Runtime Adapters#

One public/index.php serves a Kinetis application under FrankenPHP, PHP-FPM, RoadRunner and AWS Lambda:

public/index.php#
use Kinetis\Runtime\HttpStartup;

require dirname(__DIR__) . '/vendor/autoload.php';

HttpStartup::run(__DIR__);

HttpStartup detects the runtime once per boot and drives it through its adapter. Application code does not change between runtimes; the deployment chooses the runtime and sets the few server settings this page lists.

Choose a runtime#

Runtime

Process model

Package

Choose it for

FrankenPHP worker mode

Each worker thread boots once and serves request after request

core

Production on a container or VM — Kinetis’s primary target

PHP-FPM

Every request runs public/index.php from the start

core

Development with edit-and-reload, or an existing FPM platform

RoadRunner

Persistent PHP worker processes behind RoadRunner’s Go server

kinetis/roadrunner-adapter

A persistent worker on a RoadRunner platform

AWS Lambda

A warm execution environment serves one invocation at a time

kinetis/bref-adapter

An API Gateway HTTP API or a Lambda Function URL

Detection checks frankenphp_handle_request(), then RR_MODE=http, then AWS_LAMBDA_RUNTIME_API, and falls back to PHP-FPM. A RoadRunner or Lambda signal without its package installed fails at startup with a message naming the package to install.

The choice changes four things an application acts on:

  • Code changes. A persistent worker (FrankenPHP, RoadRunner) keeps loaded classes in memory, so an edited controller takes effect after a restart. PHP-FPM under APP_ENV=development picks it up on the next request.

  • Request isolation. Under a persistent worker, application-scoped services outlive the request. Request data belongs in the request scope, never in a static or a shared service — see Appendix: Container Lifecycle.

  • Database I/O. DB_DRIVER=auto selects the native non-blocking drivers under FrankenPHP and RoadRunner, and one blocking PDO connection under PHP-FPM and Lambda. When the overlap is real shows what that means for concurrently().

  • Streaming. FrankenPHP and PHP-FPM stream a StreamedResponse. RoadRunner answers one with 501, and Lambda fails the invocation.

Every runtime also needs the settings under “Request bodies: one contract under every runtime” and, behind a proxy, TRUSTED_PROXIES.

Running under FrankenPHP#

Worker mode needs one PHP setting and the worker script:

docker/kinetis.ini#
enable_post_data_reading=0
docker run --rm -p 8080:8080 -v "$PWD":/app -w /app \
    -v "$PWD/docker/kinetis.ini":/usr/local/etc/php/conf.d/zz-kinetis.ini:ro \
    dunglas/frankenphp:1.13.5-php8.5.12 \
    frankenphp php-server --listen :8080 --root /app/public --worker /app/public/index.php

enable_post_data_reading=0 is required: without it PHP consumes and truncates the body before Kinetis runs, and the adapter refuses to serve. kinetis/pingpong’s image uses this command. Its docker/kinetis.ini carries this setting and also turns PHP’s error display off, so a diagnostic reaches the container log rather than the response body.

A worker keeps public/index.php, including route discovery, loaded across requests, so a code change needs a container restart. Use PHP-FPM while editing code constantly.

Command-line services on the same image#

The dunglas/frankenphp image declares a HEALTHCHECK that requests http://localhost:2019/metrics, the admin endpoint of a running FrankenPHP server. A container built from that image that runs migrate, queue:work or a scheduled command instead never answers it, so Docker reports the container unhealthy. A service_healthy dependency on it never starts, and an orchestrator that replaces unhealthy containers restarts a working queue worker. Disable the inherited check on every service that does not run the server:

docker-compose.yml#
  queue-worker:
    build:
      context: .
      dockerfile: docker/Dockerfile
    command: ["php", "vendor/bin/kinetis", "queue:work"]
    healthcheck:
      disable: true

kinetis/pingpong’s docker-compose.yml does this for its migrate, queue-worker and cron services.

A Compose depends_on on a database service needs a healthcheck that passes only once the database accepts TCP connections; the Postgres healthcheck in the tutorial shows why a bare pg_isready releases dependents too early.

Sizing FrankenPHP’s worker threads#

