Microserve Laravel Package

Getting Started

• composer require desilva/microserve — check composer.json first for the required PHP version and whether it pulls in ReactPHP (it does the event-loop work under the hood; you are not writing against PHP-FPM).
• Read the README example end-to-end, then open src/. The package is small enough that the source is the documentation: identify the app/server class, the router, and the request/response objects before writing anything real.
• Understand the execution model before your first route: this is a standalone long-running process, not a library bootstrapped from public/index.php. Your entry point is a server.php you run with php server.php.
• Smallest first use case: a JSON health/echo endpoint on a port, hit with curl. Do not port a Laravel route file to it on day one.

Typical skeleton (confirm class names against the actual source — the API surface is tiny and drifts between 0.x releases):

require __DIR__ . '/vendor/autoload.php';

$app = new Desilva\MicroServe\App(); // check README for the real entry class

$app->get('/', function ($req, $res) {
    return $res->json(['ok' => true]);
});

$app->listen(8080);

Implementation Patterns

• Standalone microservice / webhook receiver. The realistic sweet spot: a single-purpose process (Stripe webhook, internal RPC endpoint, tiny read-only API) run under systemd or supervisor instead of PHP-FPM. Small route count, no sessions, no Blade.
• Sidecar next to Laravel. Keep Laravel as the main app and use microserve for a long-running listener that Laravel calls over localhost. This avoids dragging Octane/Swoole into the whole application just to get one persistent endpoint.
• Imperative routing, one file per domain. Define routes at boot in flat files. Keep handlers as invokable classes and wire them with closures — do not try to recreate Laravel's container, facades, or route model binding here.
• Middleware as a manual chain. There is no kernel pipeline; compose handlers yourself (auth → validate → handler), where each function either returns a response or delegates to the next. Keep the chain explicit so you can read it top to bottom.
• Share domain code with Laravel. Put DTOs, validation rules, and business logic in a path-repository package autoloaded by both apps. The failure mode with small frameworks is copy-pasting logic until the two codebases diverge.
• Config via env at process start. There is no config() helper and no .env loader — use vlucas/phpdotenv explicitly if you want one. Read config once at boot, not per request.
• Log to stdout/stderr. Let supervisor/journald capture output. Don't write to Laravel's storage/logs from a separate process unless you wire a Monolog channel deliberately.
• Deploy = restart the process. supervisorctl restart microserve on every deploy; opcache and any in-memory state persist otherwise.

Gotchas and Tips

• Not a Laravel package. No service provider, no facade, no routes/ auto-discovery, no artisan integration. You own server.php, the supervisor unit, and the nginx proxy config.
• Maturity risk is the headline. 2 stars, 0 dependents, single maintainer, last release 2024-07-14. Pin the exact version, read the source before relying on any behaviour, and assume you may end up vendoring or forking it. Budget for that.
• Long-running process semantics. Memory leaks now matter: no unbounded static caches, reset request-scoped state, watch for accumulating event listeners. A leak that is invisible under FPM (process dies after the request) will OOM this server overnight.
• Blocking calls kill concurrency. Any sleep(), synchronous Guzzle call, or remote file_get_contents blocks the entire event loop and stalls every other request. Use async HTTP clients or offload heavy work to a queue/worker.
• No superglobals. $_GET, $_POST, $_SERVER are not the request. Read from the package's Request object. Libraries (and some Laravel helpers) that inspect superglobals will silently misbehave.
• Debugging looks different. var_dump inside a handler prints to the terminal running the server, not the HTTP response. Wrap handlers in try/catch — depending on version, an uncaught exception can drop the connection or take down the process.
• Proxy timeouts mislead you. Behind nginx, a hung handler surfaces as a 504 with no PHP stack trace. Align proxy timeouts with your server's and disable buffering where appropriate.
• Extension points are thin. Sessions, CSRF, ORM integration, and templating are yours to build. That's acceptable for genuinely small endpoints; if you find yourself writing those five things, switch to Laravel Octane or Slim instead.
• Test handlers as plain units. Call handler functions/classes directly with fake Request/Response objects. Fast unit tests without booting the event loop are the main practical advantage this package gives you over spinning up the full Laravel HTTP kernel for a trivial service.