Resources for Developers

PHP on Scalingo

Detection

Your application will be detected as a PHP application if:

  • There is a composer.lock file at the root of your project
  • index.php is present in the root directory (legacy app)

Stack

A stack based on Nginx and PHP-FPM will be installed.

PHP Versions

Compatibility

The following PHP versions are compatible with the platform:

  • 5.6 (up to 5.6.38)
  • 7.0 (up to 7.0.32)
  • 7.1 (up to 7.1.23)
  • 7.2 (up to 7.2.11)
  • 7.3 (up to 7.3.0)

Select a version

By default, the latest stable version of PHP will be installed, if you need to install a precise version it should be mentioned in your composer.json file.

Example to get the PHP version 5.6.38 installed:

{
  "config": {
    "platform": {
      "php": "5.6.38"
    }
  }
}

Composer

Composer is the official package manager for PHP. The official website is https://getcomposer.org/. It aims at handling the dependency management of your application: installing dependencies and freezing their versions.

If composer is used in a project, the deployment system will detect it and use it to install the dependencies of the project.

composer.json

This file defines the different dependencies used by your application. It is also used to configure custom deployment settings for the project (see below).

composer.lock

Once the third-party libraries have been defined, their versions need to be frozen in order to ensure a precise version of the application will always deploy a compatible set of Composer packages. These versions will be written in a compose.lock file. This file is required as it is read during the deployment on the platform.

To generate compose.lock you need to run:

$ composer install

When you need to upgrade a library, for instance slim:

$ composer update slim/slim

After each command, the composer.lock file will be updated automatically, do not forget to commit the modifications of the file.

Composer during the deployment

It is considered that when an application is deployed on Scalingo, it is run in “production” mode. As a result, composer install is run with the flag --no-dev.

If, in order to debug an application, development dependencies should be installed, please set the following environment variable:

  • COMPOSER_DEV=true

Native PHP extensions

Applications might require native PHP extensions, these extensions are usually written in C and need to be compiled as shared libraries (.so files) and be used by PHP.

Some of them are bundled by default with the deployed version of PHP, the others are installed dynamically if specified in the project composer.json.

Native extension dependency

If an application requires a native PHP extension, it should be added in the require block of its composer.json:

{
  "require": {
    "ext-mongodb": "*",
    "ext-imagick": "*",
    ...
  }
}

These dependency instructions are parsed by the deployment system which will install the require files.

List of pre-installed extensions

These extensions are available by default with the installed version of PHP:

List of available extensions

These extensions will be installed dynamically if required in the composer.json file.

  • APC User Cache: apcu
  • MongoDB Driver: mongodb
  • MongoDB Legacy Driver: mongo (obsolete, only PHP 5.6)
  • Redis Driver: redis
  • Image manipulation with ImageMagick: imagick
  • Memcached driver: memcached
  • Libevent bindings: libevent
  • GMP Multiple Precisions math functions: gmp
  • FTP Client: ftp
  • Tidy: tidy
  • Extension’s missing: contact us, the support for it will be added quickly

Officially supported frameworks

Scalingo supports out-of-the-box many well-known frameworks. When using such frameworks, you have nothing special to configure in your composer.json, git push your code and everything will work!

List of the frameworks:

Configuration tweaks

Setup basic auth

You may want to hide your application behind an authentication gateway. You can configure HTTP basic auth for your application.

PHP-FPM concurrency

The level of concurrency configured is defined automatically according to the size of the containers of your application. If you want to override this value, you can define the environment variable: WEB_CONCURRENCY.

The value defined here, directly modify the pm.max_children parameter, defining how much process will be run by php-fpm.

Buildpack custom configuration

The buildpack allows you to configure precisely how your application is deployed. This configuration is done in your composer.json at the root of your project.

All these fields are optional, define them if you need to modify their default value.

{
   // Your content
  "extra": {
    // default values of PaaS specific instructions
    "paas": {
      "document-root": "",
      "index-document": "index.php",
      "engines": {
        "nginx": "default",
      },
      "php-config": [],
      "php-includes": [],
      "php-fpm-config": [],
      "php-fpm-includes": [],
      "nginx-includes": [],
      "log-files": [],
      "compile": [],
      "new-relic": false,
      "access-log-format": ""
    }
  }
}

.extra.paas.document-root

The directory where Nginx will define the root of your app.

This parameter can also be overridden with the DOCUMENT_ROOT environment variable.

.extra.paas.index-document

Name of the index document of each directory. When accessing a directory (https://example.scalingo.io/web/), Nginx looks by default for an index.php file to execute, if your project is using another name, specify it here.

.extra.paas.engines.nginx

Define a precise version of Nginx to use. By default your application is reachable through the last stable version of the server. Most of the time, you don’t need to change this value.

.extra.paas.php-config

List of directives which will be added to your php.ini.

Example:

{
  "php-config": [
    "display_errors=off",
    "short_open_tag=on"
  ]
}

.extra.paas.php-fpm-config

List of directives which will be added to your php-fpm.ini.

Example:

{
  "php-fpm-config": [
    "log_level=debug"
  ]
}

.extra.paas.php-includes

Extra files which will be included in the php.ini.

.extra.paas.php-fpm-includes

Extra files which will be included in the php-fpm.ini.

.extra.paas.nginx-includes

Extra files which will be included in the Nginx configuration of your application.

.extra.paas.compile

Commands to run after the dependency installation.

Example:

{
  "compile": [
    "php app/console assetic:dump --env=prod --no-debug"
  ]
}

.extra.paas.log-files

If your project is writing in custom log files, you can specify them here and they will be streamed to the logs of your application.

Your can read the logs on your dashboard or with the Scalingo CLI utility.

.extra.paas.new-relic

If true, enable new-relic instrumentation tools.

The environment variable named NEW_RELIC_LICENSE_KEY is required.

.extra.paas.access-log-format

The format of the logs produced by the proxy Nginx for each request to your application.

It is empty by default, it means that Nginx will use the following format:

'$http_x_forwarded_for - "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent"'

e.g.

109.26.203.98 - "GET / HTTP/1.1" 200 1761 "http://google.com/search" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.12; rv:51.0) Gecko/20100101 Firefox/51.0"

When defining a custom value for the log format, please refer to the Nginx documentation page..

This parameter can also be overridden with the ACCESS_LOG_FORMAT environment variable.

Warning: .htaccess files

Legacy projects often use .htaccess file in their project to modify the configuration of the Apache server. As the buildpack is based on Nginx and PHP-FPM, these files are ineffective.

Instead of using these files, you have to write directives for Nginx and configure the nginx-includes part of your composer.json. It can contains one or more configuration files:

{
  
  "extra": {
    "paas": {
      "nginx-includes": ["path/to/nginx_conf_file", ]
    }
  }
}

Example: URL rewriting (e.g. WordPress)

Here is an example of legacy .htaccess which won’t work on Scalingo. You need to replace it with the Nginx configuration following the example.

Legacy .htaccess example:

<IfModule mod_rewrite.c>
RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . /index.php [L]
</IfModule>

Nginx configuration:

location / {
  try_files $uri $uri/ /index.php?$args;
}

mode_edit Suggest edits