Each worker thread processes one HTTP request at a time, start to finish. concurrently() overlaps work inside one request; a thread suspended on a database response is still not free to take a second request. Cross-request concurrency is the thread count. Set it with a worker block in the Caddyfile’s global frankenphp block:

Caddyfile#
{
    frankenphp {
        worker {
            file public/index.php
            num 20
        }
    }
}

or the shorthand worker public/index.php 20 in the same place. Left unset, FrankenPHP starts roughly 2× the CPU cores.

  • Requests dominated by waiting — slow queries, remote APIs — want num well above the core count, closer to the expected number of concurrent requests. Undersizing produces queueing that looks like a slow application.

  • Requests mixing CPU with fast queries — the common case with the native drivers — want num around 2–3× the core count. On an 8-vCPU host against a sub-millisecond database, 20 threads outperform 8 on every database-touching route (a 20-query fan-out by ~10%, single-query routes by ~9%) with no loss on CPU-pure routes.

When every thread is busy, a new request waits for one, and by default it waits without limit. Set max_wait_time in the same frankenphp block so an overloaded server answers 503 Service Unavailable instead of growing an unbounded queue:

Caddyfile#
{
    frankenphp {
        max_wait_time 5s
    }
}

Pick a value below the client’s or load balancer’s timeout, so the client gets a fast, retryable 503 rather than a timeout.

Every thread runs bootstrap.php and the package bootstraps, so each builds its own database pool. Keep threads × DB_MAX_CONNECTIONS under the database’s connection limit — see Database’s “Sizing maxConnections under worker mode” and Performance tuning. Measure under realistic load: the two regimes want opposite corrections.

Install ext-event#

Without a loop extension, Revolt uses a select()-based driver that cannot watch a file descriptor numbered above 1024. The native Postgres driver, the Redis client and the HTTP client register socket watchers, and under FrankenPHP the Go server’s client sockets share the process’s descriptor table, so descriptor numbers pass 1024 under load. Install ext-event (pecl install event) in any image that uses those clients; Revolt selects it automatically. This is a correctness requirement, not tuning. ext-ev and ext-uv also work; ext-uv’s only release is a beta that must be pinned (pecl install uv-0.3.0).

The native MySQL driver registers no socket watcher, but mysqli’s own poll has a separate descriptor ceiling that no loop extension lifts — see Performance tuning’s “mysqli’s poll limit”.

Running under PHP-FPM#

PHP-FPM needs the same PHP setting, and the web server in front of it needs a body limit at least as large as MAX_BODY_SIZE:

docker/Dockerfile#
FROM php:8.4.27-fpm-alpine
WORKDIR /app
COPY docker/kinetis.ini /usr/local/etc/php/conf.d/zz-kinetis.ini
CMD ["php-fpm", "-F"]
docker/nginx.conf#
server {
    listen 8080;

    root /app/public;
    index index.php;

    # nginx reads the body before PHP does, so this must be at least
    # Kinetis's MAX_BODY_SIZE; raise both together.
    client_max_body_size 2m;

    location / {
        try_files $uri /index.php$is_args$args;
    }

    location ~ \.php$ {
        fastcgi_pass app:9000;
        fastcgi_index index.php;
        fastcgi_param SCRIPT_FILENAME /app/public/index.php;
        include fastcgi_params;
    }
}

docker/kinetis.ini carries the enable_post_data_reading=0 shown under FrankenPHP. kinetis/skeleton ships this setup with a docker-compose.yml that mounts the project at /app in both containers and names the PHP-FPM service app. Its copy of the ini also turns PHP’s error display off, so a diagnostic reaches the container log rather than the response body.

nginx answers a body over client_max_body_size with its own 413 before PHP runs. Its default is 1 MiB, under the 2 MiB MAX_BODY_SIZE default, which is why the configuration sets 2m.

nginx buffers a FastCGI response and delivers it once the script ends, which turns a streamed response — an MCP progress stream, any StreamedResponse — into one delayed lump. Add fastcgi_buffering off; to the PHP location, or send X-Accel-Buffering: no on the streamed response.

Every request reruns public/index.php, so production PHP-FPM depends on the prebuilt artifact Caching & AOT Compilation describes.

Running under RoadRunner#

