Symfony Laravel Package

Getting Started

This package is a thin Laravel integration layer over papi-core, so the first thing to internalise is that your effective feature set is determined by the papi-core version resolved in composer.lock, not by this package's version number. v0.15.1 is a dependency-floor release: it requires papi-core >= 0.15.3, which carries the PHP 8.5 compatibility fixes.

Minimal path from zero to first working call:

1. Check your PHP version first. php -v. If you are on PHP 8.5, you must be on this release or later — earlier versions pin a papi-core that predates the 8.5 fixes and you will hit deprecation/fatal errors deep in the dependency rather than in your own code. On PHP 8.3/8.4 the upgrade is functionally inert.
2. Install with an explicit constraint, not a bare composer require:

   composer require vendor/laravel-papi:^0.15.1
   

   Then confirm the transitive resolution:

   composer show vendor/papi-core
   

   You want >= 0.15.3. If Composer resolved something older, you have a conflict (usually another package pinning papi-core) — resolve that before writing any code, because debugging against the wrong core version is the single biggest time sink with this package.
3. Read the package's own service provider before the docs. Because the Laravel layer is thin, the provider is the authoritative map of what is bound, what is aliased, and what is publishable. Look for mergeConfigFrom, publishes, and any singleton bindings — those tell you the extension points in about two minutes.
4. Publish and diff the config rather than assuming defaults:

   php artisan vendor:publish --provider="Vendor\Papi\PapiServiceProvider"
   

   Open the published file and read every key; several will be pass-throughs to papi-core and their defaults may differ from what the core uses standalone.
5. First use case: wire up one read-only call end-to-end — resolve the client from the container (injected into a controller or via the facade), make a single request, and dd() the raw response before touching any resource/DTO layer. This confirms credentials, base URL, and transport config all at once.

If you are upgrading an existing install rather than starting fresh, treat this as a two-line change: bump the package constraint, run composer update vendor/laravel-papi vendor/papi-core, and verify the core version. There is no migration or config change in this release.

Implementation Patterns

Pin the floor, not just the package. In composer.json, constrain both layers explicitly so a future composer update on a colleague's machine cannot silently downgrade your core:

"require": {
    "vendor/laravel-papi": "^0.15.1",
    "vendor/papi-core": "^0.15.3"
}

This is the highest-value habit with a wrapper package like this — it turns an invisible transitive dependency into a declared contract, and it documents why the version matters (PHP 8.5 support) to whoever reads the file next.

Resolve through the container, never with new. The Laravel layer exists to give you config-driven construction and test substitution. Inject the client into constructors, or resolve it in a service provider and bind a configured instance:

$this->app->singleton(MyPapiGateway::class, fn ($app) => new MyPapiGateway(
    $app->make(\Vendor\Papi\PapiClient::class)
));

Wrapping the package client in your own thin gateway interface is worth the ten minutes: it isolates the 0.x API surface behind something you control, so a breaking minor bump becomes a one-file change instead of a grep across the codebase.

Treat the config as environment-scoped. Because settings are pass-throughs to the core, the clean pattern is config keys backed by env() in the published file, and different values per environment — sandbox credentials locally, real ones in production, and a stubbed/faked transport in testing. Never let tests reach a live endpoint.

Guard the boundary in a feature test. The cheapest insurance against this package's 0.x churn is a single test that constructs the client and asserts it resolves and is configured — no network call needed. When you bump versions, that test failing tells you immediately whether the container binding or config shape moved.

Batch and queue where the core allows it. Wrapper packages typically expose the core's async primitives but not its ergonomics; check whether the Laravel layer provides a queue job or whether you need to wrap calls in your own ShouldQueue job. For anything beyond a handful of requests, push it to a job with retry/backoff configured — it keeps request latency out of the equation and gives you a natural place for rate-limit handling.

CI matrix note: if you test across PHP versions, add 8.5 to the matrix on this release. That is the entire point of v0.15.1, and it is the only way to catch a regression in the fix before production does.

Gotchas and Tips

This is a dependency-floor release, not a feature release. v0.15.1's only substantive change is requiring papi-core 0.15.3+. If your composer.lock already resolved papi-core at or above that, composer update will show no behavioural change — don't go hunting for one. The meaningful question is only: am I on PHP 8.5, and if so is my core new enough?

0.x semver means minor bumps can break you. ^0.15.1 correctly constrains to 0.15.x only, which is the right choice — but be aware that 0.16.0 may contain breaking changes and Composer will not hold you back if someone runs composer require loosely. Review changelogs before any minor bump, and keep composer.lock committed.

The failure mode is misleading. PHP 8.5 issues from an old papi-core surface as deprecation notices or type errors inside vendor code, frequently pointing at a file in papi-core that you never wrote. If you see stack traces originating in the dependency on a fresh 8.5 environment, check the resolved core version before debugging your own code.

Version-conflict resolution is the main operational risk. A third-party package pinning papi-core to 0.14.x or <0.15.3 will block this bump. Diagnose with composer why vendor/papi-core rather than guessing, and prefer upgrading or replacing the conflicting package over --ignore-platform-reqs hacks that leave you in an untested combination.

Config caching catches people out. After changing publishable config, run php artisan config:clear (or config:cache in deploy). Because keys pass through to the core, a stale cached config can leave the core pointing at old credentials or an old base URL while the Laravel-side config file looks correct.

Extension points to survey before forking anything: the container binding (swap the client), the config file (credentials, transport, timeouts),published views/routes if any, and any events the package dispatches. In a thin wrapper these are usually the whole surface — if you find yourself needing behaviour they don't cover, that logic belongs in your own gateway class, not in a vendored patch.

Keep a note in your upgrade log. One line — "v0.15.1: PHP 8.5 support, requires papi-core ≥0.15.3" — saves the next person from re-deriving why the floor exists when they try to loosen the constraint.