Revisionable Laravel Package

Getting Started

• Confirm the version constraint. v2.1.3 adds Laravel 5.5 support, so pin ^2.1 in composer.json rather than a bare composer require vendor/package. Check the package's own composer.json for illuminate/support and PHP version requirements — 5.5-era packages typically need PHP 7.0+.
• Skip manual provider registration. Laravel 5.5 introduced package auto-discovery. After composer require, confirm the provider and any aliases landed in bootstrap/cache/packages.php and vendor/composer/installed.json. If they didn't, run composer dump-autoload and php artisan package:discover. Only fall back to adding the provider to config/app.php if the package has no extra.laravel block.
• Publish before configuring. Run php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (or the narrower --tag=config) and read the published config top to bottom. Every key is a decision you're making, and the defaults are rarely production-appropriate.
• Move secrets to .env. Published config files get committed; anything credential-shaped should reference an env() key you add to .env and .env.example.
• Run migrations if the package ships them. Publish the migration tag, then php artisan migrate. Do this before touching application code so failures surface early.
• First use case: one read in Tinker. Before wiring anything into a controller, resolve the package's entry point in php artisan tinker and make a single successful call — a list/read operation against your configured credentials. It isolates auth and config problems from application code.
• Where to look first: the README's usage section, src/*ServiceProvider.php (bindings, singletons, config merging, published tags), the config file, and the package's tests/ directory — package tests are usually the most accurate documentation of intended wiring.

Implementation Patterns

• Inject, don't instantiate. Resolve the package's client/manager from the container via constructor injection. The service provider almost certainly binds an interface or a singleton; binding against the interface is what makes the package fakeable in tests and swappable later.
• Wrap it in a thin adapter. Put the package behind one or two of your own classes (App\Services\FooClient) with methods named after your domain, not the package's. Day to day this costs ten minutes and pays for itself the first time you upgrade a major version, swap vendors, or need to mock the package in a feature test.
• Facades are for glue code only. Fine in Blade templates, Artisan commands, and quick scripts; use constructor injection in services, jobs, and controllers so dependencies stay explicit and testable.
• Config over code for tunables. Timeouts, retry counts, queue names, driver selection — surface these as config keys in your own config/services.php entry so ops can tune without a deploy. Change .env, then php artisan config:clear.
• Long-running and queued work. If the package holds request-scoped state, resolve a fresh instance per job rather than injecting a singleton into a queued job's constructor — the job serializes, and stale state in a worker is a classic silent bug.
• Integrate via events and the scheduler. If the package dispatches events, listen for them in app/Providers/EventServiceProvider instead of polling. If it exposes sync commands, register them in app/Console/Kernel.php with withoutOverlapping().
• Testing. Swap the container binding for a fake/mock in setUp(); use RefreshDatabase if the package's migrations are published into your suite; Queue::fake() and Event::fake() to assert the package's side effects without exercising them.
• Blade and API surfaces. If the package ships views, publish them to resources/views/vendor/{package} and override there rather than editing vendor/ — vendor edits vanish on composer update.

Gotchas and Tips

• env() returns null after config:cache. Any env() call inside a published config file is resolved at cache time. Always run php artisan config:clear after editing .env locally, and never call env() outside config files in your own code.
• Auto-discovery goes stale. If the provider "isn't there" after composer update, delete bootstrap/cache/packages.php and bootstrap/cache/services.php, then composer dump-autoload.
• vendor:publish overwrites your edits. Bare vendor:publish re-copies files. Use --tag= for targeted publishes; --force only when you intend to discard local modifications to the config or views.
• Don't edit published migrations after they've run in production. Add a follow-up migration instead; the publish step won't reconcile your edits, and other environments will silently diverge.
• Version-skew debugging. When something behaves oddly, first verify the installed version (composer show vendor/package) matches what the README documents. A surprising number of "package bugs" are a docs/version mismatch.
• Debugging loop. php artisan tinker for container resolution and single calls, Log::debug() around the boundary of your adapter, storage/logs/laravel.log for swallowed exceptions, and php artisan route:list if the package registers routes you didn't expect.
• Upgrade posture for v2.1.3. This is a compatibility release adding Laravel 5.5 support — no breaking changes indicated relative to 2.1.x. If you're coming from 2.0.x, read the 2.1 upgrade notes separately. Treat the Laravel 5.5 bump as an opportunity to drop any manual config/app.php provider registration you were carrying.
• Extension points to know before you fork. Container bindings in the service provider, extend()/custom-driver hooks on any manager class, and Blade/macro registration are the supported seams. Prefer them over subclassing package internals, which have no BC guarantee across minor versions.