Filament Address Pro

Appearance

API Reference ​

Last updated: 2026-03-22

Quick reference for key classes, methods, and interfaces in Filament Address Pro.

Table of Contents ​

Models ​

Address ​

Location: Models\Address

Polymorphic address model with verification tracking.

Properties ​

php
// Primary key
string $id                        // ULID

// Polymorphic relationship
string $addressable_type
string $addressable_id

// Label
?string $label                    // Home, Work, Billing, Shipping, etc.

// Country and subdivisions
string $country_code              // ISO 2-letter code
?string $administrative_area_id   // State/province ULID
?string $administrative_area      // Text fallback
?string $locality_id              // City ULID
string $locality                  // City or town name
?string $dependent_locality_id    // District ULID
?string $dependent_locality       // Ward, neighborhood, or suburb

// Street address
string $address_line_1            // Required, max 255 chars
?string $address_line_2           // Optional, max 100 chars
?string $postal_code

// Additional fields
?string $bldg                     // Building or company name
?string $box                      // PO Box number
?string $ico                      // In care of recipient

// Geographic coordinates
?float $lat                       // Latitude
?float $lon                       // Longitude

// Status flags
bool $is_primary                  // One per entity (default: false)
bool $is_verified                 // Verified by an external service (default: false)
bool $needs_review                // Verification found suggested changes pending user review (default: false)

// Verification tracking
?string $verification_provider    // usps, google, smarty
?Carbon $verified_at              // When verification occurred
?array $verification_metadata     // Raw response + context (e.g. ['context' => 'map_selection'])

// Quality
?int $quality_score               // 0–100 (auto-calculated on save)

// Timestamps
Carbon $created_at
Carbon $updated_at

Relationships ​

php
// Polymorphic relationship to owner (User, Customer, etc.)
public function addressable(): MorphTo

// Country relationship
public function country(): BelongsTo

// Subdivision relationships
public function administrativeArea(): BelongsTo
public function locality(): BelongsTo
public function dependentLocality(): BelongsTo

Scopes ​

php
// Verification
Address::verified()->get();                    // is_verified = true
Address::unverified()->get();                  // is_verified = false
Address::verifiedBy('usps')->get();            // verified by specific provider

// Review workflow
Address::where('needs_review', true)->get();   // pending user review

// Quality
Address::whereQuality('excellent')->get();     // excellent, good, fair, poor, very_poor
Address::minimumQuality(60)->get();            // quality_score >= 60
Address::needsQualityImprovement()->get();     // quality_score < 60 (configurable threshold)

Methods ​

php
// Check if address is verified
public function isVerified(): bool

// Mark address as verified
public function markAsVerified(
    string $provider,
    ?array $metadata = null
): self

// Get formatted address (international format)
public function getFormattedAttribute(): string

// Get formatted address (domestic format)
public function getFormattedLocalAttribute(): string

Example Usage ​

php
use Viewflex\FilamentAddress\Models\Address;

// Create an address
$address = Address::create([
    'addressable_type' => 'App\Models\User',
    'addressable_id' => 1,
    'country_code' => 'US',
    'address_line_1' => '1600 Pennsylvania Ave NW',
    'locality' => 'Washington',
    'administrative_area' => 'District of Columbia',
    'postal_code' => '20500',
    'lat' => 38.8977,
    'lon' => -77.0365,
    'is_primary' => true,
]);

// Mark as verified
$address->markAsVerified('usps', [
    'delivery_point' => 'confirmed',
    'dpv_match' => 'Y',
]);

// Get formatted address
echo $address->formatted; // International format with country
echo $address->formatted_local; // Domestic format without country

Country ​

Location: Models\Country

Country with subdivisions and address definition.

Properties ​

php
string $code                      // ISO 2-letter code
string $name                      // Full country name
?string $iso3                     // ISO 3-letter code
?string $numeric_code             // ISO numeric code
?string $phone_code              // International dialing code
?string $capital
?string $currency
?string $currency_name
?string $currency_symbol
?string $tld                      // Top-level domain
?string $region                   // Geographic region
?string $subregion
bool $is_sovereign                // vs. territory
?string $parent_code              // For territories

Relationships ​

php
// Country's subdivisions (states, provinces)
public function subdivisions(): HasMany

// Active subdivisions only
public function activeSubdivisions(): HasMany

