Filament Simple Role Permission Laravel Package

Getting Started

Install and confirm the constraint actually moved. The only substantive change in 0.0.5 is Laravel 12 support, so the first job is verifying how that support was added:

composer require vendor/package:^0.0.5
composer why-not illuminate/support 12   # should return nothing

Then open the package's composer.json and check require. If 0.0.5 widened the constraint (e.g. illuminate/support: ^10.0|^11.0|^12.0), you can upgrade in place on existing Laravel 10/11 apps. If it bumped it to ^12.0 only, then 0.0.5 is a Laravel-12-only release and Laravel 10/11 apps must stay on 0.0.4 — that is the single most important thing to determine before touching composer.lock. Also confirm the PHP floor (^8.2 is the Laravel 12 baseline).

Where to look first, in order:

1. README.md install/usage section — but treat any Laravel 11-era instructions with suspicion (see Gotchas).
2. src/*ServiceProvider.php — register() shows container bindings, boot() shows publishes, commands, routes, migrations.
3. config/<package>.php — the real surface area; the config keys usually map 1:1 to features.
4. routes/, database/migrations/, src/Console/ — tells you whether it hooks HTTP, the DB, or the scheduler.

First use case. Get one end-to-end path working before designing anything around it:

php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
# set env vars, then:
php artisan config:clear && php artisan package:discover
php artisan tinker   # resolve the binding, call one method

If the package exposes a command, run it with -vvv first — it exercises the full bootstrap path (config, bindings, container, migrations) in one step and fails loudly.

Implementation Patterns

Config-driven, not code-driven. Publish the config file, commit it, and drive every environment difference through env() in .env. Resist editing the class or hardcoding constructor args — at 0.0.x you want your customization to live in a file you can diff against the upstream version on every bump.

Resolve from the container; keep the facade for terse call sites. If the service provider binds an interface, type-hint the interface in your own classes rather than calling Package::method() statically. That single choice is what makes the package swappable and testable later.

Wrap it behind a thin adapter. At 0.0.5 there is no backwards-compatibility promise. Put a one-class seam between your application and the package:

final class MyIntegration
{
    public function __construct(private \Vendor\Package\Client $client) {}
    public function doTheThing(array $payload): Result { /* translate + call */ }
}

When 0.0.6 renames a method, you edit one file instead of grepping the codebase.

Use it in tests as a seam, not a dependency. Bind a fake in your test case rather than hitting the real thing:

$this->swap(\Vendor\Package\Client::class, new FakeClient());

If the package dispatches jobs or makes HTTP calls, pair this with Queue::fake() / Http::fake() and assert on what your code dispatched — this keeps your suite green across package upgrades.

Add a Laravel 12 job to CI, keep one on the lowest supported version. The whole point of 0.0.5 is framework compatibility, so pin the matrix explicitly (laravel/framework: ^11.0 and ^12.0) with --prefer-lowest on at least one job. This is how you find out that a transitive dependency silently blocks the upgrade, before your users do.

Adopt incrementally behind a flag. For a pre-1.0 package, wire the integration for one feature first, ship it, and only then broaden usage. It costs an extra config key and buys you a clean rollback.

Gotchas and Tips

^0.0.5 does not mean "0.0.5 and up." For 0.0.x versions, Composer's caret operator is equivalent to >=0.0.5 <0.0.6 — you get exactly one patch. If you want to absorb fixes without editing composer.json, use ~0.0.5 (allows 0.0.x) or 0.0.*, and accept that 0.x has no stability guarantees. Whichever you choose, commit composer.lock.

Laravel 11/12 changed where things get registered. Manual provider registration goes in bootstrap/providers.php, not config/app.php. Middleware and routing configuration live in bootstrap/app.php, not app/Http/Kernel.php. Any README snippet referencing Kernel.php is stale for your app even if the package code is fine — translate it rather than pasting it.

Stale published config after an upgrade. vendor:publish will not overwrite an existing config file without --force, which is usually what you want — but it means a new config key added in 0.0.5 can be silently missing. After every bump, diff the published file against vendor/vendor/package/config/<package>.php and merge new keys in. Missing keys are the #1 cause of "the new version behaves identically to the old one."

Config cache hides your .env. If the package reads config('package.key') and you cached config before setting the env var, the change appears to be ignored. Sequence matters: set env → php artisan config:clear → retest. Same story with package:discover after adding a provider.

Debugging a boot-time failure. A package that throws during register()/boot() breaks every artisan command, including config:clear. Workarounds: temporarily comment out the provider in bootstrap/providers.php, use php artisan about to confirm what actually loaded, or composer dump-autoload and run a bare php -r "require 'vendor/autoload.php';" to isolate. For runtime issues, Event::listen('*', ...) in AppServiceProvider often reveals whether the package's events are even firing.

Check the transitive tree when the upgrade stalls. composer why-not illuminate/support 12 and composer outdated --direct will usually name the real blocker — it is often a dev dependency or a database driver, not the package you're trying to upgrade.

Extension points worth knowing before you fork. In rough order of preference: container rebinding an interface, extend() on a manager/driver registry, publishable stubs or views, custom driver registration, and only then subclassing. Forking a 0.0.x package is a maintenance tax you should avoid until the API stabilizes at 1.0.