Last Updated October 2014

PHP is a "general-purpose scripting language that is especially suited to web development." Pagoda Box was initially built specifically for PHP and makes creating and using PHP services incredibly simple. This doc walks through how PHP works on Pagoda Box and how you can use it. After reading it, you should be familiar with:

  • Creating & Configuring PHP Webs & Workers
  • The differences between PHP Webs & Workers
  • Basking in the awesomeness of PHP on a scalable cloud infrastructure

PHP Webs

PHP web services house publicly accessible web applications powered by Apache and a PHP. All web services are accessed through the http protocol. For more information on web services in general, check out the Web Services doc.


PHP web services consist of one or more instances, each running an Apache web server and PHP process.

The particular flavor of Apache used on Pagoda Box has been optimized for performance. It uses the mod_php module for PHP interpretation and supports normal usage of .htaccess files, .htpasswd files, custom error pages, etc.

Creating a PHP Web Service

To create a PHP web service, simply include a web service in your Boxfile with the type specified as "php". On your next deploy, your PHP service will be created.

PHP Web Services in the Boxfile YAML

    type: php

Configuring PHP & Apache

On Pagoda Box, the configuration that typically happens in your httpd.conf and php.ini is handled in your Boxfile. There are many options available for both PHP and Apache. The following docs cover them in detail:

PHP Settings in the Boxfile
PHP Extensions
Apache Settings in the Boxfile

Using Multiple PHP Web Services

In many cases, having multiple PHP web services in a single app comes in handy. Some good uses cases are given in the Web Services doc. When using multiple PHP webs, your document root acts as the key differentiator between services. This is set using the httpd_document_root setting in your Boxfile. This is what specifies the public root or which directory a web service should run out of. If two PHP web services use the same document root, they will run the same code.

Multiple PHP Web Services in the Boxfile YAML

    name: front-end
    type: php
    httpd_document_root: public
    name: api
    type: php
    httpd_document_root: api

PHP Workers

PHP workers house only a PHP process. Workers are meant to be used for heavy or long running background tasks, not web traffic. They cannot be accessed via http. For more information on workers, check out the Workers doc.


PHP workers consist of one or more instances, each running a PHP process. Generally, workers should consist of a looping PHP script that continually checks some type of job queue. When it finds a job in the queue, it pulls the job, performs a given task, the continues to check the queue. The queue can come in many different forms and it's up to you to implement it. There is an example of a PHP Worker in the Workers doc.

Creating a PHP Worker Service

To create a PHP worker, simply include a worker service in your Boxfile with the type specified as "php" and your worker exec — the command that starts your worker script. On your next deploy, your worker will be created.

PHP Workers in the Boxfile YAML

    type: php
    exec: 'php path/to/worker-script.php'

Configuring PHP in Workers

The same PHP configuration options available to web services are available to workers. These are covered in the PHP Settings in the Boxfile doc

Scaling PHP Services

PHP web and worker services are extremely flexible, able to scale both horizontally and vertically.

Horizontal Scaling (adding instances) allows your PHP service to better handle concurrent requests. For PHP webs, this means they'll be able to handle more concurrent traffic. For workers, it means they'll be able to process more jobs concurrently.

Vertical Scaling (adding resources) gives each of your service's instances more power to perform their given tasks.

Check out the How & When to Scale doc for detailed information about scaling on Pagoda Box.

PHP Log Streams

By default, PHP and Apache output their logs to stdout and stderr. Anything logged to stdout or stderr is streamed through the Pagoda Logging System. In your Boxfile, you have the ability to toggle the standard PHP and Apache Error Logs.

Log Stream Settings in the Boxfile YAML

    type: php
    # default settings
    php_error_log: true
    apache_access_log: false
    apache_error_log: true

Note: PHP workers do not include Apache will not output any Apache logs.

PHP & Composer

Composer has quickly become the tool of choice for managing dependencies in PHP. Luckily, it's incredibly easy to use on Pagoda Box. On deploy, we run the composer install command as the default build hook to load your Composer dependencies.

For a complete understudying of how Composer works on Pagoda Box, check out the Composer doc.

If you have any questions, suggestions, or corrections, let us know.