PHP buildpack

This is the cloudControl PaaS PHP buildpack conforming to the Heroku buildpack api. It runs PHP applications using Apache and PHP-FPM.

Composer - dependency management

Composer is used to manage the dependencies. There should be a 'composer.json' file in the top directory of the project.

For example the 'composer.json' file, for a project that uses the Zend framework, would look like this:

{
    "name": "application-name",
    "description": "Application's description",
    "license": "the-licence",
    "keywords": [
        "keyword1",
        "keyword2"
    ],
    "homepage": "http://example.com/",
    "require": {
        "php": ">=5.3.3",
        "zendframework/zendframework": "2.*"
    }
}

It is also possible to include composer executable (composer.phar) in the top directory of the project. In this case provided composer executable will be used instead of platform default one.

Extensions

The buildpack comes pre-configured with the following PHP extensions:

• Blackfire - Blackfire Profiler automatically instruments your code to gather data about consumed server resources like memory, CPU time, and I/O.

For example, to enable the Blackfire extension, add 'ext-blackfire' to the 'require' section of your 'composer.json' file:

    "require": {
        "ext-blackfire": "*"
    }

Frameworks

The following frameworks are currently supported:

• Symfony 1
• Symfony 2
• Zend 1
• Zend 2
• Yii
• Kohana
• CakePhp

Other frameworks might work if you just specify the DocumentRoot manually.

Custom Procfile

The buildpack generates a file called Procfile in your project root, which is used to start your application, If you want to define worker process types, you have to override this default Procfile with your own. In this case you also have to explicitly provide the web process command:

web: bash boot.sh
myworker: php code/do_work.php --some-worker-option

Your repository contents are located beneath code/, so if you have a worker script in your repository under scripts/mail_worker.php, use php code/scripts/mail_worker.php in your Procfile line. The name of the worker process type ("myworker" in the example) can be chosen arbitrarily.

Configuration

Buildpack

You can place buildpack configuration in the .buildpack directory of your repository. Some influential variables can be set in the file .buildpack/envrc.

Currently supported variables are:

COMPOSER_INSTALL_ARGS to set additional arguments you want to pass to the composer install command.

Example .buildpack/envrc:

export COMPOSER_INSTALL_ARGS="--prefer-source --optimize-autoloader"

Apache

For normal deployments the buildpack's default settings should work out of the box. If you want to pass additional options to Apache, place them in files under .buildpack/apache/conf directory. All files in this directory ending in .conf get included at the end of Apache's httpd.conf.

Manually Setting the DocumentRoot

By default the document root of the web application is '/app/code'. This can be modified in custom Apache configuration files too. Below is the example of the Apache configuration file (e.g. .buildpack/apache/conf/custom_document_root.conf) specifying a custom DocumentRoot and Directory:

# If the webroot is /page/public in your project, the DocumentRoot will be
# /app/code/page/public
DocumentRoot /app/code/page/public
# allow access to this directory (required)
<Directory /app/code/page/public>
    AllowOverride All
    Options SymlinksIfOwnerMatch
    Order Deny,Allow
    Allow from All
    DirectoryIndex index.php index.html index.htm
</Directory>

Create Alias

Whenever need to map between URLs and file system paths not being under DocumentRoot specify alias and pass it in custom configuration file, e.g .buildpack/apache/conf/sf_alias.conf:

#Create alias for symfony resources
Alias /sf /app/code/lib/vendor/symfony/data/web/sf
<Directory /app/code/lib/vendor/symfony/data/web/sf>
    AllowOverride All
    Options SymlinksIfOwnerMatch
    Order Deny,Allow
    Allow from All
</Directory>

Supported Apache Modules:

The following Apache Modules are available as part of the Pinky stack:

• mod_actions
• mod_alias
• mod_auth_basic
• mod_authn_file
• mod_authz_default
• mod_authz_groupfile
• mod_authz_host
• mod_authz_user
• mod_autoindex
• mod_deflate
• mod_dir
• mod_env
• mod_expires
• mod_headers
• mod_mime
• mod_negotiation
• mod_reqtimeout
• mod_rewrite
• mod_setenvif
• mod_status

PHP

Similarly, the default PHP configuration can be overridden or extended by specifying custom configuration files in .buildpack/php/conf directory. They should follow the PHP config syntax and should have an '.ini' extension, e.g:

[MySQL]
mysql.allow_persistent = On
mysql.max_persistent = -1
mysql.max_links = -1
mysql.connect_timeout = 60
mysql.trace_mode = Off

[MySQLi]
mysqli.max_links = -1
mysqli.default_port = 3306
mysqli.default_host = 127.0.0.1
mysqli.reconnect = Off

[APC]
apc.stat = 1
apc.enabled = 0
apc.shm_size = 27M

PHP-FPM

PHP applications on cloudControl run on the PHP-FPM FastCGI implemantation. The default configuration can be found here. In order to override or extend it, you should create file named php-fpm.ini under the .buildpack/php-fpm/conf/ directory and set your preffered setting under the appropriate section like this:

[global]
; error_log = /app/php/logs/php-fpm-error.log
error_log = /srv/www/code/data/logs/php-fpm-error.log

; Log level, possible values: alert, error, warning, notice, debug
; Default value: notice
log_level = debug

[www]
pm = dynamic
pm.start_servers = 1
pm.max_children = 5
slowlog = /srv/www/code/data/logs/php-fpm-slow.log