Akismet Bundle Laravel Package

Getting Started

• Install with composer require <vendor>/<package>:^1.0. The 1.0.0 tag is the first stable release, so the public API is now covered by semver — pin with ^1.0 rather than dev-main.
• Laravel package discovery should register the service provider automatically. Check bootstrap/providers.php (Laravel 11+) or config/app.php only if the provider is not listed in the package's composer.json extra.laravel.providers block — if it is, do not add it manually.
• Publish the config first: php artisan vendor:publish --tag=<package>-config. Read the published file top to bottom before touching code; most day-one questions are answered by the defaults and the inline comments rather than the README.
• Look at the package's service provider (src/<Package>ServiceProvider.php) to see what is bound into the container and under which keys. That file is the real documentation for how to override or replace behaviour.
• First use case: resolve the package's main entry point from the container (app(<Package>::class) or the injected contract) inside a single controller or artisan command, run it against your local database, and confirm the output before wiring it into anything else. Avoid Facades for this first pass — constructor injection makes it obvious what you are actually resolving.

Implementation Patterns

• Bind to the contract, not the concrete class. If the package ships an interface, add your own $this->app->bind(Contract::class, Concrete::class) in a AppServiceProvider and type-hint the interface everywhere. This is the cheapest way to swap in a fake during tests.
• Constructor injection over app() calls. Laravel resolves the package's dependencies for you; calling app() inside methods hides the dependency and makes the class untestable without booting the container.
• Config over hardcoding. Anything the package exposes in config/<package>.php should be set through config() at boot and overridden per-environment via .env. Keep a single config/<package>.php in version control and treat env() calls inside it as the only place environment variables are read.
• Queued work. If the package performs I/O (HTTP, storage, mail), wrap the call in a job so retries and timeouts apply. Resolve the package inside handle() rather than serialising it into the job payload.
• Testing. Use RefreshDatabase plus the package's own fakes if provided; otherwise bind a mock of the contract in the test's setUp(). Assert on the side effects you care about (rows written, requests sent) rather than on internal calls.
• Integration tip. Register package customisation in a dedicated PackageServiceProvider registered after the package provider, so your extend()/bind() calls win. Do not edit the vendor config file; publish and override.

Gotchas and Tips

• Symfony 6 means PHP 8.0+ and Laravel 9+. Laravel 9 ships Symfony 6 components; Laravel 8 is pinned to Symfony 5.4. On a Laravel 8 app composer require will fail on a version conflict rather than a clear message — run composer why-not <vendor>/<package> 1.0.0 to confirm the culprit before downgrading anything.
• Watch for transitive bumps. Supporting Symfony 6 can move symfony/* constraints upward across the whole dependency graph. If unrelated packages start resolving to new major versions after the update, pin them explicitly rather than letting a lockfile refresh cascade.
• 1.0.0 is a stability promise, not a feature freeze. Read the changelog for behaviour changes that landed alongside the 1.0 tag; the "Support Symfony 6" headline can hide smaller BC adjustments made in the same release.
• Config caching. php artisan config:cache freezes config(). Never call env() outside config files — it returns null once cached, which surfaces as a confusing "missing credentials" error in production only.
• Duplicate provider registration. If you previously added the provider by hand, remove it after upgrading; two registrations mean event listeners fire twice.
• Debugging order. php artisan about for versions, composer show <vendor>/<package> for the resolved constraint, php artisan tinker to app()->bound(...) and inspect the resolved instance. Most "it does nothing" reports are a mis-keyed config value or a stale config cache.
• Extension points. Prefer the package's published config and manager extend() hooks over subclassing internals. Anything under src/ without @internal is fair game; anything marked @internal will break on a minor release.