Note

Not part of core. Install it separately:

composer require kinetis/roadrunner-adapter

The package brings roadrunner/worker and roadrunner/http. rr serve sets RR_MODE=http for the worker it spawns, which selects the adapter. Two settings in .rr.yaml are required:

.rr.yaml#
version: "3"

server:
  command: "php public/index.php"

http:
  address: 0.0.0.0:8080
  raw_body: true
  max_request_size: 10
rr serve -c .rr.yaml
  • http.raw_body: true hands PHP the bytes the client sent. Without it RoadRunner parses form bodies in Go and answers a body it cannot parse itself. The adapter checks this on every request and refuses to serve with an error naming the setting.

  • http.max_request_size, in megabytes, bounds the body before PHP.

http.max_request_size is the real defense against an oversized body#

Warning

RoadRunner reads the whole body into memory before any PHP runs, and its default max_request_size is 1000 MB. MAX_BODY_SIZE refuses a body Kinetis already holds; it cannot bound RoadRunner’s read, and a chunked body with no declared length has no other bound. Set max_request_size explicitly to what the application accepts, and set MAX_BODY_SIZE to match (MAX_BODY_SIZE=10485760 alongside max_request_size: 10), or a body between the two limits reaches PHP and is refused there.

ext-sockets under an Alpine-based image#

roadrunner/worker requires ext-sockets. On an Alpine image, docker-php-ext-install sockets also needs linux-headers:

FROM php:8.4.27-cli-alpine
RUN apk add --no-cache $PHPIZE_DEPS linux-headers \
 && docker-php-ext-install sockets

Sizing RoadRunner’s worker processes#

http.pool.num_workers sets the number of PHP worker processes, each serving one request at a time. Size it the way Sizing FrankenPHP’s worker threads describes: each process builds its own database pool, and the thread ratios measured for FrankenPHP have not been re-measured for processes.

A crash in one request doesn’t take the worker down#

An exception a handler throws is reported to RoadRunner with Worker::error(), which answers that one client with an error, and the worker keeps serving. Recycling persistent workers covers the settings that replace a worker.

What isn’t supported#

  • Response streaming. A StreamableResponseInterface is answered with 501, never buffered or dropped silently.

  • Cookie order. Names and values arrive intact; their order may not.

Forwarded headers and the RoadRunner section of Appendix: Runtime Reference give the detection and delivery details.

Running on AWS Lambda#

Note

Not part of core. Install it separately:

composer require kinetis/bref-adapter

BrefLambdaAdapter polls the Lambda Runtime API itself, with no bref/bref handler in between: the one PHP process a Lambda container runs must execute public/index.php directly, and it is that process for which Lambda sets AWS_LAMBDA_RUNTIME_API, which the adapter reads to select itself.

A bref/php-84 image does not do that on its own. Its CMD is a handler string, not a command — the image’s entrypoint reads CMD into _HANDLER and then runs /var/runtime/bootstrap, which starts Bref’s own runtime and never reaches Kinetis’s front controller.

Replacing the runtime bootstrap#

Replace /var/runtime/bootstrap so it runs public/index.php instead:

docker/lambda/Dockerfile#
FROM bref/php-84:3
COPY . /var/task
COPY docker/lambda/bootstrap /var/runtime/bootstrap
RUN chmod 0755 /var/runtime/bootstrap
CMD ["public/index.php"]
docker/lambda/bootstrap#
#!/bin/sh
exec /opt/bin/php /var/task/public/index.php

CMD still satisfies the entrypoint’s one required argument, but Kinetis reads no _HANDLER and ignores it. exec replaces the shell with PHP, so PHP itself becomes the container’s runtime process. The entrypoint itself is unchanged, and the Runtime Interface Emulator it embeds for local invocations runs this same replacement bootstrap. Pin bref/php-84 by tag or digest: this recipe relies on /var/runtime/bootstrap and /opt/bin/php existing at those exact paths.

