Setting Up the Full Addressing Panel

Last updated: 2026-05-13

This guide walks through adding the complete addressing interface to your Filament panel — the same experience as the package demo.

What You'll Get

Resources (navigation group: "Address API"):

Address Manager - global table of all addresses across your app, with search, filters, import/export, and inline verification
API Cache Viewer - browse cached geocoding/verification results, view hit rates, clear expired entries
API Audit Log - full history of API calls with costs, provider, response times, and cache savings

Dashboard Widgets:

Address Stats - total/verified/needs-review counts with quality score subtitle and deep-link to filtered address list
API Costs - monthly spend, cache hits, and savings across all configured providers
USPS Rate Limit Monitor - real-time US quota usage with progress bar and alerts
Smarty Usage Monitor - monthly US and International lookup usage with per-section quota tracking

Prerequisite: FilamentUser

Filament requires your User model to implement FilamentUser before any panel will grant access. Without it, all users get a 403. Add it once — it applies to all options below:

php

use Filament\Models\Contracts\FilamentUser;
use Filament\Panel;

class User extends Authenticatable implements FilamentUser
{
    public function canAccessPanel(Panel $panel): bool
    {
        return true; // or restrict: $this->is_admin, str_ends_with($this->email, '@yourcompany.com'), etc.
    }
}

Option 0: One Command (Recommended)

The fastest path. Run the install wizard and answer a few prompts:

bash

php artisan addresses:install

It will ask which panel approach you want, register the provider in bootstrap/providers.php, update your .env, and optionally run migrations and seed country data. Done.

Option 1: One Line (Zero Maintenance)

Add a single entry to bootstrap/providers.php:

php

return [
    App\Providers\AppServiceProvider::class,
    Viewflex\FilamentAddress\Filament\AddressingPanelProvider::class,  // ← add this
];

Then set in .env:

env

ADDRESS_PANEL_ID=addressing
ADDRESS_PANEL_PATH=addressing

Visit /addressing - the panel is live. Because the provider lives inside the package, it auto-updates with every composer update - resources, widgets, and fixes included.

To customize colors, auth, or middleware, use Option 2 instead.

Option 2: Add to Your Existing Panel

The simplest path - two additions to your panel provider:

php

// app/Providers/Filament/AdminPanelProvider.php
use Viewflex\FilamentAddress\FilamentAddressServiceProvider;

public function panel(Panel $panel): Panel
{
    return $panel
        ->id('admin')
        ->path('admin')
        ->resources([
            // Your existing resources...
            UserResource::class,
            CustomerResource::class,

            // Add all three package resources
            ...FilamentAddressServiceProvider::getResources(),
        ])
        ->widgets([
            AccountWidget::class,

            // Add package dashboard widgets
            ...FilamentAddressServiceProvider::getWidgets(),
        ]);
}

Then update your .env to tell the package which panel it's running in:

env

ADDRESS_PANEL_ID=admin
ADDRESS_PANEL_PATH=admin

Done. Your panel now has /admin/addresses, /admin/address-api-cache, /admin/address-api-audit-log, and four dashboard widgets.

Option 3: Dedicated `/addressing` Panel (Customizable Copy)

Publish a customizable copy of the panel provider to your app. You own the file, set your own colors, brand, auth guards, and middleware. For full CSS control, add ->viteTheme('resources/css/filament/addressing-theme.css') to the panel chain.

bash

php artisan vendor:publish --tag=filament-address-pro-panel

This creates app/Providers/Filament/AddressingPanelProvider.php. Then register it and configure .env as shown below.

Note: Unlike Option 1, your published copy is not updated when you upgrade the package. You own it. The underlying resources and widgets (which live in the package) still update automatically.

Manual: Create the Panel Provider

Alternatively, create app/Providers/Filament/AddressingPanelProvider.php by hand:

php

<?php

namespace App\Providers\Filament;

use Filament\Http\Middleware\Authenticate;
use Filament\Http\Middleware\AuthenticateSession;
use Filament\Http\Middleware\DisableBladeIconComponents;
use Filament\Http\Middleware\DispatchServingFilamentEvent;
use Filament\Pages\Dashboard;
use Filament\Panel;
use Filament\PanelProvider;
use Filament\Widgets\AccountWidget;
use Illuminate\Cookie\Middleware\AddQueuedCookiesToResponse;
use Illuminate\Cookie\Middleware\EncryptCookies;
use Illuminate\Foundation\Http\Middleware\VerifyCsrfToken;
use Illuminate\Routing\Middleware\SubstituteBindings;
use Illuminate\Session\Middleware\StartSession;
use Illuminate\View\Middleware\ShareErrorsFromSession;
use Viewflex\FilamentAddress\FilamentAddressServiceProvider;

