README

Google Serverless runtime support package for Laravel 11.x.

Supporting Cloud Run & App Engine (Standard Environment) with the php83 runtime.

Based on original work for App Engine (GaeSupportL5 using the php55 runtime) by @shpasser.

Functionality

Google Cloud Operations Suite integration
- Cloud Logging destination with structured logs (see docs/logging.md).
- Error Reporting integration for aggregation of reported exceptions (see docs/logging.md).
- Cloud Trace (via opentelemetry) (see docs/trace.md)
  - Distributed trace propagation via Guzzle.
  - Integration with laravel-debugbar (optional, see docs/debugbar.md).
Identity Aware Proxy (IAP) integration
- Inbound authentication via Laravel's Guards (optional, see docs/iap-auth-verify.md).
- Outbound authentication via Guzzle middleware (optional, see docs/guzzle.md).
Cloud SQL integration
- IAM Authentication (optional, see docs/cloud-sql.md).
- Automatic failover between read replicas (optional, see docs/cloud-sql.md).
- Query Insights integration via eloquent-sqlcommenter (optional, see docs/cloud-sql.md).
Cloud Firestore in Datastore mode integration
- Session handler (optional, see docs/sessions.md).
- Eloquent driver via eloquent-datastore.
Optimizations for containerized deployment
- bootstrap/cache generation before deployment (see g-serverless:prepare).
- Blade View Pre-Compiler (optional, see docs/blade-pre-compile.md)
- Automatic retries for outbound connections on network layer failure with Guzzle (optional, see docs/guzzle.md)
Domain Wide Delegation (DWD) support via IAM Credentials API (no key file required).
IAMSigner for lcobucci/jwt using IAM Credentials API.
Examples for push-to-deploy from Git via Cloud Build with Secret Manager (see docs/cloudbuild.md)

Installation

1. Pull in the package via Composer:

    "require": {
        "affordablemobiles/g-serverless-support-laravel": "~11"
    }

2. Add the following to composer.json:

    "scripts": {
        "post-autoload-dump": [
            "php artisan g-serverless:prepare"
        ]
    },

This is to automatically run the artisan command that prepares our app for deployment after composer finishes running: this creates any necessary cache files and if enabled, pre-compiles all of the blade views.

If you are deploying with Cloud Build, composer install is likely to run just before packaging/deployment to your chosen serverless product, so this will ensure everything else required runs as part of that step.

3. Update the use statement at the top of bootstrap/app.php from:

use Illuminate\Foundation\Application;

to:

use AffordableMobiles\GServerlessSupportLaravel\Foundation\Application;

This will enable automatic exception reporting to Cloud Logging & Error Reporting, alongside adjusting the emergency logger to work correctly inside the containerized environment by writing to stderr.

Important: the Logging API & the Trace API need to be enabled within your project, and the service account being used by your serverless app needs to have IAM permissions to use them:

Enable the Logs API - append ?project=<project-name> to the URL if necessary.
Assign the IAM permission "Logs Writer" to your service account.
Enable the Trace API - append ?project=<project-name> to the URL if necessary.
Assign the IAM permission "Cloud Trace Agent" to your service account.

4. Configure the service providers within config/app.php by adding:

    /*
    |--------------------------------------------------------------------------
    | Autoloaded Service Providers
    |--------------------------------------------------------------------------
    |
    | The service providers listed here will be automatically loaded on any
    | requests to your application. You may add your own services to the
    | arrays below to provide additional features to this application.
    |
    */

    'providers' => \Illuminate\Support\ServiceProvider::defaultProviders()->merge([
        // Package Service Providers...
        \AffordableMobiles\GServerlessSupportLaravel\GServerlessSupportServiceProvider::class,
        \AffordableMobiles\GServerlessSupportLaravel\Auth\AuthServiceProvider::class,
        \AffordableMobiles\GServerlessSupportLaravel\Database\DatabaseServiceProvider::class,
    ])->replace([
        \Illuminate\View\ViewServiceProvider::class => \AffordableMobiles\GServerlessSupportLaravel\View\ViewServiceProvider::class,
    ])->toArray(),

5. Add the following environment variables:

This can be done either in .env, inside app.yaml, or as part of the Cloud Run service configuration - we recommend the latter two options where possible.

LOG_CHANNEL=stderr
LOG_STDERR_FORMATTER=AffordableMobiles\GServerlessSupportLaravel\Log\Formatter\JsonFormatter

CACHE_STORE=array

SESSION_DRIVER=datastore

When using Cloud Tasks, you'll also want to configure:

CLOUD_TASKS_REGION=europe-west1 (or similar, required)
TASK_QUEUE_SERVICE_ACCOUNT=<project-name>@appspot.gserviceaccount.com (default, required for Cloud Run)
OIDC_AUDIENCE=<OAuth2 Client ID used by IAP, if enabled for inbound calls to your app> (required for Cloud Run)

If you are using an external CDN such as Cloudflare, also configure the following environment variable with the name of the HTTP header used for passing the client's IP address:

SOURCE_IP_HEADER=CF-Connecting-IP

And if you need to disable OpenTelemetry tracing (we highly recommend you leave it enabled), define the following environment variable:

G_SERVERLESS_TRACE_STOP=true

Also, if running in a development environment, please also set the following:

G_SERVERLESS_DEVELOPMENT=true

This does several things, such as:

Alters the local storage location to include HTTP_HOST.
Turns OpenTelemetry tracing on for every request.
Turns off sticky database connections per instance.

Upgrading (from Laravel 9.x LTS)

1. Update the package version in composer.json:

    "require": {
        "affordablemobiles/g-serverless-support-laravel": "~11"
    }

2. Follow the Laravel upgrade steps for all versions 9.x ... 11.x

3. Update any references in your code to our namespace:

A1comms\GaeSupportLaravel

has changed to:

AffordableMobiles\GServerlessSupportLaravel

4. Ensure bootstrap/app.php is extending our Application class:

Please see step 3 in the main installation guide as an example.

5. Change to the new provider configuration format in config/app.php:

Please see step 4 in the main installation guide as an example.

6. Update explicit/silent exception reporting:

Anywhere referencing the Error Reporting integration class directly:

AffordableMobiles\GServerlessSupportLaravel\Integration\ErrorReporting::exceptionHandler($e);

should be updated to report using Laravel's new method:

report($e);

7. Revert config/logging.php to the Laravel default.

8. Update environment variables:

Please see step 5 in the main installation guide & update your environment variables accordingly.

9. If you are using php-gds for Datastore, consider switching to eloquent-datastore.

Otherwise, you'll need to require it via composer yourself, as it is no longer required by this repository.

10. If using the lcobucci/jwt compatible DWDTokenSource, it has now been removed.

Migrate to the google/auth compatible GCEDWDCredentials.

11. Update your app.yaml file(s) to specify runtime: php83.

affordablemobiles / g-serverless-support-laravel

Maintainers

Details

README

Functionality

Installation

Upgrading (from Laravel 9.x LTS)