PHP

You can now use the Upsun composable image to install runtimes and tools in your application container. To find out more about this feature, see the dedicated documentation page.
Also, see how you can modify your PHP runtime when using the composable image.

Supported versions

You can select the major and minor version. Patch versions are applied periodically for bug fixes and the like. When you deploy your app, you always get the latest available patches. Note that from PHP versions 7.1 to 8.1, the images support the Zend Thread Safe (ZTS) version of PHP.

Specify the language

To use PHP, specify php as your app’s type: For example:

Usage example

Configure your app to use PHP on Upsun.

1. Specify the version

Choose a supported version and add it to your app configuration:

2. Serve your app

To serve your app, define what (and how) content should be served by setting the locations parameter. Usually, it contains the two following (optional) keys:

root for the document root, the directory to which all requests for existing .php and static files (such as .css, .jpg) are sent.
passthru to define a front controller to handle nonexistent files. The value is a file path relative to the app root.
For enhanced security, when setting passthru to true, you might also want to add the following configuration:
1. Set scripts to false. This prevents PHP scripts from being executed from the specified location.
2. Set allow to false. By default, when PHP scripts aren’t executed, their source code is delivered. Setting allow to false allows you to keep the source code of your PHP scripts confidential.

Adjust the locations block to fit your needs. In the following example, all requests made to your site’s root (/) are sent to the public directory and nonexistent files are handled by app.php: See how to create a basic PHP app with a front controller. To have more control, you can define rules to specify which files you want to allow from which location.

Complete example

A complete basic app configuration looks like the following:

Dependencies

Up to PHP version 8.1, it’s assumed that you’re using Composer 1.x to manage dependencies. If you have a composer.json file in your code, the default build flavor is run:

composer --no-ansi --no-interaction install --no-progress --prefer-dist --optimize-autoloader

To use Composer 2.x on your project, either use PHP 8.2+ or, in your app configuration, add the following dependency: Adding a dependency to the dependencies block makes it available globally. So you can then use included dependencies as commands within your app container. You can add multiple global dependencies to the dependencies block, such as Node.js. If you want to have more control over Composer or if you don’t want to use Composer at all, adapt the build flavor. You can also use a private, authenticated third-party Composer repository.

Change the build flavor

If you need more control over the dependency management, you can either use your custom build flavor or interact with Composer itself through its environment variables. You can remove the default build flavor and run your own commands for complete control over your build. Set the build flavor to none and add the commands you need to your build hook, as in the following example: That installs production dependencies with Composer but not development dependencies. The same can be achieved by using the default build flavor and adding the COMPOSER_NO_DEV variable. See more on build flavors.

Alternative repositories

In addition to the standard dependencies format, you can specify alternative repositories for Composer to use as global dependencies. So you can install a forked version of a global dependency from a custom repository. To install from an alternative repository:

Set an explicit require block:

This is equivalent to composer require platform/client 2.x-dev.

Add the repository to use:

That installs platformsh/client from the specified repository URL as a global dependency. For example, to install Composer 2 and the platform/client 2.x-dev library from a custom repository, use the following:

Configure security blocking

When building a PHP app, Upsun runs composer install, which runs the latest available Composer version. By default, PHP builds fail if a dependency in a project has a known vulnerability. A PHP build might also fail if a dependency is abandoned. The best practice is to upgrade the dependencies to reduce security risks and to catch issues sooner. However, you can configure the level of security blocking by defining the following keys in the .dependencies.php.config section of your .upsun/config.yaml file.

Key	Description
`audit.block-insecure`	Default is `true`. Important: Upsun recommends keeping this default setting and upgrading affected dependencies to reduce security risks.
`audit.block-abandoned`	Default is `false`; set to `true` for even stricter security. Ignored if `audit.block-insecure` is `false`.
`audit.ignore`	Array of specific advisories to ignore; see example below.
`audit.ignore-severity`	Ignore vulnerabilities based on their severity rating (`low`/`medium`/`high`). See the example below. For each rating, include an `apply` key with one of these values: `all` to ignore everything for this rating `block` to ignore this severity level for blocking builds (but still flag findings in audit reports) `audit` to ignore this severity level in audit reports (but still block builds)

