Dorehami Laravel Package

Getting Started

The package ships as a standard Composer dependency with Laravel package discovery, so day-to-day adoption is short:

composer require <vendor>/<package>:^0.2

1. Confirm discovery. Check vendor/<vendor>/<package>/composer.json for an extra.laravel.providers entry. If it is absent, register the service provider manually in bootstrap/providers.php (Laravel 11+) or config/app.php.
2. Publish what you need, not everything. Run php artisan vendor:publish --provider="<Vendor>\<Package>\<PackageServiceProvider>" and inspect the tags offered (--tag=config, --tag=migrations, --tag=views). Publish the config first; that file is the best single source of truth for what the package can do and is the fastest way to learn its surface area.
3. Read the source before the docs. With release notes this thin ("Second Release"), src/ plus the published config is more reliable than any README. Look at the service provider's register()/boot() methods — that is where bindings, singletons, and optional integrations are wired.
4. First use case. Resolve the package's primary entry point out of the container (app(SomeManager::class) or its Facade) in a throwaway php artisan tinker session and exercise one real call against a staging database before writing any application code. This surfaces missing config and credential issues immediately.

Before upgrading an existing install, diff the 0.1.x and 0.2.0 tags (git diff 0.1.0..0.2.0 -- src config) or read CHANGELOG.md/UPGRADE.md in the repo. The release notes alone are not sufficient to judge blast radius.

Implementation Patterns

Wrap it, don't sprinkle it. Bind the package behind a thin application-level interface and resolve that in your controllers, jobs, and listeners. Pre-1.0 packages reshape their API between minor versions; a single adapter class means a 0.2.x breaking change is a one-file fix instead of a repository-wide grep.

// app/Contracts/ThingGateway.php  ->  app/Services/PackageThingGateway.php
$this->app->bind(ThingGateway::class, PackageThingGateway::class);

Configuration in config/ only. Keep the published config file as the sole place credentials and endpoints live, and read them through config('package.key') — never from the package namespace directly in application code. This is what makes php artisan config:cache safe and lets you override per-environment via .env.

Queue anything remote. If the package performs HTTP calls, file I/O, or third-party sync, call it from a queued job with $tries, backoff(), and failed() defined. The package will generally not know your retry policy; you own it. Restart workers on every deploy (php artisan queue:restart) after a version bump.

Fake it in tests. Laravel's fakes should cover the integration boundary, not the package internals:

Queue::fake(); Http::fake([...]); Event::fake([PackageEvent::class]);

Add one or two contract tests that hit the real package (unfaked) against a local database; fake-everything suites pass happily while a 0.2.0 signature change breaks production.

Roll out behind a flag. For anything user-facing, gate the new call path with Pennant or a config toggle so you can disable the integration without a deploy.

Register listeners, not callbacks in the provider. If the package dispatches events, subscribe in EventServiceProvider / Event::listen in your own provider rather than editing vendor-published code, so upgrades do not conflict.

Gotchas and Tips

• Semver in 0.x is not what you expect. "^0.2" resolves to >=0.2.0 <0.3.0, so a 0.2.1 can still change behaviour, and composer update inside the same constraint is not a safe operation. Commit composer.lock, and treat every 0.x bump as a potentially breaking upgrade. For tighter control, pin exactly ("0.2.0") in production and upgrade deliberately.
• Release notes are not a changelog. "Second Release" tells you nothing about deprecations or signatures. Always cross-check the Git tag diff, CHANGELOG.md, and any UPGRADE.md before merging. If the maintainers are not keeping these, budget for reading the diff on every bump and consider that a risk signal for the dependency.
• Config cache hides new keys. After upgrading, php artisan config:cache may keep stale published config that lacks a newly required key, producing confusing null errors. Re-publish or manually merge the config (vendor:publish --force only after diffing), then php artisan config:clear.
• Deferred providers and singletons. If the provider is deferred, resolving a binding too early in a long-lived process (Octane, queue worker) can capture stale state. Prefer resolving per-request where possible, and test under php artisan octane:start if you run Octane.
• Migrations and data. Run php artisan migrate --pretend first on any package that publishes migrations; check for irreversible column drops and confirm the package supports rollback. Take a snapshot before upgrading in production.
• Debugging: php artisan about, php artisan vendor:publish --list, and dump(app()->getLoadedProviders()) confirm whether a provider actually booted. Log::withContext() around package calls makes stack traces attributable when several integrations are in play.
• Extension points to prefer: package events, container bindings for interfaces it type-hints, and published config. Avoid subclassing vendor classes or editing published files — both make the next release a manual merge.
• Upgrade checklist: pin lockfile → diff tags → clear cached config → run contract tests → migrate --pretend → deploy with queue:restart → keep the previous version tag handy for a fast revert.