OpenSwoole HTTP Server Configuration

Latest version: pecl install openswoole-22.1.2 | composer require openswoole/core:22.1.5

Because the OpenSwoole HTTP Server is an extension of the standard OpenSwoole TCP/UDP Server, the built-in HTTP server is an implementation of the HTTP protocol. The following configuration options are only available when running a OpenSwoole HTTP server, they are an extension to the normal Server Configuration options, they can be set the same way using $server->set. You can use all the settings from a OpenSwoole\Server in a OpenSwoole\HTTP\Server, refer to the main Server Configuration.

Setting Configuration Options

We set server configuration options before we start the server, take the following example to see how options are set, each option here can be set the same way in the settings array:

<?php

$server = new Server('127.0.0.1', 9501, OpenSwoole\Server::POOL_MODE);

$server->set([
    'worker_num' => 2,
    'task_worker_num' => 2,
    'upload_tmp_dir' => '/data/uploaded_files/',
    // ...
]);

$server->on('Request', function(OpenSwoole\Http\Request $request, OpenSwoole\Http\Response $response)
{
    // On Request event callback...
});

$server->start();

upload_tmp_dir

Set the temporary directory path for uploaded files to the server.

<?php
$server->set([
    'upload_tmp_dir' => '/data/uploaded_files/',
]);

The max length of upload_tmp_dir is 220 bytes.

http_parse_post

Enable the analysis of POST data. If you set this configuration to false, OpenSwoole will not analyse POST request data. If this configuration is set to true, OpenSwoole will analyse the POST data where the Content-Type is x-www-form-urlencoded. This is set to true by default.

<?php
$server->set([
    'http_parse_post' => true,
]);

Enable parsing of HTTP cookies from the request. If set to true, then this will let the server parse and get cookies from the request. If set to false, then OpenSwoole won't analyse HTTP cookies and they will be left in their raw format. This is set to true by default.

This options relates to the HTTP server OpenSwoole\Http\Request object where this information will be made available if true.

<?php
$server->set([
    'http_parse_cookie' => true,
]);

http_parse_files

Enable parsing of uploaded files from the request. If set to true, then this will let the server parse and get uploaded files from the request. If set to false, then OpenSwoole won't analyse any uploaded files alone. This is set to true by default.

This options relates to the HTTP server OpenSwoole\Http\Request object where this information will be made available if true.

<?php
$server->set([
    'http_parse_files' => true,
]);

http_compression

Enable or disable HTTP compression, this is the alternative to using gzip as it does not support if the browser/client supports Accept-Encoding, if the client does not support gzip compression, it will lead to the client not being able to extract the request. The new http_compression configuration item is based on the client Accept-Encoding header, it will automatically select whether to compress (if the client supports it), and automatically selects the best compression algorithm. This is set to true by default.

HTTP-Chunk does not support any compression. use the write() method instead to chunk data to the client.

Current compression algorithm support: gzip, br and deflate, by using the Accept-Encoding header the client will select the best compression algorithm.

If you are wanting to use gzip or deflate, you must install zlib:

sudo apt-get install libz-dev

And if you are using br compression, it requires the brotli library. It is best to check on how to install brotli for your distro but for Ubuntu, something like this guide may work for you.

Since v4.1.0

<?php
$server->set([
    'http_compression' => true,
]);

http_compression_level

Set the compression level when http_compression is enabled. The default is 1.

You can select a range from 1 - 9. The higher the number the higher the compression but more CPU usage.

<?php
$server->set([
    'http_compression_level' => 1,
]);

document_root

Set the web root path for static files. This configuration needs to be set with enable_static_handler.

If the document_root is set and the value of enable_static_handler is true, Swoole will judge if the request file exists within the directory given. If the file requested exists, Swoole will send the file to client directly and won't trigger the event callback function of Request.

You must use an absolute directory path.

<?php
$server->set([
    'document_root' => '/var/www/openswoole.com',
    'enable_static_handler' => true,
]);

When using a document root, it is best practice to isolate dynamic PHP files from your static files. You should separate your document root away from your PHP app files, keeping static files together with nothing else.

enable_static_handler

Enable or disable static file handling via the Swoole HTTP server. This option is used in conjunction with document_root and they must be set together.

This option can be used as a switch to turn static file handling on or off.

http_autoindex

Enable or disable HTTP auto index. This is set to false by default.

http_index_files

With http_autoindex enabled, you can then set the list of files that need to be indexed:

<?php
$server->set([
    'document_root' => '/data/www/openswoole.com',
    'enable_static_handler' => true,
    'http_autoindex' => true,
    'http_index_files' => ['index.html', 'index.txt'],
]);

static_handler_locations

Set the directory path(s) locations of where Swoole will look for existing static files to serve back to the client.

This option is an array and is off by default.

<?php
$server->set([
    'static_handler_locations' => ['/static', '/app/images'],
]);

Each location must start with a /, supports multi-level paths like /app/images and if the static files does not exist, a 404 error will be returned.

Since v4.4.0

open_http2_protocol

Enable or disable the use of the HTTP2 protocol. By default this is false.

You must make sure to install/compile Swoole with the --enable-http2 option for this to work.

compression_min_length

Set the minimum number of bytes to enable compression. Compression will be enabled only when the option value is exceeded.

<?php
$server->set([
    'compression_min_length' => 128,
]);

Since v4.6.3

Last updated on September 20, 2022