Examples: Related information:

Troubleshooting PHP builds that now fail

Additional Composer schema properties

In addition to alternate repositories, other Composer schema properties can be added to the global dependencies. For example, one of your dependencies may be a plugin where you need to explicitly whitelist it as an allowed-plugin. To add additional composer schema properties:

Set an explicit require block:

Add each additional property as a block at the same indentation as the require block:

Connect to services

PHP settings

You can configure your PHP-FPM runtime configuration by specifying the runtime in your app configuration. In addition to changes in runtime, you can also change the PHP settings. Some commonly used settings are:

Name	Default	Description
`max_execution_time`	`300`	The maximum execution time, in seconds, for your PHP scripts and apps. A value of `0` means there are no time limits.
`max_file_uploads`	`20`	The maximum number of files that can be uploaded in each request.
`max_input_time`	`60`	The maximum time in seconds that your script is allowed to receive input (such as for file uploads). A value of `-1` means there are no time limits.
`max_input_vars`	`1000`	The maximum number of input variables that are accepted in each request.
`memory_limit`	`128M`	The memory limit, in megabytes, for PHP. Ensure that the PHP memory limit is set to a lower value than your environment’s memory.
`post_max_size`	`64M`	The maximum size, in megabytes, per uploaded file. To upload larger files, increase the value.
`zend.assertions`	`-1`	Assertions are optimized and have no impact at runtime. Set assertions to `1` for your local development system. See more on assertions.
`opcache.memory_consumption`	`64`	The number of megabytes available for the OPcache. For large apps with many files, increase this value.
`opcache.validate_timestamps`	`On`	If your app doesn’t generate compiled PHP, you can disable this setting.

Retrieve the default values

To retrieve the default PHP values, run the following CLI command:

upsun ssh "php --info"

To get specific default values, use grep. For example, to get the value for opcache.memory_consumption, run the following command:

upsun ssh "php --info" | grep opcache.memory_consumption

Retrieve the settings

To see the settings used on your environment:

Find the PHP configuration files with the following CLI command:

upsun ssh "php --ini"

The output is something like the following:

Configuration File (php.ini) Path: /etc/php/8.0-zts/cli
Loaded Configuration File:         /etc/php/8.0-zts/cli/php.ini
Scan for additional .ini files in: /etc/php/8.0-zts/cli/conf.d
Additional .ini files parsed:      (none)

Display the configuration file by adapting the following command with the output from step 1:
```
upsun ssh "cat <VariableBlock name="LOADED_CONFIGURATION_FILE_PATH" />"
```

Customize PHP settings

You can customize PHP values for your app in two ways. The recommended method is to use variables.

Using variables
Using `php.ini`

Set variables to override PHP settings for a given environment using the CLI.For example, to set the PHP memory limit to 256 MB on a specific environment, run the following CLI command:

upsun variable:create --level environment \
    --prefix php --name memory_limit \
    --value 256M --environment <VariableBlock name="ENVIRONMENT_NAME" /> \
    --no-interaction

For more information, see how to use PHP-specific variables.

You can provide a custom php.ini file at the app root. Using this method isn’t recommended since it offers less flexibility and is more error-prone. Consider using variables instead.For example, to change the PHP memory limit, use the following configuration:

php.ini

memory_limit = 256M

If you’re using PHP-CLI, you need to take into account the default settings of PHP-CLI when you customize your PHP settings. The default settings of PHP-CLI can’t be overwritten and are the following:

max_execution_time=0
max_input_time=-1
memory_limit=-1

Disable functions for security

A common recommendation for securing PHP installations is disabling built-in functions frequently used in remote attacks. By default, Upsun doesn’t disable any functions. If you’re sure a function isn’t needed in your app, you can disable it. For example, to disable pcntl_exec and pcntl_fork, add the following to your app configuration: Common functions to disable include:

