README

Brazilian address fields for Filament, with CEP lookup and an optional map field that ships with Mapbox and Google Maps support.

Installation

You can install the package via composer:

composer require a21ns1g4ts/filament-br-address

You can publish the config file with:

php artisan vendor:publish --tag="filament-br-address-config"

You can publish and run the migrations with:

php artisan vendor:publish --tag="filament-br-address-migrations"
php artisan migrate

Configuration

Set your preferred map provider and credentials:

FILAMENT_BR_ADDRESS_MAP_PROVIDER=mapbox
MAPBOX_ACCESS_TOKEN=

# or
FILAMENT_BR_ADDRESS_MAP_PROVIDER=google
GOOGLE_MAPS_API_KEY=

The package config also controls CEP lookup and defaults:

return [
    'address_model' => \A21ns1g4ts\FilamentBrAddress\Models\Address::class,

    'cep' => [
        'base_url' => env('FILAMENT_BR_ADDRESS_CEP_BASE_URL', 'https://brasilapi.com.br/api'),
        'timeout' => env('FILAMENT_BR_ADDRESS_CEP_TIMEOUT', 10),
        'cache_ttl' => env('FILAMENT_BR_ADDRESS_CEP_CACHE_TTL', 86400),
    ],

    'maps' => [
        'default' => env('FILAMENT_BR_ADDRESS_MAP_PROVIDER', 'mapbox'),
        'height' => env('FILAMENT_BR_ADDRESS_MAP_HEIGHT', 400),
    ],
];

Usage

Add the trait to any model that owns addresses:

use A21ns1g4ts\FilamentBrAddress\Concerns\HasAddresses;

class Customer extends Model
{
    use HasAddresses;
}

Use the default Filament schema:

use A21ns1g4ts\FilamentBrAddress\Filament\Forms\AddressForm;
use A21ns1g4ts\FilamentBrAddress\Filament\Tables\AddressTable;

AddressForm::configure();
AddressForm::configure(mapProvider: 'google');
AddressForm::configure(withMap: false);

AddressTable::getDefaultColumns();
AddressTable::getDefaultFilters();

You can also use the facade:

use A21ns1g4ts\FilamentBrAddress\Facades\FilamentBrAddress;

FilamentBrAddress::form();
FilamentBrAddress::tableColumns();
FilamentBrAddress::tableFilters();

Components

`Address`

A21ns1g4ts\FilamentBrAddress\Models\Address is the default Eloquent model for the addresses table.

It includes:

addressable_id and addressable_type morph fields.
Brazilian address fields: zip_code, street, number, neighborhood, city, state, ibge, country.
Map coordinates: lat, lng.
Address classification: type, is_default, complement.
Computed location array with lat and lng.
Computed full_address string.
CEP normalization before saving.
Default-address guard so only one address per owner is marked as default.

`HasAddresses`

Use A21ns1g4ts\FilamentBrAddress\Concerns\HasAddresses on models that own addresses:

use A21ns1g4ts\FilamentBrAddress\Concerns\HasAddresses;

class Customer extends Model
{
    use HasAddresses;
}

$customer->addresses;
$customer->defaultAddress();

If you need a custom model, change address_model in the package config.

`AddressType`

A21ns1g4ts\FilamentBrAddress\Enums\AddressType provides the default Filament labels for:

home
work
billing
shipping

`AddressForm`

A21ns1g4ts\FilamentBrAddress\Filament\Forms\AddressForm returns a ready-to-use Filament schema:

AddressForm::configure();

Available arguments:

AddressForm::configure(
    withMap: true,
    mapProvider: 'mapbox',
    mapAccessToken: 'your-mapbox-token',
    mapApiKey: null,
);

For Google Maps:

AddressForm::configure(
    mapProvider: 'google',
    mapApiKey: 'your-google-maps-key',
);

Without a map:

AddressForm::configure(withMap: false);

The form looks up Brazilian CEPs through BrasilAPI and fills street, neighborhood, city, state, ibge, and country. When the map is enabled, it dispatches geocoding updates to the map field.

`AddressMap`

A21ns1g4ts\FilamentBrAddress\Forms\Components\AddressMap is a standalone Filament field. It works with lat and lng fields in the same parent state path.

Mapbox example:

use A21ns1g4ts\FilamentBrAddress\Forms\Components\AddressMap;

AddressMap::make('location')
    ->provider('mapbox')
    ->accessToken('your-mapbox-token');

Google Maps example:

AddressMap::make('location')
    ->provider('google')
    ->apiKey('your-google-maps-key');

Other options:

AddressMap::make('location')
    ->height(480)
    ->draggable()
    ->showControls();

If you do not pass keys directly, the component reads from config('filament-br-address.maps.*').

Custom JavaScript providers can be registered with:

window.filamentBrAddressMapProviders = window.filamentBrAddressMapProviders || {}

window.filamentBrAddressMapProviders.myProvider = (config, component) => ({
    async boot() {
        // Initialize your map provider here.
    },

    async geocodeAddress(address) {
        // Geocode and call component.updateCoordinates(lat, lng).
    },
})

Then use:

AddressMap::make('location')
    ->provider('myProvider');

`AddressTable`

A21ns1g4ts\FilamentBrAddress\Filament\Tables\AddressTable exposes table defaults:

AddressTable::getDefaultColumns();
AddressTable::getDefaultFilters();

The default columns include street, number, neighborhood, city, state, ZIP code, type, and a toggle for the default address.

`CepService`

A21ns1g4ts\FilamentBrAddress\Services\CepService performs CEP lookup against BrasilAPI by default:

app(\A21ns1g4ts\FilamentBrAddress\Services\CepService::class)->get('78000000');

The service caches results using Laravel cache. You can change the base URL, timeout, and TTL in the package config.

Testing

composer test
composer test-coverage
composer phpstan
composer format

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Credits

License

The MIT License (MIT). Please see License File for more information.

a21ns1g4ts / filament-br-address

Maintainers

Package info

Fund package maintenance!

Statistics

Security