PHP Settings in the Boxfile

Last Updated February 2015

The Boxfile is a yaml config file that allows you to custom-configure your app's environment. The following PHP configuration options are available in the Boxfile and allow you to tailor-fit your PHP build specific to your needs. Any changes that would typically be made to your php.ini should be done here. After reading this doc, you should understand how to:

  • How to customize your PHP build
  • Bask in the awesomeness of PHP and Pagoda Box

Overview of PHP Boxfile Settings YAML

  web1:
    version: 5.6
    stability: production

    # php.ini Settings
    php_extensions:
      - json
      - mbstring
      - pdo
      - session
      - xml
    php_zend_extensions:
      - ioncube_loader
    php_expose_php: "Off"
    php_error_reporting: 30719
    php_display_errors: "1"
    php_disable_functions:
      - exec
      - shell_exec
      - system
    php_max_children: 20
    php_max_requests: 128
    php_max_execution_time: 30
    php_max_input_time: 60
    php_post_max_size: "8M"
    php_max_input_vars: 1000
    php_file_uploads: "1"
    php_upload_max_filesize: "2M"
    php_max_file_uploads: 20
    php_opcode_mem_percentage: 50
    php_allow_url_fopen: "On"
    php_short_open_tag: "1"
    php_default_mimetype: "text/html"
    php_date_timezone: "US/central"
    php_default_locale: "en_US"
    php_geoip_custom_directory: "/data/app/GeoIP/"
    php_browscap: "/data/app/browscap.ini"
    php_register_globals: "0"
    php_iconv_internal_encoding: "UTF-8"
    php_register_argc_argv: "Off"
    php_zlib_output_compression: "Off"
    php_mail_add_x_header: "On"
    php_session_save_handler: "files"
    php_session_save_path: "/tmp/pagodabox/sessions"
    php_session_length: "3600"
    php_session_autostart: "0"
/Boxfile

PHP Configuration Options

PHP Version

This allows you to specify the version of php to load into your web or worker service. It defaults to the newest stable release. The following versions are available:

  • 5.3

  • 5.4

  • 5.5

  • 5.6

  • 7.0 (Default)

The specific patch level is determined by the "stability" config.

version YAML

# default setting
web1:
  type: php
  version: 7.0
/Boxfile
PHP Extensions

By default, your php executable is extremely slim, and only contains the core interpreter. All additional extensions are loaded when your instances are built. Simply list the extensions (from the list of available extensions) you need for your app in your Boxfile.

You can view the available extensions available for your version of php in the PHP Extensions doc.

php_extensions YAML

  web1:
    php_extensions: [eaccelerator, mysql, curl]
      ##OR##
    php_extensions:
      - eaccelerator
      - mysql
      - curl
    php_zend_extensions:
      - ioncube_loader
/Boxfile
Expose PHP

See PHP.net Docs for definition & configuration options.

php_expose_php YAML

  web1:
    php_expose_php: "On"
/Boxfile
PHP Error Reporting

See PHP.net Docs for definition & configuration options.

php_error_reporting YAML

  # default setting
  web1:
    php_error_reporting: 30719 # Equivalent to E_ALL
/Boxfile
PHP Display Errors

See PHP.net Docs for definition & configuration options.

display_errors YAML

  # default setting
  web1:
    php_display_errors: "1"
/Boxfile
PHP Disable Functions

See PHP.net Docs for definition & configuration options.

php_disable_functions YAML

  web1:
    php_disable_functions:
      - exec
      - shell_exec
      - system
/Boxfile
PHP-FPM Max Children

Sets the maximum number of child processes that can be created by PHP.

Note: This setting will only apply when using fastcgi as your apache PHP interpreter.

Use the PHP-FPM Max Children Setting carefully

Changing the Max Children setting can drastically affect how your web instances use available resources and can lead to reduced performance and/or unresponsiveness.

php_max_children YAML

  # default setting
  web1:
    php_max_children: 20
/Boxfile
PHP-FPM Max Requests

Sets the number of requests each child process should execute before respawning. This can be useful to work around memory leaks in 3rd party libraries.

Note: This setting will only apply when using fastcgi as your apache PHP interpreter.

Use the PHP-FPM Max Requests Setting Carefully

Changing the Max Requests setting can drastically affect how your web instances use available resources and can lead to reduced performance and/or unresponsiveness.

php_max_requests YAML

  # default setting
  web1:
    php_max_requests: 128
/Boxfile
PHP Max Execution Time

See PHP.net Docs for definition & configuration options.

php_max_execution_time YAML

  # default setting
  web1:
    php_max_execution_time: 30
/Boxfile
PHP Max Input Time

See PHP.net Docs for definition & configuration options.

php_max_input_time YAML

  # default setting
  web1:
    php_max_input_time: 60
/Boxfile
PHP Max Post Size

See PHP.net Docs for definition & configuration options.

php_post_max_size YAML

  # default setting
  web1:
    php_post_max_size: "8M"
/Boxfile
PHP Max Input Vars

See PHP.net Docs for definition & configuration options.

php_max_input_vars YAML

  # default setting
  web1:
    php_max_input_vars: 1000