Name	Description
`create_function`	This function has been replaced by anonymous functions and shouldn’t be used anymore.
`exec`, `passthru`, `shell_exec`, `system`, `proc_open`, `popen`	These functions allow a PHP script to run a bash shell command. Rarely used by web apps except for build scripts that might need them.
`pcntl_*`	The `pcntl_*` functions are responsible for process management. Most of them cause a fatal error if used within a web request. Cron tasks or workers may need them. Most are usually safe to disable.
`curl_exec`, `curl_multi_exec`	These functions allow a PHP script to make arbitrary HTTP requests. If you’re using HTTP libraries such as Guzzle, don’t disable them.
`show_source`	This function shows a syntax highlighted version of a named PHP source file. Rarely useful outside of development.

Execution mode

PHP has two execution modes you can choose from:

The command line interface mode (PHP-CLI) is the mode used for command line scripts and standalone apps. This is the mode used when you’re logged into your container via SSH, for crons, and usually also for alternate start commands. To use PHP-CLI, run your script with php <VariableBlock name="PATH_TO_SCRIPT" />, where is a file path relative to the app root.
The Common Gateway Interface mode (PHP-CGI) is the mode used for web apps and web requests. This is the default mode when the start command isn’t explicitly set. To use PHP-CGI, run your script with a symlink: /usr/bin/start-php-app <VariableBlock name="PATH_TO_SCRIPT" />, where is a file path relative to the app root. With PHP-CGI, PHP is run using the FastCGI Process Manager (PHP-FPM).

Alternate start commands

To specify an alternative process to run your code, set a start command. For more information about the start command, see the web commands reference. By default, start commands use PHP-CLI. Find out how and when to use each execution mode. Note that the start command must run in the foreground and is executed before the deploy hook. That means that PHP-FPM can’t run simultaneously with another persistent process such as ReactPHP or Amp. If you need multiple processes, they have to run in separate containers. See some generic examples on how to use alternate start commands:

Run a custom script
Run a custom web server
Run specific tasks

Add your script in a PHP file.
Specify an alternative start command by adapting the following:

.upsun/config.yaml

applications:
  # The name of the app container. Must be unique within a project.
  myapp:
    # The location of the application's code.
    web:
      commands:
        start: /usr/bin/start-php-app

Add your web server’s code in a PHP file.
Specify an alternative start command by adapting the following:

.upsun/config.yaml

applications:
  # The name of the app container. Must be unique within a project.
  myapp:
    # The location of the application's code.
    web:
      commands:
        start: /usr/bin/start-php-app

Configure the container to listen on a TCP socket:

.upsun/config.yaml

applications:
  # The name of the app container. Must be unique within a project.
  myapp:
    # The location of the application's code.
    web:
      upstream:
        socket_family: tcp
        protocol: http

When you listen on a TCP socket, the $PORT environment variable is automatically set. See more options on how to configure where requests are sent. You might have to configure your app to connect via the $PORT TCP socket, especially when using web servers such as Swoole or Roadrunner.

Optional: Override redirects to let the custom web server handle them:

.upsun/config.yaml

applications:
  # The name of the app container. Must be unique within a project.
  myapp:
    # The location of the application's code.
    locations:
      "/":
        passthru: true
        scripts: false
        allow: false

To execute runtime-specific tasks (such as clearing cache) before your app starts, follow these steps:

Create a separate shell script that includes all the commands to be run.
Specify an alternative start command by adapting the following:

is the bash script created in step 1. is a file path relative to the app root.

Foreign function interfaces

PHP 7.4 introduced support for foreign function interfaces (FFIs). FFIs allow your PHP program to call routines or use services written in C or Rust. Note: FFIs are only intended for advanced use cases. Use with caution. If you are using C code, you need .so library files. Either place these files directly in your repository or compile them in a makefile using gcc in your build hook. Note: The .so library files shouldn’t be located in a publicly accessible directory. If you are compiling Rust code, use the build hook to install Rust. To leverage FFIs, follow these steps:

