PHP
Back to home
On this page
Note
You can now use the Platform.sh composable image (BETA) 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 a 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.
Grid and Dedicated Gen 3 | Dedicated Gen 2 |
---|---|
|
|
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
:
type: 'php:<VERSION_NUMBER>'
For example:
type: 'php:8.4'
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.
Grid and Dedicated Gen 3 | Dedicated Gen 2 |
---|---|
|
|
Usage example
Configure your app to use PHP on Platform.sh.
1. Specify the version
Choose a supported version and add it to your app configuration:
type: 'php:8.4'
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
totrue
, you might also want to add the following configuration:-
Set
scripts
tofalse
. This prevents PHP scripts from being executed from the specified location. -
Set
allow
tofalse
. By default, when PHP scripts aren’t executed, their source code is delivered. Settingallow
tofalse
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
:
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:
name: 'myapp'
type: 'php:8.4'
disk: 2048
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:
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:
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:
- Set an explicit
require
block:
dependencies:
php:
require:
"platformsh/client": "2.x-dev"
This is equivalent to composer require platformsh/client 2.x-dev
.
- Add the repository to use:
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 platformsh/client 2.x-dev
library from a custom repository,
use the following:
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
The following examples show how to use PHP to access various services. The individual service pages have more information on configuring each service.
<?php
declare(strict_types=1);
use Elasticsearch\ClientBuilder;
use Platformsh\ConfigReader\Config;
// Create a new config object to ease reading the Platform.sh environment variables.
// You can alternatively use getenv() yourself.
$config = new Config();
// Get the credentials to connect to the Elasticsearch service.
$credentials = $config->credentials('elasticsearch');
try {
// The Elasticsearch library lets you connect to multiple hosts.
// On Platform.sh Standard there is only a single host so just
// register that.
$hosts = [
[
'scheme' => $credentials['scheme'],
'host' => $credentials['host'],
'port' => $credentials['port'],
]
];
// Create an Elasticsearch client object.
$builder = ClientBuilder::create();
$builder->setHosts($hosts);
$client = $builder->build();
$index = 'my_index';
$type = 'People';
// Index a few document.
$params = [
'index' => $index,
'type' => $type,
];
$names = ['Ada Lovelace', 'Alonzo Church', 'Barbara Liskov'];
foreach ($names as $name) {
$params['body']['name'] = $name;
$client->index($params);
}
// Force just-added items to be indexed.
$client->indices()->refresh(array('index' => $index));
// Search for documents.
$result = $client->search([
'index' => $index,
'type' => $type,
'body' => [
'query' => [
'match' => [
'name' => 'Barbara Liskov',
],
],
],
]);
if (isset($result['hits']['hits'])) {
print <<<TABLE
<table>
<thead>
<tr><th>ID</th><th>Name</th></tr>
</thead>
<tbody>
TABLE;
foreach ($result['hits']['hits'] as $record) {
printf("<tr><td>%s</td><td>%s</td></tr>\n", $record['_id'], $record['_source']['name']);
}
print "</tbody>\n</table>\n";
}
// Delete documents.
$params = [
'index' => $index,
'type' => $type,
];
$ids = array_map(function($row) {
return $row['_id'];
}, $result['hits']['hits']);
foreach ($ids as $id) {
$params['id'] = $id;
$client->delete($params);
}
} catch (Exception $e) {
print $e->getMessage();
}
Configuration reader
While you can read the environment directly from your app, you might want to use thePHP configuration reader library. It decodes service credentials, the correct port, and other information for you.
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:
platform ssh "php --info"
To get specific default values, use grep.
For example, to get the value for opcache.memory_consumption
, run the following command:
platform 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:
platform 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:
platform ssh "cat LOADED_CONFIGURATION_FILE_PATH"
Customize PHP settings
For Dedicated Gen 2, see the configuration options.
You can customize PHP values for your app in two ways. The recommended method is to use variables.
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:
platform variable:create --level environment \
--prefix php --name memory_limit \
--value 256M --environment ENVIRONMENT_NAME \
--no-interaction
For more information, see how to use PHP-specific variables.
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, Platform.sh 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:
variables:
php:
disable_functions: "pcntl_exec,pcntl_fork"
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 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:
- Add your script in a PHP file.
- Specify an alternative
start
command by adapting the following:
web:
commands:
start: /usr/bin/start-php-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:
-
Enable the FFI extension:
runtime:
extensions:
- ffi
-
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:
variables:
php:
opcache.enable_cli: true
-
Run your script with the following command:
php CLI_SCRIPT
See complete working examples for C and Rust.
Project templates
The following list shows templates available for PHP apps.
A template is a starting point for building your project. It should help you get a project ready for production.
Modify your PHP runtime when using a composable image
Note
This section is only relevant when using the Platform.sh composable image (BETA).
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.
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. |
Here is an example configuration:
name: 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"
Note
You can also set your app’s runtime timezone.