G Serverless Support Laravel Laravel Package

Getting Started

What it is. A thin compatibility layer that makes a stock Laravel app behave on Google's serverless runtimes (Cloud Run, App Engine standard, Cloud Functions). It does not replace Laravel — it patches the assumptions Laravel makes about a writable, persistent, single-instance filesystem and about where logs go.

Minimum steps

1. composer require affordablemobiles/g-serverless-support-laravel
2. Confirm the service provider is auto-discovered (php artisan about or php artisan package:discover). If you have a custom FilesystemServiceProvider or exception handler override, resolve the ordering now rather than in production.
3. Publish anything it ships: php artisan vendor:publish --provider="GServerlessSupportLaravel\...ServiceProvider" — check vendor/affordablemobiles/g-serverless-support-laravel/ for the actual provider name and any config/ stubs.
4. Build a container, deploy to Cloud Run, and hit a route that writes a file and throws an exception. Those two paths exercise 90% of what the package fixes.

Where to look first

• The README's configuration table — it is the only reliable index of which behaviours are opt-in.
• src/ — the package is small; you can read the whole thing in an hour and you probably should, because there are ~33 stars and no public dependents, meaning you are the support channel.
• Your config/filesystems.php, config/logging.php, and config/view.php — those are the three files the package most often needs to override.

Best first use case. A single Cloud Run service running an existing Laravel app where the only production symptoms are (a) failed to open stream: Read-only file system and (b) log lines arriving in Cloud Logging as unparsed blobs. Fix those two, verify, then layer on tracing and IAP.

Implementation Patterns

Build-time over runtime. Serverless instances are cold, short-lived, and read-only. Everything cacheable should be baked into the image:

RUN composer install --no-dev --optimize-autoloader --classmap-authoritative
RUN php artisan config:cache && php artisan route:cache && php artisan view:cache
RUN php artisan event:cache

view:cache at build time is the single most effective way to avoid the compiled-views-write failure without depending on /tmp behaviour. If the package redirects the view compiler path, verify it still works after view:cache — you want precompiled paths in the image, with /tmp only as a fallback.

Storage. Let the package remap the local disk to a GCS bucket so unmodified framework code (Storage::disk('local'), file-based cache, uploaded temp files) keeps working. In practice:

• Treat the mapped local disk as private and durable — it is a bucket, not a scratch dir.
• Keep a genuine /tmp path for anything write-heavy and disposable (intervention/image, PDF generation, zip streaming). /tmp on Cloud Run counts against instance memory.
• Use signed URLs for user-facing downloads instead of proxying bytes through PHP.

Logging. Route the stack/single channel to stdout and let the package's formatter emit structured JSON with severity, message, and logging.googleapis.com/trace. Two config moves make this pay off:

// config/logging.php
'stdout' => [
    'driver'  => 'monolog',
    'handler' => StreamHandler::class,
    'with'    => ['stream' => 'php://stdout'],
    'formatter' => \GServerlessSupportLaravel\Log\...Formatter::class, // per README
],

Then add a Log::withContext(['trace' => ...]) in middleware so every line in a request correlates to a Cloud Trace span. Without the trace field, Cloud Logging's "show related" is useless.

Tracing / request middleware. Register the package's middleware globally (not on a route group) so it sees every request including health checks and 404s. It reads X-Cloud-Trace-Context, which Cloud Run injects; it only works if your proxy/ingress preserves the header.

IAP authentication. If the service sits behind Identity-Aware Proxy, the package's guard lets you authenticate users from the X-Goog-Authenticated-User-Email header instead of standing up a full login flow. Map it to a local user record:

// config/auth.php
'guards' => [
    'iap' => ['driver' => 'iap', 'provider' => 'users'],
],

Use it as a supplement, not a replacement: keep a normal guard for admin tooling and local development, and gate the IAP guard on an env flag so php artisan serve and tests never exercise it.

Sessions, cache, queues. These are not really the package's job, and that's the trap. On a multi-instance service:

• Sessions → Redis (Memorystore) or Firestore. Never the file driver.
• Cache → Redis. cache:table/database cache is viable but adds latency per request.
• Queues → Cloud Tasks or Pub/Sub, or a dedicated Cloud Run worker service with CPU always allocated. A queue worker in the same request-serving container will be throttled and eventually killed.

Config and secrets. Keep secrets in Secret Manager mounted as env vars (--set-secrets), not in config:cache'd files, and not fetched at boot with a network call — that adds cold-start latency to every instance.

Local parity. Gate all package behaviour behind an env flag (G_SERVERLESS=true) so php artisan test and Sail behave normally. A package that silently remaps disks is a debugging nightmare on a laptop.

Gotchas and Tips

/tmp is RAM, not disk. Cloud Run's writable layer is memory-backed and per-instance. A 200 MB temp file is a 200 MB memory spike, and it vanishes on the next request that lands on a different instance. Never use it for anything you need to read back.

File-based anything breaks at scale. The moment min-instances > 1 or max-instances > 1, sessions, cache, and storage/framework/* stop being coherent across requests. This is the number-one source of "works locally, randomly logs users out in prod."

Trusted proxies. Cloud Run terminates TLS. Without TrustProxies set to * (or the Google front-end ranges), url() and secure_url() generate http:// links and redirects loop. This looks like a package bug and isn't.

Health checks. Point the Cloud Run startup probe at a /up-style route that touches nothing — no DB, no Redis, no GCS. A probe that depends on downstream services will restart healthy instances during a transient outage.

Log parsing is fragile. Multi-line stack traces and var_dump to stdout corrupt Cloud Logging's structured parsing. Force single-line JSON, and put payloads in context, not in the message string.

IAP header spoofing. The X-Goog-Authenticated-User-Email header is only trustworthy if the service is only reachable through IAP. If Cloud Run allows allUsers ingress on the run.app URL, anyone can forge it. Set ingress to internal-and-cloud-load-balancing and verify with curl from outside.

Trace context is request-scoped. Queued jobs and scheduled commands start with no trace header, so their logs orphan in Cloud Logging. Pass the trace ID into the job payload if correlation matters to you.

Cold starts are your latency budget. Every extra service provider, every config() call that hits the network, every facade that boots a client costs ~10–100 ms per cold start. php artisan about and Blackfire are worth running once on a cold instance.

Extension points are minimal by design. This is a small package; where it doesn't cover your case, prefer standard Laravel extension points (custom FilesystemManager, custom Monolog formatter, Illuminate\Contracts\Debug\ExceptionHandler) over patching vendor/. You'll get a cleaner upgrade path.

Pin the version. 33 stars and zero dependents means no downstream canary population — a bad release reaches you first. composer require with an explicit constraint, and re-test the three core paths (storage write, exception logging, view render) on every Laravel minor upgrade.

Debugging checklist when a deploy misbehaves: (1) php artisan config:show filesystems inside the running container, (2) confirm LOG_CHANNEL=stdout, (3) check whether the failing path is under /tmp or a bucket, (4) verify the instance count is 1 before blaming the package for state loss.