Enable and configure OPcache preloading.
Enable the FFI extension:

Make sure that your preload script calls the FFI::load() function. Using this function in preload is considerably faster than loading the linked library on each request or script run.
If you are running FFIs from the command line, enable the preloader by adding the following configuration:

Run your script with the following command:
```
php <VariableBlock name="CLI_SCRIPT" />
```

Frameworks

All major PHP web frameworks can be deployed on Upsun. See dedicated guides for deploying and working with them:

Modify your PHP runtime when using the composable image

This section is only relevant when using the Upsun composable image.

The following table presents the possible modifications you can make to your PHP primary runtime using the stack.runtimes key in a composable image. For example, extensions are enabled under .applications.frontend.stack.runtimes[0]["php@<MetaVersion language='php:latest'/>"].extensions for PHP ). See the example below for more details.

The PHP-FPM service starts automatically only when PHP is the primary runtime.

Name	Type	Description
`extensions`	List of `string`s OR extensions definitions	PHP extensions to enable.
`disabled_extensions`	List of `string`s	PHP extensions to disable.
`request_terminate_timeout`	`integer`	The timeout (in seconds) for serving a single request after which the PHP-FPM worker process is killed.
`sizing_hints`	A sizing hints definition	The assumptions for setting the number of workers in your PHP-FPM runtime.
`xdebug`	An Xdebug definition	The setting to turn on Xdebug.

PHP-FPM service sizing hints

The following table shows the properties that can be set in sizing_hints:

Name	Type	Default	Minimum	Description
`request_memory`	`integer`	45	10	The average memory consumed per request in MB.
`reserved_memory`	`integer`	70	70	The amount of memory reserved in MB.

See more about PHP-FPM workers and sizing.

Example PHP configuration

Here is an example configuration:

You can also set your app’s runtime timezone.

Get Started

Core Concepts

Configure Apps & Services

Build, Deploy & Run

Manage Projects

Manage Environments

Manage Resources

Observability & Metrics

Integrations

Troubleshooting

Resources

Supported versions

Specify the language

Usage example

1. Specify the version

2. Serve your app

Complete example

Dependencies

Change the build flavor

Alternative repositories

Configure security blocking

Additional Composer schema properties

Connect to services

PHP settings

Retrieve the default values

Retrieve the settings

Customize PHP settings

Disable functions for security

Execution mode

Alternate start commands

Foreign function interfaces

Frameworks

Modify your PHP runtime when using the composable image

PHP-FPM service sizing hints

Example PHP configuration

Get Started

Core Concepts

Configure Apps & Services

Build, Deploy & Run

Manage Projects

Manage Environments

Manage Resources

Observability & Metrics

Integrations

Troubleshooting

Resources

​Supported versions

​Specify the language

​Usage example

​1. Specify the version

​2. Serve your app

​Complete example

​Dependencies

​Change the build flavor

​Alternative repositories

​Configure security blocking

​Additional Composer schema properties

​Connect to services

​PHP settings

​Retrieve the default values

​Retrieve the settings

​Customize PHP settings

​Disable functions for security

​Execution mode

​Alternate start commands

​Foreign function interfaces

​Frameworks

​Modify your PHP runtime when using the composable image

​PHP-FPM service sizing hints

​Example PHP configuration

Supported versions

Specify the language

Usage example

1. Specify the version

2. Serve your app

Complete example

Dependencies

Change the build flavor

Alternative repositories

Configure security blocking

Additional Composer schema properties

Connect to services

PHP settings

Retrieve the default values

Retrieve the settings

Customize PHP settings

Disable functions for security

Execution mode

Alternate start commands

Foreign function interfaces

Frameworks

Modify your PHP runtime when using the composable image

PHP-FPM service sizing hints

Example PHP configuration