/Boxfile
PHP File Uploads

See PHP.net Docs for definition & configuration options.

php_file_uploads YAML

  # default setting
  web1:
    php_file_uploads: "1"
/Boxfile
PHP Upload Max Filesize

See PHP.net Docs for definition & configuration options.

php_upload_max_filesize YAML

  # default setting
  web1:
    php_upload_max_filesize: "2M"
/Boxfile
PHP Max File Uploads

See PHP.net Docs for definition & configuration options.

php_max_file_uploads YAML

  # default setting
  web1:
    php_max_file_uploads: 20
/Boxfile
PHP OpCode Cache Memory Percentage

Upon startup, PHP OpCode caching engines (APC, eAccelerator, xCache, OpCache) immediately reserve a percentage of the available RAM. This setting allows you to configure that percentage.

In your dashboard stats, the OpCode cache percentage will be reflected in your Swap immediately after the process starts. However it may not be reflected in your RAM usage. The caching engines reserve the memory space, but they don't necessarily use it. Reserved memory will always be refelected in Swap. If you find yourself running out of Swap often, you may consider lowering this percentage.

php_opcode_mem_percentage YAML

  # default setting
  web1:
    php_opcode_mem_percentage: 50
/Boxfile
PHP Allow URL fopen

See PHP.net Docs for definition & configuration options.

php_allow_url_fopen YAML

  # default setting
  web1:
    php_allow_url_fopen: 'On'
/Boxfile
PHP Short Open Tag

See PHP.net Docs for definition & configuration options.

php_short_open_tag YAML

  # default setting
  web1:
    php_short_open_tag: "1"
/Boxfile
PHP Default MIME Type

See PHP.net Docs for definition & configuration options.

php_default_mimetype YAML

  # default setting
  web1:
    php_default_mimetype: "text/html"
/Boxfile
PHP Default Date Timezone

See PHP.net Docs for definition & configuration options.

php_date_timezone YAML

  # default setting
  web1:
    php_date_timezone: "US/central"
/Boxfile
Default Locale

See PHP.net Docs for definition & configuration options.

php_default_locale YAML

  web1:
    php_default_locale: "en_US"
/Boxfile
GeoIP Custom Directory

See PHP.net Docs for definition & configuration options.

Note: When specifying the path to the directory, be sure to use the absolute server path, /data.

You Must Provide a GeoIP Database

When using the geoip php extension, you need to provide your own GeoIP database. Free databases are available for download from Maxmind. Maxmind also provides subscription databases that tend to be more accurate.

php_geoip_custom_directory YAML

  web1:
    php_geoip_custom_directory: "/data/app/GeoIP/"
/Boxfile
PHP Browscap

This allows you to specify the filepath to your browser capabilities file (browscap.ini). See PHP.net Docs for definition & configuration options.

You must include your own browscap.ini in your app's repo. They are available for free from browscap.org.

Note: When specifying the path to your browscap.ini, be sure to use the absolute server path, /data.

php_browscap YAML

  web1:
    php_browscap: "/data/app/browscap.ini"
/Boxfile
PHP Register Globals

See PHP.net Docs for definition & configuration options.

php_register_globals YAML

  # default setting
  web1:
    php_register_globals: "0"
/Boxfile
PHP iconv Internal Encoding

See PHP.net Docs for definition & configuration options.

php_iconv_internal_encoding YAML

  # default setting
  web1:
    php_iconv_internal_encoding: "UTF-8"
/Boxfile
PHP Register argc argv

See PHP.net Docs for definition & configuration options.

php_register_argc_argv YAML

  # default setting
  web1:
    php_register_argc_argv: "Off"
/Boxfile
zlib Output Compression

See PHP.net Docs for definition & configuration options.

php_zlib_output_compression YAML

  # default setting
  web1:
    php_zlib_output_compression: "Off"
/Boxfile
Mail Add X Header

See PHP.net Docs for definition & configuration options.

php_mail_add_x_header YAML

  # default setting
  web1:
    php_mail_add_x_header: "On"
/Boxfile
PHP Session Save Handler

See PHP.net Docs for definition & configuration options.

php_session_save_handler YAML

  # default setting
  web1:
    php_session_save_handler: "files"
/Boxfile

May Need PHP Extensions for other Session Handlers

If you choose to use Redis or Memcached as your session save handler, you will need to include either the redis or memcache php_extensions.

PHP Session Save Path

See PHP.net Docs for definition & configuration options.

php_session_save_path YAML

  web1:
    php_session_save_path: "/tmp/pagodabox/sessions"
/Boxfile

Session Save Paths for Memcached & Redis

If you're using session save paths for Memcached or Redis, use the host and port for your cache service provided in the dashboard or your service environment variables and connect through tcp.

Example: tcp://${CACHE1_HOST}:${CACHE1_PORT}

PHP Session Length

See PHP.net Docs for definition & configuration options.

php_session_length YAML

  # default setting
  web1:
    php_session_length: "3600"
/Boxfile
PHP Session Autostart

See PHP.net Docs for definition & configuration options.

php_session_autostart YAML

  # default setting
  web1:
    php_session_autostart: "0"
/Boxfile

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