Xeroticframe Laravel Package

Getting Started

• Install with an exact pin, not a range: composer require vendor/package:0.0.1. A 0.0.x release is a testing artifact — treat the public API as unstable until 1.0.0.
• Before writing a single line of app code, read these four things in order:
  1. composer.json — PHP and illuminate/* constraints. A loose Laravel constraint (e.g. ^10.0|^11.0) on a 0.0.1 package usually means untested combinations.
  2. The service provider — what it binds, merges, publishes, and registers.
  3. config/*.php — which env keys exist and whether defaults are safe.
  4. tests/ — if there are none, you are the test suite.
• Confirm auto-discovery worked before debugging anything else: php artisan package:discover then check bootstrap/cache/packages.php for the provider entry. On Laravel 11+ this is the whole registration story; on 10 and below the provider lands in config/app.php.
• First use case: pick one narrow, reversible integration — a single queue job, one Artisan command, or one read-only query path. Do not wire it into your domain core on day one.
• Wrap the package immediately behind your own interface (App\Contracts\... + an adapter implementation bound in a service provider). This costs an hour now and makes the inevitable 0.0.2 breaking change a one-file edit.

Implementation Patterns

Container-first, facade-never. Resolve from the container in constructors rather than calling the facade statically. This keeps the class mockable and lets you swap the binding to a fake in tests without touching call sites.

final class SyncOrders
{
    public function __construct(private readonly VendorClient $client) {}
}

Bind to your own contract, not the package class. Bind the package's client to your interface in a dedicated service provider so the package namespace appears in exactly one file across the codebase — the single seam you edit on upgrade.

Config and env discipline. Publish config with php artisan vendor:publish --provider="Vendor\Package\ServiceProvider" and commit it. Set values in config/*.php using env() only there — never call env() at runtime, it returns null once php artisan config:cache has run. Override in tests with config()->set() in setUp(), not by mutating $_ENV.

Parallel-run pattern for an unproven package. Run the new implementation alongside the existing one behind a config flag, log both outputs, diff them for a week, then cut over. This is the highest-value pattern for a 0.0.1 dependency and it costs very little.

Test the boundary, not the package. You are testing your integration, not their internals:

• Http::fake() for any outbound calls the package makes — assert the request shape it produces, since that is the contract most likely to break silently.
• Queue::fake() / Bus::fake() if it dispatches jobs.
• Event::fake() if it fires events you listen to.
• RefreshDatabase plus a migration/table assertion if it ships migrations; verify it does not collide with your naming conventions.

Composer and CI hygiene. Commit composer.lock. Give this package a Renovate/Dependabot rule that opens a PR for every patch and requires a green CI run — pre-1.0 patch bumps regularly contain behaviour changes despite what semver implies. Run a CI matrix across your actual PHP and Laravel versions rather than trusting the package's declared constraints.

Escape hatches. If the package exposes a manager/driver class, prefer registering a custom driver via the documented extend() hook over forking. If it does not, the adapter from Getting Started is your only extension point — and that is fine.

Gotchas and Tips

• The caret operator is a trap pre-1.0. ^0.0.1 resolves to >=0.0.1 <0.0.2, which is a single patch. ^0.1.0 gives you >=0.1.0 <0.2.0. Neither behaves like ^1.0. Pin explicitly and upgrade deliberately.
• A 0.0.1 labelled "for testing" is not a stability signal you can ignore. Assume no upgrade guide, no deprecation policy, and possible silent removal of methods. Subscribe to the repo's releases and read every diff before bumping.
• Auto-discovery fails quietly after some Composer operations. If bindings vanish, run composer dump-autoload and php artisan package:discover before suspecting your own code.
• Publish tags may not exist yet. vendor:publish with no --tag is fine on a first release; with a guessed tag it exits 0 and publishes nothing. Drop the flag if you get an empty result.
• Debugging order: php artisan about (is the provider listed?) → bootstrap/cache/packages.php → published config diffed against the package's original in vendor/ → the package source itself. On a first release, reading vendor/vendor/package/src is legitimate due diligence, not a last resort.
• Config cache clears are required after any published-config edit in a deployed environment; the most common "it works locally" report on a new package is a stale bootstrap/cache/config.php.
• Watch for global side effects. A young package may register a global middleware, a model observer, or a DB::listen hook by default. Grep the provider for boot() side effects before enabling it in production.
• Do not let it own your migrations. If the package ships tables, consider copying the migration into your app and disabling its publishing so your schema history stays under your control.
• Extension points to look for, in preference order: container bindings (bind your own implementation) → documented driver/manager extend() → published config → published stubs/view overrides. If none exist, isolate with the adapter and treat the dependency as replaceable.