PHP

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.

• 8.3
• 8.2
• 8.1

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:

applications:
    # The app's name, which must be unique within the project.
    <APP_NAME>:
        type: 'php:<VERSION_NUMBER>'

For example:

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'php:8.3'

Deprecated versions

The following versions are deprecated. They’re available, but they aren’t receiving security updates from upstream and aren’t guaranteed to work. They’ll be removed in the future, so migrate to one of the supported versions.

• 8.0
• 7.4
• 7.3
• 7.2
• 7.1
• 7.0
• 5.6
• 5.5
• 5.4

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:

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'php:8.3'

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.

  Note

  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:

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'php:8.3'
        web:
            locations:
                '/':
                    root: 'public'
                    passthru: '/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:

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'php:8.3'
        web:
            locations:
                '/':
                    root: 'public'
                    passthru: '/app.php'

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:

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'php:8.3'
        ...
        dependencies:
            php:
                composer/composer: '^2'

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:

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'php:8.3'
        ...
        build:
            flavor: none

        hooks:
            build: |
                set -e
                composer install --no-interaction --no-dev                

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:

1. Set an explicit require block:

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'php:8.3'
        ...
        dependencies:
            php:
                require:
                    "platformsh/client": "2.x-dev"

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

2. Add the repository to use:

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'php:8.3'
        ...
        dependencies:
            php:
                require:
                    "platformsh/client": "2.x-dev"
                repositories:
                    - type: vcs
                      url: "git@github.com:platformsh/platformsh-client-php.git"

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:

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'php:8.3'
        ...
        dependencies:
            php:
                composer/composer: '^2'
                require:
                    "platformsh/client": "2.x-dev"
                repositories:
                    - type: vcs
                      url: "git@github.com:platformsh/platformsh-client-php.git"

Connect to services

You can access service credentials to connect to managed services from environment variables present in the application container. Consult each of the individual service documentation to see how to retrieve and surface credentials into your application.

• ClickHouse

• Elasticsearch

• Gotenberg

• Headless Chrome

• InfluxDB

• Kafka

• MariaDB/MySQL

• Memcached

• MongoDB

• Network Storage

• OpenSearch

• PostgreSQL

• RabbitMQ

• Redis

• Solr

• Varnish

• Vault KMS

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:

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:

1. 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)

2. Display the configuration file by adapting the following command with the output from step 1:

   upsun ssh "cat 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.

upsun variable:create --level environment \
    --prefix php --name memory_limit \
    --value 256M --environment ENVIRONMENT_NAME \
    --no-interaction

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:

applications:
    # The app's name, which must be unique within the project.
    app:
        type: 'php:8.3'
        variables:
            php:
                disable_functions: "pcntl_exec,pcntl_fork"

Common functions to disable include:

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 PATH_TO_SCRIPT, where PATH_TO_SCRIPT 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 PATH_TO_SCRIPT, where PATH_TO_SCRIPT 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:

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

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

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

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

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

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:

1. Enable and configure OPcache preloading.

2. Enable the FFI extension:

applications:
    app:
        type: 'php:8.3'
        runtime:
            extensions:
                - ffi

3. 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.

4. If you are running FFIs from the command line, enable the preloader by adding the following configuration:

applications:
    app:
        type: 'php:8.3'
        variables:
            php:
                opcache.enable_cli: true

5. Run your script with the following command:

   php CLI_SCRIPT

Frameworks

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

• Laravel
• Symfony

Modify your PHP runtime when using the composable image

The following table presents the possible modifications you can make to your PHP primary runtime using the stack key and composable image. Each modification should be listed below the stack chosen (i.e. extensions are enabled under .applications.frontend.stack[0]["php@8.3"].extensions for PHP 8.3). See the example below for more details.

Here is an example configuration:

applications:

  frontend:

    stack:
      - "php@8.3":
          extensions:
            - apcu # A PHP extension made available to the PHP runtime
            - sodium
            - xsl
            - pdo_sqlite

          xdebug:
            idekey: YOUR_KEY

          disabled_extensions:
            - gd

          request_terminate_timeout: 200

          sizing_hints:
            request_memory: 45
            reserved_memory: 70

      - "php83Extensions.apcu" # A PHP extension made available to all runtimes.
      - "python@3.12"
      - "python312Packages.yq"