affordablemobiles/g-serverless-support-laravel

Google Serverless runtime support for Laravel apps

v11.0.18 2024-12-11 10:31 UTC

This package is auto-updated.

Last update: 2024-12-11 10:32:32 UTC


README

Latest Stable Version   PHP Version Require   Monthly Downloads   Total Downloads   License

Google App Engine    Google Cloud Run    Google Operations Suite

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

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.