Bootstrap Bundle Laravel Package

Getting Started

Start by confirming the package is actually installed and auto-discovered before writing any code:

composer require vendor/package
php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider"

Read these three things first, in this order:

1. The service provider — vendor/vendor/package/src/*ServiceProvider.php. This tells you what is bound into the container, what is registered as a singleton, whether a facade exists, and which publishes() tags are available. It is the map of the package.
2. config/package.php (after publishing) — every default, and every value the package expects you to override. Most "it doesn't work" reports trace back to a stale published config from an older major version.
3. The README's "Usage" section only — not the whole README. Skim the changelog afterwards if you need to know what the currently-installed version supports.

First use case to validate the integration: resolve the package's main class out of the container in tinker and call the simplest public method:

app(\Vendor\Package\Client::class); // or app('package')

If that resolves and returns without throwing, the wiring, config merge, and autoloading path are all correct. Only then move on to real usage.

Implementation Patterns

Inject, don't app(). Resolve the package through constructor injection (or a typed method parameter on a controller/job) rather than the app() helper. It makes the dependency visible, keeps it mockable in tests, and means a future package swap is a one-line constructor change rather than a grep.

Bind configuration at the boundary, not at call sites. If the package needs credentials or environment-specific settings, publish the config and read from config('package.*') in your own service provider. Never call the package with hard-coded values sprinkled across the app — that is the thing that breaks in staging.

Wrap third-party calls in your own thin adapter. A small App\Services\Mailer (or similarly named) that delegates to the package gives you one place to add logging, retry, and caching without touching call sites, and gives you a seam when the package is deprecated. This is the single highest-value pattern for day-to-day leverage.

Use fakes/fixtures for the queue and HTTP paths. If the package makes outbound calls, bind it behind an interface and register a fake in tests. $this->app->instance(Contract::class, $fake) in setUp() keeps test suites fast and deterministic.

Drive it from jobs, not requests. Anything the package does that touches the network or writes more than one row belongs in a queued job. This lets you retry, and it stops a slow package call from being on the request path.

Register extension points in a dedicated provider. Custom drivers, macros, event listeners, and command registrations go in one PackageIntegrationServiceProvider rather than scattered through AppServiceProvider. It makes the dependency auditable and removable.

Gotchas and Tips

Config cache will lie to you. php artisan config:cache bakes the config at boot. Editing config/package.php afterwards has no effect until you config:clear. If a config change "isn't working," clear it before reading another line of the package source.

Published configs go stale across versions. This is the most common upgrade failure. Before upgrading, diff your published config/package.php against the package's shipped default; new keys are almost always additive and missing keys fall back silently (or, worse, throw deep inside the package). Keep a comment at the top of the file noting the version it was published at.

Auto-discovery vs. manual registration. Laravel's package discovery reads the service provider from composer.json extra.laravel. If the package "isn't there" after install, run php artisan package:discover — and check you haven't disabled discovery in the app's own composer.json.

Publish tags are not interchangeable. vendor:publish --tag=package-config and --tag=package-migrations are separate tags. Publishing everything is usually fine, but publishing only the config and then wondering why the table is missing is a classic afternoon loss.

Migration ordering. Package migrations run in filename order and are timestamped at install time. If you need to modify a package table, publish the migrations first and edit your copy — do not edit vendor/. Also note that package migrations are typically loaded by the provider, so they appear in php artisan migrate even though they are not in database/migrations/.

Facade mocking requires a swap, not a Mockery::mock(). Real facades need Facade::swap($mock) or the package's own Fake class. If shouldReceive() silently has no effect, that is why.

Serious caveat on serialization. If the package object is passed into a queued job, it must be serializable. Objects holding closures, PDO handles, or Guzzle clients will fail at dispatch time with a confusing "serialization of … is not allowed" error. Pass IDs and re-resolve inside handle().

Version pin generously but not blindly. Prefer "vendor/package": "^0.8" over "*". For pre-1.0 packages, expect breaking changes in minor releases — read the changelog before composer update, and run the full suite, not just the tests touching the package.

Extension points to look for when you need behaviour the package doesn't offer: custom driver registration (usually Extend/Manager::extend), macros, Package::before() / after() hook methods, published contracts/interfaces you can rebind, and events the package dispatches that you can listen to rather than fork. Forking should be the last resort — rebinding a contract in your own provider is nearly always cheaper.