// Address definition (format configuration)
public function addressDefinition(): HasOne

// Parent country (for territories)
public function parent(): BelongsTo

// Territory relationships
public function territories(): HasMany

// Country groups (EU, ASEAN, etc.)
public function groups(): BelongsToMany

Methods ​

php
// Get actual subdivision depth (1, 2, or 3)
public function getActualSubdivisionDepth(): int

// Get subdivision counts by level
public function getSubdivisionCountsByLevel(): array

Services ​

GeocodingService ​

Location: Viewflex\FilamentAddress\Services\GeocodingService

Main service for geocoding and address component extraction.

Constructor ​

php
public function __construct(
    AddressVerificationService $verificationService,
    AddressExtractorRegistry $extractorRegistry
)

Methods ​

geocode() ​

Forward geocoding: converts address to coordinates and components.

php
public function geocode(string $address, string $countryCode): array

// Parameters:
// - $address: Full address string
// - $countryCode: ISO 2-letter country code

// Returns:
[
    'success' => bool,
    'lat' => ?float,
    'lon' => ?float,
    'formatted_address' => ?string,
    'components' => [
        'address_line_1' => string,
        'address_line_2' => ?string,
        'city' => string,
        'state' => string,
        'state_abbr' => ?string,
        'postal_code' => string,
        'country_code' => string,
        'dependent_locality' => ?string,
        'is_verified' => bool,
        'verification_provider' => ?string,
        'verified_at' => ?string,
        'verification_metadata' => ?array,
    ],
    'error' => ?string,
]

Example:

php
$geocoder = app(GeocodingService::class);
$result = $geocoder->geocode('1600 Pennsylvania Ave NW', 'US');

if ($result['success']) {
    $address = Address::create([
        'country_code' => $result['components']['country_code'],
        'address_line_1' => $result['components']['address_line_1'],
        'locality' => $result['components']['city'],
        'administrative_area' => $result['components']['state'],
        'postal_code' => $result['components']['postal_code'],
        'lat' => $result['lat'],
        'lon' => $result['lon'],
        'is_verified' => $result['components']['is_verified'],
        'verification_provider' => $result['components']['verification_provider'],
    ]);
}
reverseGeocode() ​

Reverse geocoding: converts coordinates to address.

php
public function reverseGeocode(float $lat, float $lon): array

// Parameters:
// - $lat: Latitude
// - $lon: Longitude

// Returns: Same structure as geocode()

Example:

php
$result = $geocoder->reverseGeocode(38.8977, -77.0365);

if ($result['success']) {
    echo "Address: " . $result['formatted_address'];
    echo "City: " . $result['components']['city'];
    echo "Country: " . $result['components']['country_code'];
}
extractComponents() ​

Extract address components from Google's address_components array.

php
public function extractComponents(
    array $addressComponents,
    string $countryCode
): array

// Uses country-specific extractors:
// - JapaneseAddressExtractor for JP
// - GreeceAddressExtractor for GR
// - ConfigBasedAddressExtractor for KR, CN
// - DefaultAddressExtractor for all others

CountryService ​

Location: Services\CountryService

Static utility methods for country and address operations.

Methods ​

validatePostalCode() ​

Validate a postal code against a regex pattern. Pass the pattern from CountryAddressDefinition::postal_code_regex.

php
public static function validatePostalCode(
    ?string $pattern,
    ?string $postalCode
): bool

// Examples:
$pattern = Country::where('iso2', 'US')->first()->addressDefinition->postal_code_regex;
CountryService::validatePostalCode($pattern, '20500');   // true
CountryService::validatePostalCode($pattern, 'invalid'); // false

// Returns true when pattern is null (country has no postal code format constraint)
CountryService::validatePostalCode(null, 'anything');    // true
getAdministrativeAreaOptions() ​

Get state/province options for dropdown.

php
public static function getAdministrativeAreaOptions(
    string $countryCode
): array

// Returns: ['ulid' => 'State Name', ...]

$states = CountryService::getAdministrativeAreaOptions('US');
// ['01K7MTQ...' => 'New York', '01K7MTR...' => 'California', ...]
getLocalityOptions() ​

Get city options for dropdown.

php
public static function getLocalityOptions(
    string $countryCode,
    ?string $administrativeAreaId = null
): array

