Getting Started

Welcome to Filament Address Pro. This guide helps you find the right starting point based on your situation.

---

Quick Orientation

You want to…	Start here
Install the package for the first time	INSTALLATION.md
Set up authorization / Spatie Permissions	AUTHORIZATION.md → SPATIE-PERMISSION.md
Configure the admin panel	PANEL-SETUP.md
Understand verification providers	VERIFICATION.md
Activate your license	LICENSING.md
See all configuration options	CONFIGURATION-GUIDE.md
Browse common patterns	IMPLEMENTATION-PATTERNS.md
Read the full API reference	API-REFERENCE.md
Find answers to common questions	FAQ.md

---

Installation in 5 Steps

1. Add the Anystack repository and install:

# Add to composer.json repositories array first (see INSTALLATION.md)
composer require viewflex/filament-address-pro

2. Publish config and run migrations:

php artisan vendor:publish --tag=filament-address-config
php artisan notifications:table
php artisan migrate
php artisan db:seed --class="Viewflex\FilamentAddress\Database\Seeders\CountriesDomainSeeder"

Note: php artisan notifications:table creates the standard Laravel notifications table required for bulk verification completion alerts. Skip this step if your app already has a notifications migration.

Or use the interactive wizard (does all of the above):

php artisan addresses:install

3. Add the trait to your models:

use Viewflex\FilamentAddress\Concerns\HasAddresses;

class Customer extends Model
{
    use HasAddresses;
}

4. Register the plugin on your Filament panel:

use Viewflex\FilamentAddress\FilamentAddressServiceProvider;

->resources([...FilamentAddressServiceProvider::getResources()])
->widgets([...FilamentAddressServiceProvider::getWidgets()])

5. Add to your .env:

ADDRESS_PANEL_ID=your-panel-id
ADDRESS_PANEL_PATH=your-panel-path
FILAMENT_ADDRESS_LICENSE_KEY=your-license-key

That's it. See INSTALLATION.md for full scenario-specific walkthroughs.

---

Common Scenarios

Scenario A: Full standalone address resource

Register the plugin on your panel (step 4 above). An Addresses resource appears in the nav with full CRUD, import/export, and verification.

Scenario B: Address management on an existing resource

Add AddressesRelationManager to any resource's getRelations():

use Viewflex\FilamentAddress\Filament\RelationManagers\AddressesRelationManager;

public static function getRelations(): array
{
    return [
        AddressesRelationManager::class,
    ];
}

No need to register the package's resources in your panel. The addresses tab appears inline on the resource edit page.

Scenario C: No admin panel (public-facing form)

See docs/PUBLIC-FORMS.md for embedding the address form in a Livewire component outside the Filament panel.

---

Configuration Essentials

Google Maps (optional, enables autocomplete + map preview)

# Recommended for production — separate keys with different restrictions
GOOGLE_MAPS_SERVER_KEY=your_server_key   # Geocoding, Static Maps, Address Validation — restrict to server IP
GOOGLE_MAPS_BROWSER_KEY=your_browser_key # Maps JS, Places Autocomplete — restrict to your domain

# Simple fallback — one key for everything (local dev / simple setups)
# GOOGLE_MAPS_API_KEY=your_key

Address Verification (optional)

ADDRESS_VERIFICATION_PROVIDER=auto  # auto, usps, smarty, google, none

# USPS (US addresses only)
USPS_CONSUMER_KEY=your_key
USPS_CONSUMER_SECRET=your_secret

The package works without any API keys — fields and dropdowns are fully functional, geocoding and verification are simply disabled.

---

Need Help?

• FAQ: docs/FAQ.md
• Troubleshooting: INSTALLATION.md — Troubleshooting section
• Package page: viewflex.net/packages/premium/filament-address-pro
• Contact: viewflex.net/contact