The image must already contain vendor/ and, in production, .kinetis-cache/compiled.php — see Caching & AOT Compilation. Lambda’s /var/task is read-only. COPY copies only what .dockerignore permits, and the skeleton’s own .dockerignore excludes both directories.

  • Invoke it through an HTTP API or a Function URL. The adapter reads payload format 2.0 only. ALB events, REST API (payload format 1.0) events, and any event that fails validation are reported to Lambda as invocation errors and never reach a route; see Streaming and Runtime API failures for what an invocation error logs and returns.

  • Databases use PDO. DB_DRIVER=auto selects a blocking PDO connection. Database’s “Driver selection” covers when to select DB_DRIVER=native on Lambda.

  • The body limit is the platform’s first. API Gateway accepts and holds the whole body, up to Lambda’s 6 MB invocation payload, before the adapter runs. MAX_BODY_SIZE refuses a larger body after delivery.

  • The scheme is always https. An HTTP API and a Function URL are TLS-only; an event whose x-forwarded-proto claims http is refused. TRUSTED_PROXIES does not apply.

  • Binary responses and cookies need no code. A response body that is not valid UTF-8 is base64-encoded for API Gateway, and every Set-Cookie becomes its own cookie entry.

What Lambda does not support:

  • Response streaming. A StreamableResponseInterface fails the invocation rather than being buffered. Lambda response streaming is a different invocation model this adapter does not implement.

  • An unreachable Runtime API. A failed poll or response post throws, and the function reports an error in CloudWatch — see Streaming and Runtime API failures.

AWS Lambda events lists every validated event field, how the request’s host, port and target are derived, and how each field maps to PSR-7.

Docker Compose on one EC2 instance#

One instance runs the FrankenPHP app, a queue worker, PostgreSQL and Redis under Compose. The instance role supplies AWS credentials, an EBS volume holds the data, SSM Parameter Store holds the secrets, and CloudWatch Logs receives the output.

/srv/app/compose.yaml#
x-app: &app
  image: registry.example.com/app:1.4.0
  env_file:
    - path: app.env
      format: raw
  logging: &logging
    driver: awslogs
    options:
      awslogs-region: eu-west-1
      awslogs-group: /app/prod
      awslogs-create-group: "true"
  restart: unless-stopped

services:
  app:
    <<: *app
    ports:
      - "8080:8080"
    depends_on:
      migrate:
        condition: service_completed_successfully
      redis:
        condition: service_started

  queue-worker:
    <<: *app
    command: ["php", "vendor/bin/kinetis", "queue:work"]
    healthcheck:
      disable: true
    depends_on:
      migrate:
        condition: service_completed_successfully
      redis:
        condition: service_started

  migrate:
    <<: *app
    command: ["php", "vendor/bin/kinetis", "migrate"]
    restart: "no"
    healthcheck:
      disable: true
    depends_on:
      postgres:
        condition: service_healthy

  postgres:
    image: postgres:17
    env_file:
      - path: postgres.env
        format: raw
    volumes:
      - /srv/data/postgres:/var/lib/postgresql/data
    healthcheck:
      # "app" is POSTGRES_USER from postgres.env.
      test: ["CMD", "pg_isready", "-h", "127.0.0.1", "-U", "app"]
      interval: 5s
      retries: 20
    logging: *logging
    restart: unless-stopped

  redis:
    image: redis:8-alpine
    command: ["redis-server", "--appendonly", "yes"]
    volumes:
      - /srv/data/redis:/data
    logging: *logging
    restart: unless-stopped

migrate runs once and gates the app and the worker, as in the tutorial’s Storing pings, whose healthcheck note explains the pg_isready -h 127.0.0.1 probe. The worker and migrate disable the inherited FrankenPHP healthcheck, per Command-line services on the same image. Stop signal and grace period for the worker are in Queue’s “Deploys and restarts”.

Credentials from the instance role. kinetis/queue-sqs and kinetis/storage-s3 resolve credentials through a chain that ends at the instance metadata service (Credential resolution), so the environment carries no AWS keys. IMDSv2 answers the session-token PUT with an IP hop limit of 1 by default, and a container on Compose’s bridge network is one hop further away, so its token request never gets a reply. Allow two hops:

aws ec2 modify-instance-metadata-options \
    --instance-id i-0123456789abcdef0 \
    --http-tokens required \
    --http-put-response-hop-limit 2 \
    --http-endpoint enabled