// Returns cities for given state/province
$cities = CountryService::getLocalityOptions('US', $stateId);
getDependentLocalityOptions() ​

Get district/neighborhood options.

php
public static function getDependentLocalityOptions(
    string $countryCode,
    ?string $localityId = null
): array
formatAddress() ​

Format address in international format (with country).

php
public static function formatAddress(
    string $countryCode,
    array $addressData
): string

// $addressData supports these fields:
// - first_name: Recipient first name
// - last_name: Recipient last name
// - organization: Organization/company name
// - address_line_1: Street address (required)
// - address_line_2: Apartment, suite, etc. (optional)
// - postal_code: ZIP/postal code
// - administrative_area: State/province name or ID
// - locality: City name or ID
// - dependent_locality: District/neighborhood name or ID
// - bldg: Building number
// - box: PO Box
// - ico: In care of

// Example:
$formatted = CountryService::formatAddress('US', [
    'first_name' => 'John',
    'last_name' => 'Smith',
    'address_line_1' => '1600 Pennsylvania Ave NW',
    'locality' => 'Washington',
    'administrative_area' => 'District of Columbia',
    'postal_code' => '20500',
]);

// Output:
// John Smith
// 1600 Pennsylvania Ave NW
// Washington, District of Columbia 20500
// UNITED STATES
formatAddressLocal() ​

Format address in domestic format (without country).

php
public static function formatAddressLocal(
    string $countryCode,
    array $addressData
): string

// Same parameters as formatAddress()

// Example output:
// John Smith
// 1600 Pennsylvania Ave NW
// Washington, DC 20500

AddressProcessingService ​

Location: Viewflex\FilamentAddress\Services\AddressProcessingService

High-level service for processing addresses with batch support.

Methods ​

processFromAddress() ​

Process address from text input with geocoding and verification.

php
public function processFromAddress(
    array $addressData
): AddressProcessingResult

// Parameters:
// - $addressData: Array with address_line_1, locality, administrative_area, postal_code, country_code

// Returns: AddressProcessingResult with success, components, metadata
processFromCoordinates() ​

Process address from coordinates (reverse geocoding).

php
public function processFromCoordinates(
    float $lat,
    float $lon
): AddressProcessingResult
processFromPlace() ​

Process address from Google Places selection.

php
public function processFromPlace(
    array $placeData
): AddressProcessingResult

// Parameters:
// - $placeData: Array from Google Places API (name, lat, lon, postal_code, etc.)
processBatch() ​

Process multiple addresses with rate limiting.

php
public function processBatch(
    array $addresses,
    ?callable $progressCallback = null,
    int $delayMs = 100
): array

// Example:
$results = $processor->processBatch(
    addresses: $addressList,
    progressCallback: function ($current, $total, $result) {
        echo "Processing {$current}/{$total}...\n";
    },
    delayMs: 200 // Respect API rate limits
);
getBatchStatistics() ​

Get statistics from batch processing results.

php
public function getBatchStatistics(array $results): array

// Returns:
[
    'total' => int,
    'successful' => int,
    'failed' => int,
    'verified' => int,
    'success_rate' => float,
    'verification_rate' => float,
]

Traits ​

HasAddresses ​

Location: Viewflex\FilamentAddress\Concerns\HasAddresses

Add to models that have addresses.

Methods ​

php
// Relationship to all addresses
public function addresses(): MorphMany

// Get primary address
public function primaryAddress(): ?Address

// Get verified addresses only
public function verifiedAddresses(): Collection

// Check if has primary address
public function hasPrimaryAddress(): bool

// Check if has any verified addresses
public function hasVerifiedAddresses(): bool

// Set an address as primary (clears other primary flags)
public function setPrimaryAddress(Address $address): void

Example ​

php
use Viewflex\FilamentAddress\Concerns\HasAddresses;

class User extends Authenticatable
{
    use HasAddresses;
}

// Usage
$user = User::find(1);
$primary = $user->primaryAddress();
$verified = $user->verifiedAddresses();

if ($user->hasPrimaryAddress()) {
    echo "Primary: " . $primary->formatted;
}

// Set new primary
$newAddress = $user->addresses()->first();
$user->setPrimaryAddress($newAddress);

Filament Components ​

AddressForm ​

