Runtime Adapters#
One public/index.php serves a Kinetis application under FrankenPHP,
PHP-FPM, RoadRunner and AWS Lambda:
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 |
core |
Development with edit-and-reload, or an existing FPM platform |
RoadRunner |
Persistent PHP worker processes behind RoadRunner’s Go server |
|
A persistent worker on a RoadRunner platform |
AWS Lambda |
A warm execution environment serves one invocation at a time |
|
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=developmentpicks 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=autoselects 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 forconcurrently().Streaming. FrankenPHP and PHP-FPM stream a
StreamedResponse. RoadRunner answers one with501, 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:
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:
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:
{
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
numwell 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
numaround 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:
{
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:
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"]
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:
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: truehands 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
StreamableResponseInterfaceis answered with501, 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:
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"]
#!/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=autoselects a blocking PDO connection. Database’s “Driver selection” covers when to selectDB_DRIVER=nativeon 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_SIZErefuses a larger body after delivery.The scheme is always
https. An HTTP API and a Function URL are TLS-only; an event whosex-forwarded-protoclaimshttpis refused.TRUSTED_PROXIESdoes 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-Cookiebecomes its own cookie entry.
What Lambda does not support:
Response streaming. A
StreamableResponseInterfacefails 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.
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:
#!/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
[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.poolreplace a worker after the request in flight:supervisor.max_worker_memoryin megabytes,supervisor.ttlfor its age, andmax_jobsfor its request count. Prefermax_worker_memory: it targets the symptom and fires only when memory actually grows.supervisor.exec_ttlis 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.
FrankenPhpAdapterserves until FrankenPHP stops the worker script, and FrankenPHP restarts a worker script that exits with an error, including one that passedmemory_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 sendingSIGTERM, 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 |
|
PHP-FPM behind nginx |
|
Set it to at least |
RoadRunner |
|
Set it explicitly and match |
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 |
|---|---|---|
|
512 |
pairs in a raw url-encoded body, and leaf values in the parsed form |
|
16 |
leaf entries in |
|
8 |
array levels a name builds — |
|
512 |
parts in a raw multipart envelope, unnamed ones included |
|
16 |
header lines on any one multipart part, repeats included |
|
8 KiB |
bytes on one multipart header line |
|
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_varsormax_input_nesting_levelis set below these limits is413naming that setting, rather than a form PHP would have shortened.A body that cannot be parsed is
400with the fixed messageThe 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:
TRUSTED_PROXIES=10.0.0.0/8,172.16.0.0/12
TRUSTED_PROXIESis 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
httporhttpsis answered with400before the handler.The request’s client address stays the peer that connected.
RateLimitMiddlewarereadsX-Forwarded-Forunder 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:
exitanddieend 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=0leaves$_POSTand$_FILESempty, and reading the scheme or client address from$_SERVERskips theTRUSTED_PROXIESpolicy 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:
rules:
- Kinetis\Linting\NoProcessGlobalsRule
Identifier |
Reported |
Use instead |
|---|---|---|
|
|
return a response or throw from a handler; a console command returns its exit code |
|
|
|
|
|
the status and headers, |
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:
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:
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#
Core Concepts — why application code never needs to know which adapter is running it.
Concurrency — what
concurrently()overlaps under each runtime.Caching & AOT Compilation — the production build step, and why it matters most under PHP-FPM.
Performance tuning — the worker × connection budget and tuning by workload shape.
Appendix: Runtime Reference — request-body staging, forwarded-header handling, Lambda event mapping and the custom adapter contract.
Appendix: System Layout — the framework’s runtime namespace.