Every container on the instance then gets the role’s credentials, so grant the role only what the application needs. A third-party client, such as a mailer transport for SES, uses the role only when it falls back to the default AWS credential chain; check its own documentation.

Data on an EBS volume. Mount a separate EBS volume at /srv/data and bind-mount the PostgreSQL and Redis data directories from it. --appendonly yes makes Redis log every write, so a restart loses at most the last second of queued jobs and sessions rather than everything since its last snapshot. Start Compose only after the volume is mounted (RequiresMountsFor= below); otherwise Docker creates empty directories on the root volume and PostgreSQL initialises a new, empty cluster there. Back up with EBS snapshots, scheduled through Amazon Data Lifecycle Manager or aws ec2 create-snapshot --volume-id. A snapshot of the running volume is crash-consistent, and PostgreSQL recovers from it as from a power loss while its whole data directory is on that one volume. A volume lives in one Availability Zone; a replacement instance elsewhere starts from a snapshot.

Only the data volume has to survive instance replacement. The image comes from the registry, the secrets from Parameter Store, and compose.yaml, the systemd unit and the fetch script from your provisioning. The root volume is disposable.

Secrets from SSM Parameter Store. Kinetis reads configuration from the environment and .env only (Configuration). Write the parameters to env files before Compose starts:

/srv/app/fetch-env#
#!/bin/sh
set -eu
umask 077

fetch() {
    aws ssm get-parameters-by-path --region eu-west-1 --path "$1" --with-decryption \
        --query 'Parameters[*].[Name,Value]' --output text > "$2.raw"
    awk -F '\t' '{ name = $1; sub(/.*\//, "", name); print name "=" substr($0, length($1) + 2) }' \
        "$2.raw" > "$2.tmp"
    rm "$2.raw"
    mv "$2.tmp" "$2"
}

fetch /app/prod/app/ /srv/app/app.env
fetch /app/prod/postgres/ /srv/app/postgres.env
/etc/systemd/system/app.service#
[Unit]
Requires=docker.service
After=docker.service network-online.target
Wants=network-online.target
RequiresMountsFor=/srv/data

[Service]
Type=oneshot
RemainAfterExit=yes
WorkingDirectory=/srv/app
ExecStartPre=/srv/app/fetch-env
ExecStart=/usr/bin/docker compose up -d --remove-orphans
ExecStop=/usr/bin/docker compose down

[Install]
WantedBy=multi-user.target

A parameter /app/prod/app/DB_PASSWORD becomes DB_PASSWORD=<value> in app.env. Each path holds one service’s keys, so PostgreSQL never receives the application’s secrets. The files are created mode 0600, live only on the host, and stay out of the image and its build context. format: raw passes each value to the container unchanged, with no interpolation of $ or quotes. Each value must be a single line.

The role needs ssm:GetParametersByPath on both paths, and kms:Decrypt on the key when SecureString parameters use a customer managed key. A container receives the env file when Compose creates it, and the application reads its configuration once at boot (Configuration), so a rotated parameter takes effect after systemctl restart app, which fetches the files again and recreates the containers.

Logs in CloudWatch. The awslogs driver ships each container’s stdout and stderr to the log group. Under FrankenPHP worker mode and in console commands, the default logger writes to stderr unless PHP’s error_log names a file (Logging), so the app, the worker and migrate reach CloudWatch without a logger of their own. The Docker daemon, not the container, sends the logs with the instance role’s credentials, so the role needs logs:CreateLogStream and logs:PutLogEvents, plus logs:CreateLogGroup for awslogs-create-group.

Recycling persistent workers#

