Weave Code
Filament Locations Laravel Package
tomatophp/filament-locations
A FilamentPHP plugin providing a database and JSON-based location system with countries, cities, areas, languages, and currencies, complete with ready-made resources, a settings hub, and install command for quick setup.
Filament Locations is a comprehensive location database plugin for FilamentPHP, delivering countries, cities, areas, languages, and currencies out of the box. It supports both JSON-based and database-based data sources, making it easy to seed, browse, and manage geographic and locale data directly from your admin panel. Installation is quick via Composer, followed by the filament-locations:install command and registering FilamentLocationsPlugin in your panel provider.
- Prebuilt resources for countries, cities, areas, languages, and currencies
- Flexible JSON or database storage backends
- Editable records with dedicated create/edit screens
- Optional Settings Hub integration, toggleable via
settingsHub(false) - Ability to disable individual resources for tailored panels
Frequently asked questions about Filament Locations
- How do I install tomatophp/filament-locations in a Laravel app?
- Install the package with Composer using composer require tomatophp/filament-locations, then run php artisan filament-locations:install to publish config, migrations, and seeds. Register the plugin in your AdminPanelProvider with FilamentLocationsPlugin::make(). After that, run your migrations and seed the geographic and currency data.
- Which Laravel, PHP and Filament versions does filament-locations v5 support?
- v5.x requires Filament v5 with Laravel 12/13 and PHP 8.2 or higher. Filament v4 users must stay on the 4.x branch. This is a hard fork in the dependency matrix, not a soft recommendation.
- Can I use filament-locations without FilamentPHP?
- It is purpose-built for FilamentPHP and tightly coupled to it, with no standalone API or CLI surface beyond artisan commands. The data is seeded into the database or loaded from JSON, so external consumption still requires custom endpoints. If you are not using Filament, a standalone country or city package is a better fit.
- How do I attach locations to my own models like stores or warehouses?
- In v5 the Location model uses polymorphic model_type and model_id columns, so locations can attach to arbitrary domain entities such as stores, warehouses, or users. You should audit any pre-existing countries, cities, or locations tables before upgrading, and backfill the polymorphic columns with a planned data migration. Then define morph relations on your own models.
- What data does filament-locations provide out of the box?
- It provides countries, cities, areas, languages, and currencies with both JSON and database sources. The scope is geographic and currency data; it does not include time zones or postal codes, so you may need to extend the schema for those. Custom fields and regions have limited documentation.
- Is filament-locations tested and safe to use in production?
- v5 ships a full test suite covering resources, the settings page, the JSON driver, and commands, which raises confidence in upgrade safety. You should still test in staging, especially if you are re-seeding after the schema change or migrating existing production data. Geographic data may lag new countries or currencies, so plan validation.
- Why does filament-locations v5 fail to upgrade on Laravel 10 or Filament v3?
- v5.0.0 is a major-version jump that requires Filament v5, Laravel 12/13, and PHP 8.2 or higher. An in-place upgrade on Laravel 10/11 or Filament v2/v3/v4 will fail; it is a coordinated platform upgrade, not a package bump. Teams not ready should stay on the 4.x branch.
- How do I disable the settings hub or resources in filament-locations?
- You can disable the settings hub with the fluent method settingsHub(false) when registering the plugin, and resources can be disabled through the plugin or config options. Register the plugin in your AdminPanelProvider as usual. This keeps the panel UI focused on only the data you need.
- Does filament-locations slow down my app with JSON seeding?
- JSON-based seeding can slow initial database setup for large datasets, though the v5 JSON driver was reworked to avoid boot-time model instantiation. That fix improves request-time behavior, not seed throughput. For large installs, consider the database source and cache reads where appropriate.
- How do I keep country and currency data fresh, and what are the alternatives?
- There is no built-in sync mechanism, so geographic and currency refreshes are manual database updates or your own API sync. The main alternative within the package is staying on the 4.x branch if you are not on Filament v5. If you need standalone APIs, postal codes, or time zones, extend the schema or combine it with another data source.
Weaver
How can I help you explore Laravel packages today?