Filament Mapbox Laravel Package

Getting Started

This package v3.0.0 is a Filament plugin that has been upgraded to target Filament v5. Before installing, confirm your application already runs Filament v5 (composer show filament/filament should report a 5.x version). If you are still on Filament v4, stay on the previous major version of this package.

Minimal steps:

1. Require the package: composer require speniti/<package-name> (use the exact package name from Packagist; the release notes only reference the vendor speniti).
2. Publish any config or assets if the package provides them: php artisan vendor:publish --tag=<package>-config (check the README for the exact tag).
3. Register the plugin in your Filament panel provider (e.g. app/Providers/Filament/AdminPanelProvider.php):

   ->plugin(\Speniti\<Package>\<Package>Plugin::make())
   

   The plugin class name is typically documented in the package README; look for a class ending in Plugin.
4. Clear caches: php artisan optimize:clear and php artisan filament:cache-components if you use component caching.

Where to look first:

• README.md for installation and the plugin registration snippet.
• src/ for the plugin class and any field/widget/resource classes you will use.
• config/<package>.php (if published) for default options.
• The package's composer.json to confirm the filament/filament constraint is ^5.0.

First use case: add the package's primary component (field, widget, or resource) to an existing Filament resource. For example, if it provides a form field, add it to your Resource::form() schema; if it provides a widget, register it in the panel's widgets() array. Use the package's demo or README example as a starting point, then adapt the configuration to your model.

Implementation Patterns

Day-to-day usage typically follows the standard Filament plugin workflow:

• Panel-level registration: Register the plugin once in each panel where it should be available. If you have multiple panels (admin, vendor, etc.), decide whether the plugin should be global or panel-specific.
• Resource integration: Add the package's fields/widgets/resources to your existing Filament resources. Keep the package's configuration array close to the component definition so overrides are obvious.
• Configuration overrides: Publish the config file and override defaults in config/<package>.php. Prefer environment variables for values that differ between local and production (e.g. API keys, feature flags).
• Customization via extension points: If the package exposes custom field/widget classes or view components, extend them rather than editing vendor files. Publish views (php artisan vendor:publish --tag=<package>-views) when you need to change markup.
• Testing workflow: Write a feature test that boots a Filament panel and renders a resource containing the package's component. Use Filament's testing helpers (livewire(), assertFormExists(), etc.) to catch regressions early, especially after upgrading Filament.
• Upgrade workflow: Because v3.0.0 is a breaking release tied to Filament v5, treat the upgrade as a two-step process: first upgrade Filament to v5 and fix any Filament-level deprecations, then upgrade this package. Run your test suite after each step.

Integration tips:

• If the package provides a resource, you can extend it in your own resource class to add authorization, navigation labels, or custom actions without forking.
• Use Filament's ->visible() and ->hidden() callbacks on the package's components to conditionally show them based on user roles or feature flags.
• For widgets, override getStats() or similar methods in a subclass if the package allows it; otherwise use the package's configuration options.

Gotchas and Tips

• Breaking change: Filament v5 required. v3.0.0 will not work with Filament v4 or earlier. If you cannot upgrade Filament yet, pin the package to its previous major version (^2.0 or whatever the last v4-compatible release was). Do not mix Filament v4 and v5 packages in the same project.
• Check transitive Filament dependencies: Other Filament plugins in your project must also be v5-compatible. Run composer why-not filament/filament 5.* to identify blockers before upgrading.
• Plugin registration is easy to miss: If the package's components do not appear, confirm the plugin is registered in the correct panel provider. Filament caches panel components; run php artisan filament:cache-components after changes, or php artisan optimize:clear during development.
• Config caching: After publishing config, run php artisan config:clear (or optimize:clear) in development. In production, remember to re-cache config after deployment.
• View publishing: Published views can become stale after a major upgrade. Compare your published views with the package's updated views and re-publish if necessary. Keep a diff or use version control to track local modifications.
• Debugging: If a component fails to render, check the Laravel log and the browser console. Filament v5 may have changed asset registration; ensure you have run php artisan filament:assets if the package ships assets. Use php artisan about to confirm Filament version and panel configuration.
• Extension points: Prefer the package's documented extension points (custom classes, macros, events) over modifying vendor code. If the package does not expose an extension point you need, open an issue or use a decorator pattern around the package's service.
• Upgrade testing: After upgrading to v3.0.0, test all panels that use the package, not just the default one. Pay attention to authorization policies and navigation registration, as Filament v5 may have changed defaults.