Rest Api Laravel Package

Getting Started

• Install with composer require mediamonks/rest-api, then immediately check composer.json for the pinned symfony/http-kernel constraint and PHP version floor — the package tracks HttpKernel tightly, so match it to your runtime before writing code.
• Read the repo README.md and examples/ directory first. This is a thin package, so the example front controller is effectively the real documentation: it shows how the router, middleware stack, container, and HttpKernel are assembled.
• Stand up a minimal bootstrap in public/index.php: build the router, register middleware, construct the kernel, call $kernel->handle(Request::createFromGlobals()), and ->send() the response. Get that loop returning anything before adding features.
• First use case: a single read-only JSON endpoint like GET /health returning {"status":"ok"}. This proves request → middleware → controller → response wiring. Then add one resource route (GET /users/{id}) backed by a controller and a repository.
• Next places to look: the middleware stack (auth, CORS, body parsing) and the exception listener. Those two are where most of the real day-to-day work happens in any REST API.

Implementation Patterns

• Route → controller → JsonResponse is the core loop. Keep controllers thin: validate input, delegate to a service/repository, return a response. Business logic never belongs in the controller.
• Model the middleware pipeline explicitly and treat order as load-bearing: request-id → CORS → auth → JSON body parse → handler. Each middleware should do one thing and short-circuit cleanly (return a JsonResponse early) on failure.
• Wire dependencies through a PSR-11 container instead of instantiating services in controllers. Inject repositories, config, and a logger; this is also what makes the code testable.
• Centralize error handling in one exception listener that maps exceptions to a consistent JSON error shape (type, title, status, detail). Do it once so every endpoint — including 404s and validation failures — looks the same.
• If you need to coexist with a Laravel app: run this as a separate service (own PHP-FPM pool or server block) behind a reverse proxy or API gateway. Share contracts — DTOs, OpenAPI spec, auth tokens — via a Composer package or generated client, not by sharing a runtime.
• Share configuration through environment variables (.env or container secrets) so both apps read the same DB credentials, JWT secret, Redis host, and CORS allow-list.
• Test at the kernel boundary: construct a Request, call $kernel->handle($request), assert against the Response. This is fast, needs no web server, and exercises the full middleware chain.
• For auth, reuse your existing JWT/OAuth issuer; add one middleware that verifies the token and injects the identity into request attributes so controllers stay auth-agnostic.

Gotchas and Tips

• This is not a Laravel package. No service provider, no facades, no Artisan commands, no Eloquent integration. Expect to wire everything yourself; composer require will not "just work" inside a Laravel app.
• Don't run two HTTP kernels. Laravel and this package both assume they own the request lifecycle. Nesting one inside the other produces duplicated middleware, conflicting exception handlers, and confusing request state. Keep them in separate processes.
• Maturity risk is real. 13 stars, 0 dependents, low score — treat it as a reference implementation you own rather than an actively supported dependency. Pin the exact commit, vendor-fork if needed, and review upgrades by hand.
• Version pinning bites. Upgrades to PHP or symfony/http-kernel can change the handle()/terminate() signatures and break the kernel. Lock versions in composer.lock and update deliberately.
• Debugging is manual. Enable the kernel's debug flag and wire a Monolog logger; without it, exceptions surface as opaque 500s. Log the request-id middleware output so you can correlate with the reverse proxy and the Laravel side.
• Bootstrap ordering is the usual culprit. Router → container → middleware → kernel, all in code. If a middleware silently doesn't fire, check registration order and whether a cached container is stale.
• CORS preflight is not free. Add explicit OPTIONS handling in middleware, or browser calls will fail before they ever reach your controller.
• Extension points are custom middleware, a custom exception listener, and swapping the router. Keep your own code in a clean src/ namespace so you can lift it into Symfony or Laravel if you outgrow the package.