Spire Laravel Package

Getting Started

esplora/spire is still on a 0.0.x line (latest: 0.0.4), so treat installation as "pin, read the diff, then wire it up" rather than "composer require and go."

1. Read the diff before installing. The 0.0.4 release notes are a bare compare/0.0.3...0.0.4 link — there is no changelog body, no migration notes, no deprecation list. Open that compare view first; it is your only source of truth for what changed.
2. Install with an exact-ish pin. In Composer, ^0.0.4 resolves to >=0.0.4 <0.0.5, which is effectively an exact pin — that's the correct constraint to use on a pre-1.0 package, but be aware that the next patch (0.0.5) is a deliberate manual bump, not something you get for free.
3. Verify wiring. composer show esplora/spire and check the package's composer.json extra.laravel block — if a service provider and/or facade alias is declared there, Laravel auto-discovers it and there is nothing to register in config/app.php.
4. Publish what's publishable. php artisan vendor:publish --provider="Esplora\Spire\SpireServiceProvider" (check the actual provider FQCN in src/) and inspect the tags it exposes — config, migrations, stubs, views. Publish config in every environment, not just local.
5. First use case: resolve the package's primary entry point out of the container in php artisan tinker and exercise one happy-path call against a dev database before writing any application code. On an unversioned 0.0.x release this five-minute smoke test is cheaper than debugging a facade-not-found error inside a feature branch.

Where to look first, in order: the compare diff → README.md → src/ for the service provider and any Contracts/ directory → tests/ (on a pre-1.0 package the test suite is usually more current than the docs).

Implementation Patterns

Wrap it, don't sprinkle it. Do not call the package's facade or static helpers directly from controllers, jobs, and models. Introduce a single thin adapter in your app:

// app/Services/Spire/SpireGateway.php
final class SpireGateway
{
    public function __construct(private readonly SpireClient $client) {}

    public function doTheThing(ThingData $data): ThingResult
    {
        return ThingResult::fromSpire($this->client->execute($data->toArray()));
    }
}

Bind the interface in a dedicated SpireServiceProvider of your own and translate the package's return types into your own DTOs at that boundary. When 0.0.5 renames a method or changes a payload shape, the blast radius is one class instead of forty call sites — which is the only sane way to consume a package whose changelog is a hyperlink.

Config over code. Drive everything you can through the published config file, and reference it via config('spire.*') rather than constructor arguments. This keeps environment-specific behaviour (credentials, endpoints, sandbox toggles, queue names) out of your source and makes the upgrade diff easier to reason about.

Prefer container resolution over facades. Resolve via constructor injection or app() so tests can $this->swap() / $this->instance() the binding. If the package ships a facade, it's fine for tinker and one-off scripts, not for production paths.

Feature-test the seam. Write one integration test that hits the real binding with a faked transport (Laravel's Http::fake() if it does HTTP, Queue::fake() if it dispatches jobs) and one contract test asserting your adapter's output shape. That pair catches most silent breakage on a patch bump.

Upgrade ritual, every bump:

composer update esplora/spire --with-dependencies
git diff composer.lock
# open the compare URL from the release notes, read src/ changes
php artisan config:clear && php artisan cache:clear
php artisan test --filter=Spire

Diff vendor/esplora/spire/src between the two tags if the compare view is noisy — grepping for changed public function signatures is faster than reading the whole thing.

Extension points to look for while reading src/: interfaces in Contracts/ (bind your own implementation), Macroable traits, dispatched events you can listen for, and any Manager-style driver resolver. On a 0.0.x package these are more stable than concrete classes and are the right place to hang customisation.

Gotchas and Tips

The changelog is empty — that's the headline gotcha. A release whose entire body is **Full Changelog**: .../compare/... tells you nothing about breaking changes. On a 0.0.x package, assume every release is breaking until the diff proves otherwise. Do not composer update this package as part of a routine weekly dependency sweep; bump it deliberately, on its own branch, with the test suite green.

Semver in the 0.0.x range is not what you think. ^0.0.4 pins to 0.0.4 only. ~0.0.4 behaves the same here. Any composer.json written as "esplora/spire": "*" or "dev-main" in a project is an incident waiting to happen — audit for it.

Config cache bites on upgrade. If new config keys appear in 0.0.4 and you've previously published the config file, vendor:publish will not overwrite it (and --force will clobber your values). Either re-publish to a temp path and merge manually, or rely on the package's mergeConfigFrom defaults and only override what you actually change. Always php artisan config:cache (or config:clear in local) after editing.

Migration drift. If the package ships migrations, they're published into your database/migrations with a timestamp from publish time, not release time. Two developers publishing different versions get different filenames — check php artisan migrate:status before assuming a schema change landed.

Auto-discovery vs. cached manifests. php artisan package:discover runs on composer install; if the provider is registered in bootstrap/cache/packages.php from an older version, a renamed provider class will throw a confusing "class not found" that survives config:clear. Fix with php artisan package:discover --ansi or deleting bootstrap/cache/packages.php.

Debugging checklist when something behaves differently after the bump:

• composer show esplora/spire — confirm the installed version is what you think.
• php artisan about — confirms provider discovery and cache state at a glance.
• php artisan tinker → app(SpireClient::class) — proves the binding still resolves.
• git diff 0.0.3 0.0.4 -- vendor/esplora/spire/src — find the actual signature change.

Watch for the first 0.1.0. Packages that sit at 0.0.x for several releases often jump straight to a rewritten public API. When that tag appears, budget a real upgrade rather than a patch bump, and check whether the README's examples have been regenerated — on 0.0.x packages the README frequently lags src/, and the test suite is the better documentation.