Kinetis disposes request state at request end and never restarts a worker itself. A worker’s memory can still grow from outside Kinetis: an extension, a library’s own cache, or allocator fragmentation left by one large request. Recycling replaces such a worker between requests, before memory_limit fails a request with a fatal error.

  • RoadRunner. Soft limits under http.pool replace a worker after the request in flight: supervisor.max_worker_memory in megabytes, supervisor.ttl for its age, and max_jobs for its request count. Prefer max_worker_memory: it targets the symptom and fires only when memory actually grows. supervisor.exec_ttl is a hard limit on one request, which it interrupts, not a recycling limit. All four default to unlimited.

    .rr.yaml#
    http:
      pool:
        supervisor:
          max_worker_memory: 256
    
  • FrankenPHP. No setting recycles a worker. FrankenPhpAdapter serves until FrankenPHP stops the worker script, and FrankenPHP restarts a worker script that exits with an error, including one that passed memory_limit.

  • Lambda. One PHP process serves every invocation its execution environment receives. Lambda replaces environments on its own schedule, and no setting recycles one sooner. A process that exits with an error, including one that passed memory_limit, is reinitialized by Lambda.

  • PHP-FPM. Each request boots Kinetis fresh, so no Kinetis state outlives it.

  • queue:work. The worker has no job-count or memory limit. Its supervisor recycles it by sending SIGTERM, which stops it after the job in flight — see Queue’s Deploys and restarts.

Request bodies: one contract under every runtime#

An adapter hands the body on as raw bytes. RequestBodyMiddleware, which runs on every request, stages it, applies MAX_BODY_SIZE and the form limits below, and parses a form, so the same body is accepted or refused the same way under every runtime.

Important

enable_post_data_reading=0 — FrankenPHP and PHP-FPM. PHP otherwise reads and parses the body before Kinetis exists, silently truncating a form at max_input_vars or emptying it past post_max_size. SuperglobalsBridge refuses to serve without it. The setting is PHP_INI_PERDIR: set it in php.ini, a conf.d file, .htaccess or the FPM pool configuration, never in application code.

arg_separator.input=& — every runtime. & is PHP’s default and the only value the form parser accepts; any other value fails the first form parse with a server error naming the setting.

Set the edge limit with MAX_BODY_SIZE#

MAX_BODY_SIZE (default 2 MiB) is the byte ceiling Kinetis enforces. The server in front of PHP may read and bound the body first:

Runtime

Limit before PHP

Action

FrankenPHP

none set by Kinetis

MAX_BODY_SIZE stops the read once the body passes it

PHP-FPM behind nginx

client_max_body_size, default 1 MiB

Set it to at least MAX_BODY_SIZE

RoadRunner

http.max_request_size, default 1000 MB

Set it explicitly and match MAX_BODY_SIZE

AWS Lambda

6 MB invocation payload

Fixed by the platform

Every request in progress holds its body in memory — see Middleware’s “Request body limits” for choosing MAX_BODY_SIZE with memory_limit.

Form limits#

Limit

Default

What it counts

MAX_INPUT_VARS

512

pairs in a raw url-encoded body, and leaf values in the parsed form

MAX_FILE_PARTS

16

leaf entries in getUploadedFiles()

MAX_NESTING_DEPTH

8

array levels a name builds — a[b][c]=1 is 3

MAX_MULTIPART_PARTS

512

parts in a raw multipart envelope, unnamed ones included

MAX_PART_HEADERS

16

header lines on any one multipart part, repeats included

MAX_PART_HEADER_BYTES

8 KiB

bytes on one multipart header line

MAX_BODY_SIZE

2 MiB

bytes in the request body, whatever its content type

MAX_BODY_SIZE is configuration. The other six are Kinetis\Http\Form\FormLimits constants, counted from the raw body before anything parses it.

  • A body past any limit is refused whole with 413, naming the limit. A form is never handed on with the fields past the limit missing.

  • A runtime whose max_input_vars or max_input_nesting_level is set below these limits is 413 naming that setting, rather than a form PHP would have shortened.

  • A body that cannot be parsed is 400 with the fixed message The request body could not be parsed. Multipart bodies follow the byte-literal RFC 7578 subset browsers send; transfer encodings, encoded words, extended parameters and nested multipart parts are refused.

Both refusals happen before the handler runs. Every body is staged before the handler runs and What a multipart/form-data body may say give the staging mechanism, the exact multipart grammar and the logged failure categories.

Forwarded headers: trust only your edge#

A client can send X-Forwarded-Proto itself. By default Kinetis reads it from no one, and a request’s scheme is the one its listener serves. Behind a proxy or load balancer that terminates TLS, name that edge so absolute URLs, Secure cookies and OAuth redirects use https:

