Manual Authentication Bundle Laravel Package

Getting Started

Install the package with Composer and let Laravel's package discovery register the service provider:

composer require vendor/package

Publish any shipped configuration and migrations, then review what was published before running them:

php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"
php artisan migrate

Where to look first:

1. The package's README and CHANGELOG for the supported Laravel/PHP versions.
2. The published config/package.php — this is usually the fastest way to understand the package's moving parts and defaults.
3. The service provider's register() and boot() methods if you need to know what gets bound into the container and which hooks are fired.

First use case: wire the package into a single, low-risk entry point — a console command, a queued job, or one controller action — and confirm it works end to end. Don't roll it out across the whole app until you've verified the happy path in isolation.

Implementation Patterns

Resolve from the container, don't instantiate directly. Bindings and singletons are registered by the service provider. Type-hint the package's contracts in constructors so tests can swap in fakes:

public function __construct(private PackageContract $package) {}

Wrap third-party calls behind a thin adapter. Rather than scattering package calls across your domain, expose a small interface in your app and implement it with the package. If the package is swapped or upgraded, only one class changes.

Use events and extension points over forking. Most packages fire events or expose macroable classes. Listen to those instead of editing vendor code — changes under vendor/ are lost on composer update.

Configuration over convention when environments differ. Keep environment-specific values (API keys, endpoints, timeouts, queue names) in config/package.php reading from env(), and cache config in production:

php artisan config:cache

Test with the package's fakes when provided. If the package ships a fake, bind it in setUp() so your suite doesn't hit the network. Where no fake exists, mock the contract you defined in the adapter.

Queue long-running work. Anything that calls an external service should go through a job with retries and a timeout, not a synchronous request path.

Gotchas and Tips

• Config caching bites after deploy. If you change config/package.php on a server with cached config, the change won't take effect until php artisan config:cache is re-run. Add it to your deploy script.
• Publish tags matter. vendor:publish without a --tag publishes everything, which can overwrite local edits. Run php artisan vendor:publish --list (or check the README) first and publish only what you need.
• Version constraints are loose in Laravel packages. A minor bump can pull in a transitive dependency that breaks things. Read the CHANGELOG before composer update and pin the major version in composer.json.
• Service provider ordering. If your own provider depends on the package's bindings, register yours after it. In bootstrap/providers.php, order is significant for deferred providers.
• Facades resolve lazily. A facade that works in a controller can fail in a queued job if the container isn't booted the same way. Prefer constructor injection in jobs.
• Debugging: start with php artisan about, then check storage/logs/laravel.log. For binding issues, php artisan tinker and app()->make(YourContract::class) quickly confirms whether the container is wired up. Set APP_DEBUG=true locally only.
• Extension points: look for Macroable, published config, events, and interfaces in the package's Contracts directory. These are the supported seams — anything else is internal and can change without notice.
• Migrations: if the package publishes migrations, never edit them after they've run in production. Publish a new migration in your app if you need schema changes.