Location: Viewflex\FilamentAddress\Filament\Schemas\AddressForm

Complete address form schema with all features.

Methods ​

php
// Get full address form schema
public static function schema(): array

// Returns array of Filament form components:
// - Country select
// - Address search field with Places autocomplete + map preview (if enabled)
// - Address line 1 & 2
// - State/city/district dropdowns (country-dependent)
// - Postal code
// - Additional fields (bldg, box, ico)
// - Live preview section

Example ​

php
use Viewflex\FilamentAddress\Filament\Schemas\AddressForm;
use Filament\Forms\Form;

public static function form(Form $form): Form
{
    return $form->schema([
        ...AddressForm::schema(),
    ]);
}

AddressesRelationManager ​

Location: Viewflex\FilamentAddress\Filament\RelationManagers\AddressesRelationManager

Complete address management interface for Filament resources.

Features ​

  • Create/edit/delete addresses
  • Set primary address
  • View verification status
  • Search and filter
  • Bulk actions

Example ​

php
use Viewflex\FilamentAddress\Filament\RelationManagers\AddressesRelationManager;

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

Verification ​

AddressVerificationService ​

Location: Services\Verification\AddressVerificationService

Main verification service managing multiple providers.

Methods ​

php
// Verify an address
public function verify(
    array $address,
    ?string $providerName = null
): VerificationResult

// Register a custom provider
public function registerProvider(VerificationProvider $provider): void

// Get all registered providers
public function getProviders(): array

// Get provider for specific country
public function getProviderForCountry(string $countryCode): ?VerificationProvider

VerificationResult ​

Location: Services\Verification\VerificationResult

Standardized verification result.

Methods ​

php
// Check if verification was successful
public function isSuccessful(): bool

// Get provider name
public function getProvider(): ?string

// Should fall back to geocoding?
public function shouldFallbackToGeocoding(): bool

// Get error message
public function getError(): ?string

// Get all components
public function getComponents(): ?array

// Get metadata
public function getMetadata(): ?array

// Convenience methods
public function getAddressLine1(): ?string
public function getAddressLine2(): ?string
public function getCity(): ?string
public function getState(): ?string
public function getPostalCode(): ?string
public function getCountryCode(): ?string
public function getDistrict(): ?string
public function getLatitude(): ?float
public function getLongitude(): ?float

// Static factory methods
public static function success(
    string $provider,
    array $components,
    ?array $metadata = null
): self

public static function failure(
    string $provider,
    string $error,
    bool $shouldFallbackToGeocoding = true
): self

VerificationProvider Interface ​

Location: Services\Verification\VerificationProvider

Interface for custom verification providers.

php
interface VerificationProvider
{
    // Verify an address
    public function verify(array $address): VerificationResult;

    // Check if provider supports country
    public function supportsCountry(string $countryCode): bool;

    // Get provider name
    public function getName(): string;

    // Check if provider is properly configured
    public function isConfigured(): bool;
}

Extractors ​

AddressExtractorRegistry ​

Location: Viewflex\FilamentAddress\Services\Geocoding\AddressExtractorRegistry

Manages address component extractors with priority system.

Methods ​

php
// Register an extractor
public function register(
    AddressComponentExtractorInterface $extractor
): self

// Get extractor for country (highest priority wins)
public function getExtractor(string $countryCode): ?AddressComponentExtractorInterface

// Clear all extractors
public function clear(): self

AddressComponentExtractorInterface ​

Location: Viewflex\FilamentAddress\Services\Geocoding\Contracts\AddressComponentExtractorInterface

Interface for address component extractors.

php
interface AddressComponentExtractorInterface
{
    // Check if extractor supports country
    public function supports(string $countryCode): bool;

    // Get priority (higher = preferred)
    // - 100: Custom extractors (JapaneseAddressExtractor)
    // - 50: Config-based extractors
    // - 0: Default extractor (fallback)
    public function getPriority(): int;

    // Extract components from Google's address_components
    public function extract(array $addressComponents): array;
}

Built-in Extractors ​

DefaultAddressExtractor ​

  • Priority: 0 (fallback)
  • Supports: All countries
  • Format: Western/standard (street_number + route)

JapaneseAddressExtractor ​

  • Priority: 100
  • Supports: JP (Japan)
  • Format: Hierarchical (premise + sublocality levels)

