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 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
web1: 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:
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
web1: name: front-end type: php httpd_document_root: public web2: name: api type: php httpd_document_root: api
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
web1: 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
web1: 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.
Table of Contents
- Creating a PHP Web Service
- PHP Web Services in the Boxfile
- Configuring PHP & Apache
- Using Multiple PHP Web Services
- Multiple PHP Web Services in the Boxfile
If you have any questions, suggestions, or corrections, let us know.