Sharpapi Laravel Client Laravel Package

Getting Started

This is the first assessment for this package, and the only signal in this release is Laravel 12 compatibility (v1.2.4, a patch bump). Treat that as the primary fact: the package's composer.json now allows illuminate/* ^12.0, so Laravel 12 applications can install it without --ignore-platform-reqs or a fork.

Minimal path to a first working call:

1. Confirm the constraint before installing. Run composer show <vendor>/<package> --all and check the versions and requires block. If you are still on Laravel 10 or 11, verify the constraint is a range (e.g. ^10.0|^11.0|^12.0) rather than ^12.0 only — a patch release that drops older Laravel versions is effectively a breaking change for you.
2. Install and let discovery run. composer require <vendor>/<package>:^1.2.4 then php artisan package:discover --ansi. Laravel 12 uses the streamlined skeleton (bootstrap/app.php, no app/Http/Kernel.php), so anything the README tells you to paste into a Kernel is stale.
3. Read, in this order: the README's "Installation" and "Configuration" sections, then config/<package>.php if the service provider registers a mergeable config. That config file is the real API surface — it tells you what is tunable before you read a single class.
4. Publish and run the trivial case. php artisan vendor:publish --provider="Vendor\Package\PackageServiceProvider" (or --tag=<package>-config), then make the simplest possible call the README shows — usually a facade one-liner or a container resolve. Do this before wiring it into business logic so a config or binding problem surfaces immediately.

First real use case: get one end-to-end call working against a local/staging environment, not a test double. Laravel 12's reworked bootstrap is where integration bugs hide, and a fake will not exercise it.

Implementation Patterns

Upgrade-path pattern (the one this release enables). Move in a branch, not on main:

composer require <vendor>/<package>:^1.2.4 --with-all-dependencies
composer why-not <vendor>/<package> 1.2.4   # shows what still blocks the upgrade

--with-all-dependencies matters here: the package's new Laravel 12 constraint may require transitive packages (nesbot/carbon, symfony/*) to move too, and without -W Composer will refuse rather than resolve.

Dual-version CI matrix. If the package's constraint is a range, run your test suite against both Laravel 11 and 12 before trusting the patch bump:

matrix:
  laravel: ['^11.0', '^12.0']
  php: ['8.2', '8.3']

Laravel 12 dropped PHP 8.1, so an 8.1 row will fail on the framework itself, not on the package — keep those dimensions explicit so you can tell the difference.

Resolve through the container, not new. Bind or resolve via the facade/contract the README advertises. This is what keeps you insulated if a future minor changes the concrete class, and it is what makes ->fake() / ->swap() usable in tests.

Keep configuration in config/, read at runtime. Publish the config file and reference values through config('<package>.key') inside your own service providers and actions. Never call env() from application code — under php artisan config:cache (which Laravel 12's deploy flow still expects) env() returns null outside config files.

Wrap third-party calls behind a thin adapter. One small class in your app that delegates to the package gives you a single swap point when the next release changes a method signature, and a single place to add tracing/logging.

Test with the framework's fakes where offered. If the package ships a fake or an in-memory driver, use it in Feature tests and reserve the real driver for a small number of Integration tests. A patch release that only touches the service provider will not be caught by fakes — keep at least one test that boots the full app.

Gotchas and Tips

• A "compatibility" patch can still break you. If v1.2.4 replaced the constraint instead of widening it, your Laravel 10/11 apps will silently stop receiving updates. Diff composer.json between v1.2.3 and v1.2.4 (composer diff or the GitHub compare view) before bumping everything.
• Laravel 11/12 removed the HTTP and Console kernels. README snippets that say "add to $middlewareGroups in app/Http/Kernel.php" or "register in RouteServiceProvider" are pre-11. The equivalents live in bootstrap/app.php via ->withMiddleware() and ->withRouting(). Translate, don't paste.
• Package discovery is cached. After composer require/update, if the provider seems missing, run php artisan package:discover and then php artisan optimize:clear. A stale bootstrap/cache/packages.php produces "class not found" errors that look like a broken package.
• Config cache during deploy. php artisan config:cache in your pipeline can freeze a default that the package expects to compute at boot. If behaviour differs between artisan serve and production, clear the cache first — it is the cheapest hypothesis to eliminate.
• Check for a migration tag. If the package ships migrations, vendor:publish --tag=<package>-migrations must run before php artisan migrate on deploy. A patch release is allowed to add a migration; verify with php artisan vendor:publish --list or by diffing the package's database/ directory.
• Pin the patch in composer.lock and commit it. ^1.2 will happily pull a future 1.3 with real changes. For a release whose entire premise is a framework-version bump, lockfile diffs are your cheapest audit trail.
• Debugging order of operations: php artisan about (confirms Laravel/PHP versions and the cached-config state) → composer show <vendor>/<package> (confirms the installed version) → composer why-not (confirms what blocks resolution) → php artisan tinker resolving the class from the container. That sequence separates a version problem from a wiring problem from a code problem.
• Extension points to know before you need them: the facade accessor and bound contract (for swapping implementations in tests), the published config file (for behaviour without forking), and any Macroable/extend hook the README advertises. If none of these exist and you find yourself editing vendor/, that is the signal to open an upstream issue rather than carry a patch — a package actively shipping compatibility releases is likely to accept it.