Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/affordablemobiles/gserverlesssupportlaravel

Run Laravel on Google Serverless
https://github.com/affordablemobiles/gserverlesssupportlaravel

appengine appengine-php cloud-run gae gcr google-appengine google-cloud google-cloud-run laravel php

Last synced: 7 days ago
JSON representation

Run Laravel on Google Serverless

Host: GitHub
URL: https://github.com/affordablemobiles/gserverlesssupportlaravel
Owner: affordablemobiles
License: mit
Created: 2017-05-03T10:24:23.000Z (over 7 years ago)
Default Branch: php8.3-laravel11.x
Last Pushed: 2024-12-11T10:32:28.000Z (about 1 month ago)
Last Synced: 2024-12-20T00:02:52.226Z (about 1 month ago)
Topics: appengine, appengine-php, cloud-run, gae, gcr, google-appengine, google-cloud, google-cloud-run, laravel, php
Language: PHP
Homepage:
Size: 1.53 MB
Stars: 26
Watchers: 6
Forks: 17
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS

Awesome Lists containing this project

README

# GServerlessSupportLaravel

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](https://github.com/shpasser/GaeSupportL5) using the `php55` runtime) by [@shpasser](https://github.com/shpasser).

## Functionality
* **Google Cloud Operations Suite** integration
* **Cloud Logging** destination with structured logs (see [docs/logging.md](docs/logging.md)).
* **Error Reporting** integration for aggregation of reported exceptions (see [docs/logging.md](docs/logging.md#error-reporting)).
* **Cloud Trace** (via [opentelemetry](https://github.com/open-telemetry/opentelemetry-php)) (see [docs/trace.md](docs/trace.md))
* Distributed trace propagation via [Guzzle](src/AffordableMobiles/GServerlessSupportLaravel/Trace/Instrumentation/Guzzle/GuzzleInstrumentation.php#L70).
* Integration with [laravel-debugbar](https://github.com/barryvdh/laravel-debugbar) (optional, see [docs/debugbar.md](docs/debugbar.md)).
* **Identity Aware Proxy (IAP)** integration
* **Inbound authentication** via Laravel's Guards (optional, see [docs/iap-auth-verify.md](docs/iap-auth-verify.md)).
* **Outbound authentication** via Guzzle middleware (optional, see [docs/guzzle.md](docs/guzzle.md#authtokenmiddleware)).
* **Cloud SQL** integration
* **IAM Authentication** (optional, see [docs/cloud-sql.md](docs/cloud-sql.md#iam-authentication)).
* Automatic failover between read replicas (optional, see [docs/cloud-sql.md](docs/cloud-sql.md#multiple-read-replicas)).
* **Query Insights** integration via [eloquent-sqlcommenter](https://github.com/affordablemobiles/eloquent-sqlcommenter) (optional, see [docs/cloud-sql.md](docs/cloud-sql.md#query-insights)).
* **Cloud Firestore in Datastore mode** integration
* **Session handler** (optional, see [docs/sessions.md](docs/sessions.md)).
* **Eloquent driver** via [eloquent-datastore](https://github.com/affordablemobiles/eloquent-datastore).
* Optimizations for containerized deployment
* `bootstrap/cache` generation before deployment (see [g-serverless:prepare](src/AffordableMobiles/GServerlessSupportLaravel/Console/GServerlessPrepareCommand.php)).
* Blade View Pre-Compiler (optional, see [docs/blade-pre-compile.md](docs/blade-pre-compile.md))
* Automatic retries for outbound connections on network layer failure with Guzzle (optional, see [docs/guzzle.md](docs/guzzle.md#guzzleretrymiddleware))
* [Domain Wide Delegation (DWD)](src/AffordableMobiles/GServerlessSupportLaravel/Integration/Google/Credentials/GCEDWDCredentials.php#L12) support via [IAM Credentials API](https://cloud.google.com/iam/docs/reference/credentials/rest) (no key file required).
* [IAMSigner](src/AffordableMobiles/GServerlessSupportLaravel/Integration/JWT/Signer/IAMSigner.php) for [lcobucci/jwt](https://github.com/lcobucci/jwt) using [IAM Credentials API](https://cloud.google.com/iam/docs/reference/credentials/rest).
* Examples for push-to-deploy from Git via Cloud Build with Secret Manager (see [docs/cloudbuild.md](docs/cloudbuild.md))

## Installation

**1.** Pull in the package via Composer:

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

**2.** Add the following to `composer.json`:

```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:

```php
use Illuminate\Foundation\Application;
```

to:

```php
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](https://console.cloud.google.com/apis/api/logging.googleapis.com/overview) - _append `?project=` to the URL if necessary._
* Assign the IAM permission "Logs Writer" to your service account.
* [Enable the Trace API](https://console.cloud.google.com/apis/api/cloudtrace.googleapis.com/overview) - _append `?project=` 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:

```php
/*
|--------------------------------------------------------------------------
| 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)
[email protected] (default, required for Cloud Run)
OIDC_AUDIENCE= (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`:

```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](https://github.com/affordablemobiles/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](src/AffordableMobiles/GServerlessSupportLaravel/Integration/Google/Credentials/GCEDWDCredentials.php).

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