Larapi Laravel Package

Getting Started

one2tek/larapi is a Laravel package for scaffolding REST API layers (routing, controllers, response formatting) on top of a standard Laravel app.

1. Install with the right constraint. Because Laravel 9 support only landed in 2.0.11, pin explicitly rather than relying on the resolver:

   composer require one2tek/larapi:^2.0.11
   

   On Laravel 9 this also means PHP 8.0+; if you are still on Laravel 6/7/8, ^2.0 will resolve to a compatible 2.0.x — check composer why-not if the install refuses.
2. Register/publish the package assets. Look for a service provider auto-discovery entry, then publish anything it ships (config, routes, stubs):

   php artisan vendor:publish --provider="One2tek\Larapi\LarapiServiceProvider"
   

   Inspect config/larapi.php first — that file is the map of the package's opinions (route prefix, middleware stack, response wrapping, pagination defaults).
3. Where to look first: the published config, the package's route file (if it registers one), and its base controller / response trait. Those three files tell you whether the package wants you to extend its classes or just use its helpers.
4. First use case: stand up one versioned resource end-to-end — a single GET /api/v1/things endpoint returning the package's standard JSON envelope — and assert it with a Laravel HTTP test. Confirm the envelope shape (data/meta/errors keys) before you build a second endpoint, since every client contract downstream depends on it.

Implementation Patterns

• Extend the package base controller, don't fight it. If larapi ships an abstract API controller or response trait, subclass it for your resources so pagination, status codes, and error envelopes stay consistent across the app.
• Version at the route group, not the controller. Keep routes/api.php thin and group by prefix (/v1, /v2) with the package middleware applied at the group level. This makes the eventual v2 rollout additive rather than a rewrite.
• Standardise the response envelope once. Wrap success and error payloads through the same helper (a respond()/ApiResponse-style method or a Resource collection) so mobile and SPA clients parse one shape. Add a MakeApiResponse-style action or a base ApiController method rather than repeating response()->json([...]).
• Middleware stack: put auth (Sanctum for first-party SPAs, Passport for third-party clients) and throttle:api in the package's config-driven middleware array rather than on individual routes — you get uniform behaviour and one place to audit.
• Exception handling: register a render hook in app/Exceptions/Handler.php (or the Laravel 9 withExceptions closure) that converts ValidationException, ModelNotFoundException, and AuthenticationException into the package's error envelope. Without this you get Laravel's HTML/debug responses leaking into your JSON contract.
• Feature tests as the contract. Use $this->getJson() / assertJsonStructure() against the envelope so refactors and package upgrades fail loudly. This matters more than usual for a small-maintainer package.
• Service layer for anything non-trivial. Treat larapi as the transport/HTTP layer only; keep query logic in actions or services so endpoints stay testable without HTTP.

Gotchas and Tips

• Laravel 9 requires 2.0.11+. A stale composer.lock or a ^2.0.0 constraint copied from an older project can silently resolve to 2.0.10 and fail on Laravel 9 due to framework API differences. After upgrading Laravel, run composer update one2tek/larapi --with-dependencies and verify the installed version.
• 2.0.10 → 2.0.11 is additive (Laravel 9 support only), so no migration work is expected. The 2.0.x line implies semver patch semantics — still, read the changelog before each bump given the low release cadence and single-maintainer history.
• Config and route caching bite after publishing. Run php artisan config:clear && php artisan route:clear (and optimize:clear in CI) whenever you edit the published config or add a package-provided route file.
• Auto-discovery mismatches are the usual cause of "class not found" after install — check bootstrap/cache/packages.php, or add the provider manually in config/app.php if you're on an older app skeleton.
• Don't assume package defaults match your API style. Route prefixes, envelope keys, and pagination sizes are opinionated; override them in config/larapi.php at project setup rather than patching vendor code.
• Debugging: Log::info() inside package middleware plus Telescope's request/response pair is the fastest way to see where the envelope is being rewritten. dd() inside a response macro will surface as a broken JSON body, not a stack trace.
• Extension points to prefer: container bindings, published config, and config-driven middleware arrays. Avoid subclassing deep internal classes — with a solo maintainer, internals are the most likely thing to shift in a future minor.
• Fallback plan: the package is a thin convenience layer. If a Laravel upgrade ever outpaces its release cycle, the endpoints you built on plain controllers, resources, and route groups are portable back to vanilla Laravel with limited effort — keep that portability in mind and avoid making larapi load-bearing for business logic.