class AddressingPanelProvider extends PanelProvider
{
    public function panel(Panel $panel): Panel
    {
        return $panel
            ->id('addressing')
            ->path('addressing')
            ->login()
            ->resources(FilamentAddressServiceProvider::getResources())
            ->pages([Dashboard::class])
            ->widgets([
                AccountWidget::class,
                ...FilamentAddressServiceProvider::getWidgets(),
            ])
            ->middleware([
                EncryptCookies::class,
                AddQueuedCookiesToResponse::class,
                StartSession::class,
                AuthenticateSession::class,
                ShareErrorsFromSession::class,
                VerifyCsrfToken::class,
                SubstituteBindings::class,
                DisableBladeIconComponents::class,
                DispatchServingFilamentEvent::class,
            ])
            ->authMiddleware([Authenticate::class]);
    }
}

Step 2: Register the Provider

Add to bootstrap/providers.php:

php

return [
    App\Providers\AppServiceProvider::class,
    App\Providers\Filament\AdminPanelProvider::class,
    App\Providers\Filament\AddressingPanelProvider::class,  // ← add this
];

Step 3: Configure the Package

env

ADDRESS_PANEL_ID=addressing
ADDRESS_PANEL_PATH=addressing

Visit /addressing - you'll see the full dashboard with all resources and widgets.

Option 4: Admin-Only Resources

If you want the addressing resources visible only to admins within your existing panel:

php

->resources([
    // Your standard resources (visible to all)
    ...FilamentAddressServiceProvider::getAddressResource(),

    // Admin-only resources (cache + audit log)
    ...(auth()->user()?->hasRole('admin')
        ? [
            FilamentAddressServiceProvider::getCacheResource(),
            FilamentAddressServiceProvider::getAuditLogResource(),
          ]
        : []
    ),
])

Or restrict all package resources to admins:

php

->resources(
    auth()->user()?->hasRole('admin')
        ? FilamentAddressServiceProvider::getResources()
        : []
)

Registering Individual Resources

The service provider exposes fine-grained methods if you only want specific pieces:

php

use Viewflex\FilamentAddress\FilamentAddressServiceProvider;

// All three resources
FilamentAddressServiceProvider::getResources()

// Individually
FilamentAddressServiceProvider::getAddressResource()    // AddressResource
FilamentAddressServiceProvider::getCacheResource()      // AddressCacheResource
FilamentAddressServiceProvider::getAuditLogResource()   // AddressAuditLogResource

// All widgets
FilamentAddressServiceProvider::getWidgets()

// Individual widgets
FilamentAddressServiceProvider::getAddressStatsWidget() // AddressStatsWidget
FilamentAddressServiceProvider::getApiCostsWidget()     // ApiCostsWidget
FilamentAddressServiceProvider::getRateLimitWidget()    // UspsRateLimitWidget
FilamentAddressServiceProvider::getSmartyWidget()       // SmartyUsageWidget

Note: Provider widgets (UspsRateLimitWidget, SmartyUsageWidget) only appear when the provider is both enabled and has credentials configured. You can leave credentials in place and set ADDRESS_VERIFICATION_USPS_ENABLED=false / ADDRESS_VERIFICATION_SMARTY_US_ENABLED=false to disable a provider without removing its credentials — the widget will hide automatically.

Config Reference

The ADDRESS_PANEL_ID and ADDRESS_PANEL_PATH env vars tell the package which panel it's operating in - used for redirect URLs after save/delete operations and for building links within the panel.

env

ADDRESS_PANEL_ID=addressing        # Filament panel ID (must match ->id() in your provider)
ADDRESS_PANEL_PATH=addressing      # URL path (must match ->path() in your provider)

If these don't match your panel's actual ID/path, form submissions may redirect to the wrong place.

Admin Panel Resources - detailed reference for each resource and its features
Implementation Patterns - multi-panel setups and common patterns
User Guide - how to use the address form, verification, import/export
Configuration - full list of config options

Setting Up the Full Addressing Panel ​

What You'll Get ​

Prerequisite: FilamentUser ​

Option 0: One Command (Recommended) ​

Option 1: One Line (Zero Maintenance) ​

Option 2: Add to Your Existing Panel ​

Option 3: Dedicated /addressing Panel (Customizable Copy) ​

Manual: Create the Panel Provider ​

Step 2: Register the Provider ​

Step 3: Configure the Package ​

Option 4: Admin-Only Resources ​

Registering Individual Resources ​

Config Reference ​

Related Documentation ​