Skip to content

Classic mode ​

Classic mode executes an ordinary PHP entry script. This can be the same public/index.php file that php-fpm runs. Rapira starts a new PHP request for each HTTP request. It fills the superglobals and executes the script. Script output becomes the response. Most applications can move from php-fpm to Classic mode with no code changes.

New state for each request ​

Each request has a complete PHP request cycle. The cycle includes request initialization, entry script execution, and request shutdown. PHP removes request state before the next request. This state includes globals, static properties, the dependency injection container, and the ORM identity map.

Objects and request data cannot affect a later request. Some state stays in the worker process: persistent connections, extension state, and the working directory. Applications that do not support persistent processes can run in Classic mode.

The application initializes its autoloader, configuration, container, and routes for each request. See execution modes for more information.

Each worker uses the entry script directory as its working directory. The worker resolves the symbolic links in the entry script path and sets this directory when it starts and at each reload. A chdir() call in a request stays in effect for later requests of the same worker, until the next reload. If a request changes the working directory, restore it before the request ends.

Rapira does not provide the php-fpm fastcgi_finish_request() function. Use rapira_finish_request() to send the response before the script ends. See HTTP for more information.

Mode selection ​

Select Classic mode with mode = "classic" in the [http.pool] table of rapira.toml. Only the HTTP pool supports Classic mode. See configuration for the complete key list.

A classic entry script is ordinary PHP:

php
<?php
// index.php
header('Content-Type: text/plain');
echo "Hello, " . ($_GET['name'] ?? 'anonymous') . "!\n";
echo "Method: {$_SERVER['REQUEST_METHOD']}\n";

The rapira.toml for this script is:

toml
[http]
listen = "127.0.0.1:8000"

[http.pool]
entrypoint = "public/index.php"
mode = "classic"

Start Rapira with rapira serve rapira.toml. A relative http.pool.entrypoint uses the configuration file directory as its base. See the CLI reference for the command.

Entry script ​

Rapira does not map URLs to PHP scripts. Each request runs the configured entry script. $_SERVER['REQUEST_URI'] contains the URL for application routing.

The static file middleware can return files for GET and HEAD requests. The entry script processes the requests that the middleware does not answer. A CDN or reverse proxy can also serve static assets. See deployment for a reverse proxy example.

SCRIPT_FILENAME contains the absolute entry script path. SCRIPT_NAME contains its file name with a leading slash, such as /index.php. DOCUMENT_ROOT contains the entry script directory.

Uploads ​

PHP parses multipart/form-data bodies and fills $_FILES, as under php-fpm. The upload_max_filesize and post_max_size settings in php.ini apply.

Rapira applies http.max_body_size_mb to the complete request body before PHP runs. The default is 8 MiB. Rapira returns 413 for a larger body. If php.ini permits larger uploads, increase http.max_body_size_mb to match post_max_size. See request bodies for more information.

The [http.uploads] table applies only to Dispatcher mode. Rapira does not start when a Classic configuration contains this table. See configuration for more information.

OPcache ​

Each PHP request removes application state. OPcache keeps compiled bytecode across requests. The master process starts PHP before it creates workers, so all workers use the same OPcache shared memory segment. When you enable OPcache, later requests use the cached bytecode, and PHP does not compile unchanged scripts again. See deployment for the OPcache setup.

Each worker handles one request at a time. http.pool.processes sets the worker count, which is also the maximum number of concurrent requests. See the process model for more information.

Large responses ​

Rapira keeps the complete response of a Classic script in the memory of the worker. It sends the response when the script ends, or when the script calls rapira_finish_request(). The PHP flush() function does not send data to the client.

The worker needs memory for the complete response. While the body grows, the worker can use up to approximately three times the response size. The worker keeps the response in memory until the client receives it, and it can start the next request during this time. Thus, a 600 MB download uses more than 600 MB of memory in one worker. When the buffered body exceeds 1 GiB, Rapira stops the request, and the client receives an incomplete response.

For large files and long streams, use one of these alternatives:

  • Dispatcher mode. Exchange::writeBody() with $eos = false sends each part when the script writes it. Exchange::sendFile() sends a file from disk, and the worker does not keep the file in memory. See Send a file.
  • A reverse proxy that sends the file. The script sets a response field and sends no body, for example the nginx X-Accel-Redirect field. Rapira sends this field to the proxy without changes. The proxy reads the file and sends it to the client.

See Response transmission for more information.

Choosing between Classic and Worker ​

Use Classic mode when the application cannot safely keep state between requests. For example, some applications and vendor libraries store request data in static properties. Classic mode also decreases application changes when you move from php-fpm. Use Worker mode when the application supports a persistent process. Worker mode removes application initialization from each request. See execution modes for all three modes.

Rapira\handle_request() throws Rapira\Exception\NotInWorkerModeError in Classic mode. A Classic script ends with its request and cannot run a request loop.