.env#
TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12
  • TRUSTED_PROXIES is a comma-separated list of addresses and CIDR ranges. An entry that is neither is refused at startup.

  • Only a request whose connecting peer matches the list may set the scheme, under FrankenPHP, PHP-FPM and RoadRunner. From any other peer the header is ignored.

  • A trusted proxy sending anything other than one http or https is answered with 400 before the handler.

  • The request’s client address stays the peer that connected. RateLimitMiddleware reads X-Forwarded-For under its own policy — see Middleware’s “Behind a reverse proxy or load balancer”.

  • Lambda takes no policy: its scheme is always https.

Forwarded headers describes how each adapter applies the policy.

Process and SAPI globals#

Application code reads the request from the PSR-7 ServerRequestInterface it is given and answers with the ResponseInterface it returns. The adapter owns the process and the SAPI on both sides of that exchange, so code that reaches them directly behaves differently under each runtime:

  • exit and die end the PHP process before the response is sent or the request scope is disposed. Under FrankenPHP and RoadRunner that is the worker, with every request in flight on its event loop; under Lambda it fails the invocation in flight.

  • Request superglobals are not the request under RoadRunner and Lambda, which never fill them. Under PHP-FPM and FrankenPHP the required enable_post_data_reading=0 leaves $_POST and $_FILES empty, and reading the scheme or client address from $_SERVER skips the TRUSTED_PROXIES policy above.

  • SAPI header, cookie, and session functions never reach the client under RoadRunner and Lambda, whose CLI SAPI discards them. Under PHP-FPM and FrankenPHP they bypass the response Kinetis emits.

Kinetis\Linting\NoProcessGlobalsRule is a PHPStan rule that flags each of these. It ships under the framework’s main autoload beside NoStaticPropertiesRule and NoBlockingIoRule, and kinetis/skeleton’s phpstan.neon registers all three; an existing project adds it to its own:

phpstan.neon#
rules:
    - Kinetis\Linting\NoProcessGlobalsRule

Identifier

Reported

Use instead

kinetis.exit

exit and die, with or without a status, and \exit()

return a response or throw from a handler; a console command returns its exit code

kinetis.superglobal

$_GET, $_POST, $_COOKIE, $_FILES, $_REQUEST, $_SESSION, $_SERVER, read or written

getQueryParams(), getParsedBody(), getCookieParams(), getUploadedFiles(), and getServerParams() or a request header on ServerRequestInterface; Kinetis\Session\Session from Sessions & CSRF; getenv() for the environment

kinetis.sapiCall

header(), header_remove(), http_response_code(), setcookie(), setrawcookie(), and every global session_*() function

the status and headers, Set-Cookie included, on the returned ResponseInterface; Kinetis\Session\Session

Function names resolve the way PHP resolves them, so an unqualified header() inside a namespace that declares its own header() is not reported. A method, property, or static call that shares a reported name, a variable named by an expression, $_ENV, $GLOBALS, getenv(), and the output functions (echo, flush(), ob_*()) are not reported.

Code that owns the process or the SAPI — a console entrypoint that sets its exit code, an adapter bridging a real SAPI — is exempted with PHPStan’s standard ignores, by identifier and path, with the reason beside it:

phpstan.neon#
parameters:
    ignoreErrors:
        # A console entrypoint; it hands its command's exit code to exit.
        -
            identifier: kinetis.exit
            path: bin/console

Choose an adapter explicitly#

A deployment that wants one adapter rather than detection passes a factory to HttpStartup::assemble() and serves what it returns. The factory receives the TrustedProxies policy the container settled on:

public/index.php#
use Kinetis\Http\TrustedProxies;
use Kinetis\Runtime\Adapters\FpmAdapter;
use Kinetis\Runtime\HttpStartup;

require dirname(__DIR__) . '/vendor/autoload.php';

HttpStartup::assemble(
    dirname(__DIR__),
    static fn (TrustedProxies $proxies): FpmAdapter => new FpmAdapter($proxies),
)->serve();

BrefLambdaAdapter takes the Runtime API endpoint instead:

$adapter = new Kinetis\BrefAdapter\BrefLambdaAdapter(
    (string) getenv('AWS_LAMBDA_RUNTIME_API'),
);

To target another environment, implement RuntimeAdapterInterface and hold it to the shared conformance suite — see Writing a runtime adapter.

See also#