Download the PHP package christianjbrown/cloud-run-function-lib without Composer

Google Cloud Run Function framework

A strongly-typed PHP framework for building Google Cloud Run function HTTP endpoints that return a consistent JSON envelope. You write the business logic; the library handles header-based authorization, CORS, CDN cache-control headers, and uniform success/error responses.

It is built around PSR-7: you hand it a ServerRequestInterface and it returns a ResponseInterface. Configuration is read straight from your Cloud Run environment variables.

• Uniform envelope — every response carries success, timestamp_unix, and timestamp_iso8601, plus data, version (the Cloud Run revision), or error as appropriate.
• Header authorization — optionally require a header key/value before running your handler.
• CORS + caching — Access-Control-*, Vary, Cache-Control, and Surrogate-Control headers derived from config.
• Safe error handling — user-friendly exceptions surface their message; anything else returns a generic error unless DEBUG is on, and is logged to stderr either way.

:heavy_check_mark: Prerequisites

• Git
• PHP 8.5 or higher (8.x)
• Composer

:bulb: If you're on MacOS and have Homebrew, PHP and Composer will install with brew install composer.

:building_construction: Installation

For your composer-enabled project:

:computer: Usage

Implement DataProviderInterface with your endpoint's logic — it receives the PSR-7 request and returns an array that becomes the response data:

Build the function with CloudRunFunctionFactory, which wires every default, and run the request:

If you need the config yourself (for example to wrap it in your own config object), build it with the factory's transformer and pass it to create():

Every collaborator (RequestAuthorizerInterface, JsonResponseFactoryInterface, the config appliers) is an interface injected through a constructor, so any of them can be replaced by building CloudRunFunction yourself. A new environment variable is a new FunctionConfigApplierInterface class registered in the transformer's list.

$response is a PSR-7 response ready to emit (e.g. with guzzlehttp/psr7's HTTP factories or your Cloud Run function's runtime).

Environment variables

FunctionConfigTransformer::transform() (via the factory) reads these keys (only K_REVISION is required — Cloud Run sets it automatically):

Letting a purge reach visitors

By default the browser and the CDN are given the same TTL, so USE_CACHE_TTL=3600 produces:

That max-age is what makes a surrogate-key purge look like it did nothing: the CDN drops its copy, but a visitor who loaded the page in the last hour keeps theirs. Set USE_BROWSER_CACHE_TTL to split the two. With 0:

The browser now revalidates on every page load, which the CDN answers from its own cache, so a purge is visible immediately. Fastly reads Surrogate-Control in preference to Cache-Control and strips it before the response reaches the client, so the CDN's own TTL and its stale-while-revalidate / stale-if-error resilience are untouched.

Note what is not in that Cache-Control: the stale directives carry no s- prefix, so leaving them there would let a browser serve a body days old of its own accord and undo the point of revalidating. They are emitted on Surrogate-Control only whenever USE_BROWSER_CACHE_TTL is set.

Leave the variable unset and the headers are exactly as they were before it existed.

Response shape

A successful response:

An error response omits data and adds error:

:rotating_light: Error handling

Inside your DataProviderInterface::getData(), throwing an exception that implements christianjbrown/user-friendly-exception's UserFriendlyExceptionInterface returns its message to the client (HTTP 500). Any other Throwable returns a generic "An unhandled error occurred" message — unless DEBUG is enabled, in which case the raw message is returned to aid debugging. In both cases the Throwable is written to stderr with error_log(), so the cause is kept in Cloud Logging against the failing request rather than discarded with the response. A failed authorization check short-circuits with "Not authorized" (HTTP 401) before your handler runs.

:arrow_up: Upgrading to 2.0

CloudRunFunction no longer builds its own collaborators, FunctionConfig is immutable, and the response classes are gone. Everything is built by CloudRunFunctionFactory.

Building the function:

Building a config by hand (tests, for example):

Responses:

new FunctionConfigTransformer() with no arguments no longer works: it needs its list of appliers, which CloudRunFunctionFactory::createConfigTransformer() supplies.

:memo: Changelog

Notable changes in each release are listed in CHANGELOG.md.

:page_facing_up: License

Released under the MIT License.