GreeceAddressExtractor ​

  • Priority: 100
  • Supports: GR (Greece)
  • Format: Maps Google's non-standard admin levels to the correct Regional Unit / Municipality hierarchy

ConfigBasedAddressExtractor ​

  • Priority: 50
  • Supports: Countries configured in config/addresses.php
  • Format: Defined in configuration

Example custom extractor:

php
use Viewflex\FilamentAddress\Services\Geocoding\Contracts\AddressComponentExtractorInterface;

class AustralianAddressExtractor implements AddressComponentExtractorInterface
{
    public function supports(string $countryCode): bool
    {
        return $countryCode === 'AU';
    }

    public function getPriority(): int
    {
        return 75; // Between config-based and custom
    }

    public function extract(array $addressComponents): array
    {
        // Custom extraction logic for Australian addresses
        $address = [];

        foreach ($addressComponents as $component) {
            if (in_array('street_number', $component['types'])) {
                $address['street_number'] = $component['long_name'];
            }
            // ... more extraction logic
        }

        return $address;
    }
}

// Register in service provider
$registry = app(AddressExtractorRegistry::class);
$registry->register(new AustralianAddressExtractor());

Configuration Reference ​

All configuration options in config/addresses.php:

php
return [
    // Google Maps API Keys — see CONFIGURATION-GUIDE.md for two-key security setup
    'google_maps_api_key'     => env('GOOGLE_MAPS_API_KEY'),           // single-key fallback
    'google_maps_server_key'  => env('GOOGLE_MAPS_SERVER_KEY', env('GOOGLE_MAPS_API_KEY')),
    'google_maps_browser_key' => env('GOOGLE_MAPS_BROWSER_KEY', env('GOOGLE_MAPS_API_KEY')),

    // Verification settings
    'verification' => [
        'enabled'           => env('ADDRESS_VERIFICATION_ENABLED', true),
        'provider'          => env('ADDRESS_VERIFICATION_PROVIDER', 'auto'),
        'mode'              => env('ADDRESS_VERIFICATION_MODE', 'interactive'), // interactive|silent
        'provider_priority' => ['usps', 'smarty', 'google'],  // config-only, no env var
        'country_providers' => [
            'US' => 'usps',
        ],
        'fallback_to_geocoding' => true,
        'cache_ttl' => env('ADDRESS_VERIFICATION_CACHE_TTL', 86400),
    ],

    // Blur geocoding (auto-complete on tab/blur)
    'blur_geocoding' => [
        'enabled'              => env('ADDRESS_BLUR_GEOCODING_ENABLED', true),
        'min_length'           => env('ADDRESS_BLUR_MIN_LENGTH', 10),
        'skip_if_verified'     => env('ADDRESS_BLUR_SKIP_IF_VERIFIED', true),
        'debounce_ms'          => env('ADDRESS_BLUR_DEBOUNCE_MS', 0),
        'detect_paste'         => env('ADDRESS_BLUR_DETECT_PASTE', true),
        'require_completeness' => env('ADDRESS_BLUR_REQUIRE_COMPLETENESS', 'any'),
        // Options: 'any', 'basic' (city OR postal), 'complete' (city AND state)
        'smart_detection_level' => env('ADDRESS_BLUR_SMART_DETECTION', 'basic'),
        // Options: 'basic', 'smart' (0.60 threshold), 'aggressive' (0.80 threshold)
    ],

    // UI settings
    'filament' => [
        'enable_preview'    => env('ADDRESS_FORM_PREVIEW', true),
        'enable_map'        => env('ADDRESS_FORM_MAP', true),
        'input_mode'        => env('ADDRESS_INPUT_MODE', 'auto'), // auto|autocomplete|geocoding|manual
        'register_resource' => env('ADDRESS_RESOURCE_ENABLED', false),
    ],

    // Component extraction for international addresses
    'component_extraction' => [
        'KR' => [
            'address_line_1' => ['premise', 'sublocality_level_4', 'sublocality_level_3'],
            'separator' => ' ',
        ],
        'CN' => [
            'address_line_1' => ['premise', 'sublocality_level_5', 'sublocality_level_4'],
        ],
    ],
];

For more details, see:

Built with ❤️ by Viewflex

Released under a commercial license.

Copyright © 2025–present Viewflex