Skip to content

Latest commit

 

History

History
1528 lines (1243 loc) · 39.2 KB

advanced-php-config.md

File metadata and controls

1528 lines (1243 loc) · 39.2 KB

Advanced PHP Configuration Options

This engine exposes configuration options through the boxfile.yml, a yaml config file used to provision and configure your app's infrastructure when using Nanobox. Being a generic PHP engine, there are a lot of configuration options to try to allow compatibility with as many PHP apps as possible. This engine makes the following options available.

Overview of boxfile.yml Configuration Options

run.config:
  engine: php
  engine.config:
    # Web Server Settings
    webserver: 'apache'
    document_root: '/'

    # PHP Settings
    runtime: 'php-7.0'
    extensions:
      - curl
      - gd
      - mbstring
      - pdo_mysql
    zend_extensions:
      - ioncube_loader
      - opcache
    short_open_tag: true
    zlib_output_compression: 'Off'
    allow_url_fopen: 'On'
    disable_functions:
      - exec
      - shell_exec
      - system
    expose_php: 'On'
    max_execution_time: 30
    max_input_time: 30
    memory_limit: '128M'
    error_reporting: E_ALL
    display_errors: 'stderr'
    register_globals: 'Off'
    register_argc_argv: 'Off'
    post_max_size: '8M'
    upload_max_filesize: '2M'
    file_uploads: true
    max_file_uploads: 20
    max_input_vars: 1000
    default_mimetype: 'text/html'
    default_locale: 'en_US'
    browscap: 'app/browscap.ini'
    session_save_handler: 'files'
    session_save_path: 'app/sessions'
    session_length: 3600
    session_autostart: false
    date_timezone: 'US/central'
    iconv_internal_encoding: 'UTF-8'
    
    # Composer Settings
    composer_install: 'composer install --no-interaction --prefer-source'

    # Apache Settings
    apache_version: 2.2
    apache_document_root: '/'
    apache_index_list:
      - index.php
      - index.html
    apache_default_gateway: 'index.php'
    apache_php_interpreter: fpm
    apache_modules:
      - actions
      - alias
      - rewrite
    apache_max_spares: 10
    apache_max_clients: 128
    apache_server_limit: 128
    apache_max_requests: 10000
    apache_static_expire: 86400
    apache_log_level: warn
    apache_access_log: false

    # Nginx Settings
    nginx_document_root: '/'
    nginx_index_list:
      - index.php
      - index.html
    nginx_default_gateway: 'index.php'

    # Built-In PHP Web Server Settings
    builtin_document_root: '/'

    # PHP-FPM Settings
    php_fpm_events_mechanism: 'epoll'
    php_fpm_max_children: 20
    php_fpm_max_spare_servers: 1
    php_fpm_max_requests: 128

    # PHP GeoIP Settings
    geoip_custom_directory: 'app/GeoIP/'

    # PHP Memcache Settings
    memcache_chunk_size: 8192
    memcache_hash_strategy: 'standard'

    # PHP Mongo Settings
    mongo_native_long: 1
    mongo_allow_empty_keys: 0
    mongo_cmd: '$'
    mongo_long_as_object: 0

    # PHP APC Settings
    apc_shm_size: '32M'
    apc_num_files_hint: 1000
    apc_user_entries_hint: 4096
    apc_filters: ''

    # PHP eAccelerator Settings
    eaccelerator_shm_max: '0'
    eaccelerator_shm_size: '0'
    eaccelerator_filter: ''

    # PHP OPcache Settings
    opcache_memory_consumption: 64
    opcache_validate_timestamps: 1
    opcache_revalidate_freq: 2
    opcache_revalidate_path: 0
    opcache_save_comments: 1
    opcache_load_comments: 1
    opcache_enable_file_override: 0
    opcache_optimization_level: '0xffffffff'
    opcache_inherited_hack: 1
    opcache_dups_fix: 0
    opcache_blacklist_filename: ''

    # PHP XCache Settings
    xcache_size: 0
    xcache_var_size: 0
    xcache_admin_user: 'mOo'
    xcache_admin_pass: ''

    # PHP New Relic Settings
    newrelic_capture_params: false
    newrelic_ignored_params: ''
    newrelic_loglevel: info
    newrelic_framework: 'laravel'
    newrelic_framework_drupal_modules: true
    newrelic_browser_monitoring_auto_instrument: true
    newrelic_transaction_tracer_enabled: true
    newrelic_transaction_tracer_detail: 1
    newrelic_transaction_tracer_record_sql: 'obfuscated'
    newrelic_transaction_tracer_threshold: 'apdex_f'
    newrelic_transaction_tracer_stack_trace_threshold: '500'
    newrelic_transaction_tracer_explain_threshold: '500'
    newrelic_transaction_tracer_slow_sql: true
    newrelic_transaction_tracer_custom: ''
    newrelic_error_collector_enabled: true
    newrelic_error_collector_record_database_errors: true
    newrelic_webtransaction_name_files: ''
    newrelic_webtransaction_name_functions: ''
    newrelic_webtransaction_name_remove_trailing_path: false
Quick Links

Web Server Settings
PHP Settings
Composer Settings
Apache Settings
Nginx Settings
Built-In PHP Web Server Settings
PHP-FPM Settings
PHP GeoIP Settings
PHP Memcache Settings
PHP Mongo Settings
PHP APC Settings
PHP eAccelerator Settings
PHP OPcache Settings
PHP XCache Settings
PHP New Relic Settings

Web Server Settings

The following setting is used to select which web server to use in your application.

webserver

The following web servers are available:

run.config:
  engine: php
  engine.config:
    webserver: 'apache'

Web server specific settings are available in the Apache Settings, Nginx Settings, & Built-In PHP Web Server Settings sections below.

document_root

The public root of your web application. For instance, if you like to house your app in /public for security or organizational purposes, you can specify that here. The default is the /.

run.config:
  engine: php
  engine.config:
    document_root: '/'

PHP Settings

The following settings are typically configured in the php.ini. When using Nanobox, these are configured in the boxfile.yml.

runtime

Specifies which PHP runtime and version to use. The following runtimes are available:

  • php-5.3
  • php-5.4
  • php-5.5
  • php-5.6
  • php-7.0
  • php-7.1
  • php-7.2
run.config:
  engine: php
  engine.config:
    runtime: 'php-7.0'

extensions

Specifies what PHP extensions should be included in your app's environment. To see what PHP extensions are available, view the full list of available PHP extensions.

run.config:
  engine: php
  engine.config:
    extensions:
      - curl
      - gd
      - mbstring
      - pdo_mysql

zend_extensions

Specifies what Zend extensions should be included in your app's environment. To see what Zend extensions are available, view the Zend Extensions section of the PHP extensions list.

run.config:
  engine: php
  engine.config:
    zend_extensions:
      - ioncube_loader
      - opcache

short_open_tag

Sets the short_open_tag PHP setting.

run.config:
  engine: php
  engine.config:
    short_open_tag: true

zlib_output_compression

Sets the zlib.output_compression PHP setting.

run.config:
  engine: php
  engine.config:
    zlib_output_compression: 'Off'

allow_url_fopen

Sets the allow_url_fopen PHP setting.

run.config:
  engine: php
  engine.config:
    allow_url_fopen: 'On'

disable_functions

Sets the disable_fuctions PHP setting.

run.config:
  engine: php
  engine.config:
    disable_functions:
      - exec
      - shell_exec
      - system

expose_php

Sets the expose_php PHP setting.

run.config:
  engine: php
  engine.config:
    expose_php: 'On'

max_execution_time

Sets the max_execution_time PHP setting.

run.config:
  engine: php
  engine.config:
    max_execution_time: 30

max_input_time

Sets the max_input_time PHP setting.

run.config:
  engine: php
  engine.config:
    max_input_time: 60

memory_limit

Sets the memory_limit PHP setting. Note: This setting should not exceed the memory available on your PHP server(s).

run.config:
  engine: php
  engine.config:
    memory_limit: '128M'

error_reporting

Sets the error_reporting PHP setting.

run.config:
  engine: php
  engine.config:
    error_reporting: E_ALL

display_errors

Sets the display_errors PHP setting.

run.config:
  engine: php
  engine.config:
    display_errors: 'stderr'

register_globals

Sets the register_globals PHP setting

run.config:
  engine: php
  engine.config:
    register_globals: 'Off'

register_argc_argv

Sets the register_argc_argv PHP setting.

run.config:
  engine: php
  engine.config:
    register_argc_argv: 'Off'

post_max_size

Sets the post_max_size PHP setting.

run.config:
  engine: php
  engine.config:
    post_max_size: '8M'

upload_max_filesize

Sets the upload_max_filesize PHP setting.

run.config:
  engine: php
  engine.config:
    upload_max_filesize: '2M'

file_uploads

Sets the file_uploads PHP setting.

run.config:
  engine: php
  engine.config:
    file_uploads: true

max_file_uploads

Sets the max_file_uploads PHP setting.

run.config:
  engine: php
  engine.config:
    max_file_uploads: 20

max_input_vars

Sets the max_input_vars PHP setting.

run.config:
  engine: php
  engine.config:
    max_input_vars: 1000

default_mimetype

Sets the default_mime_type PHP setting.

run.config:
  engine: php
  engine.config:
    default_mimetype: 'text/html'

default_locale

Sets the intl.default_locale PHP setting.

run.config:
  engine: php
  engine.config:
    default_locale: 'en_US'

browscap

This allows you to specify the filepath to your browser capabilities file (browscap.ini). See PHP.net Docs for definition & configuration options. When specifying the path to your browscap.ini in your boxfile.yml, it should relative to the root of your repo.

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

run.config:
  engine: php
  engine.config:
    browscap: 'app/browscap.ini'

session_save_handler

Sets the session.save_handler PHP setting.

run.config:
  engine: php
  engine.config:
    session_save_handler: 'files'

session_save_path

Sets the session.save_path PHP setting.

run.config:
  engine: php
  engine.config:
    session_save_path: '/tmp/nanobox/sessions'

session_length

Sets the session.gc_maxlifetime PHP setting.

run.config:
  engine: php
  engine.config:
    session_length: 3600

session_autostart

Sets the session.autostart PHP setting.

run.config:
  engine: php
  engine.config:
    session_autostart: 'false'

date_timezone

Sets the date.timezone PHP setting.

run.config:
  engine: php
  engine.config:
    date_timezone: 'US/central'

iconv_internal_encoding

Sets the iconv.internal_encoding PHP setting.

run.config:
  engine: php
  engine.config:
    iconv_internal_encoding: 'UTF-8'

Composer Settings

The following settings allow you to customize how Composer is used in your application.

composer_install

composer_install

Customize the composer install command that is run in your app's build process.

run.config:
  engine: php
  engine.config:
    composer_install: 'composer install --no-interaction --prefer-source'

Apache Settings

The following settings are used to configure Apache. These only apply when using apache as your webserver.

apache_version

Defines which version of Apache to use in your application. The following versions are available:

  • 2.2
  • 2.4
run.config:
  engine: php
  engine.config:
    apache_version: 2.2

apache_document_root

The public root of your web application. For instance, if you like to house your app in /public for security or organizational purposes, you can specify that here. The default is the /.

Note: If both this setting and the global document_root are set, the builtin_document_root will take precedence.

run.config:
  engine: php
  engine.config:
    apache_document_root: '/'

apache_index_list

When a path is not specified in the url, these files are served in order in which they're listed.

run.config:
  engine: php
  engine.config:
    apache_index_list:
      - index.php
      - index.html

apache_default_gateway

When a path is not specified in the url, this files is served. This is similar to apache_index_list except it only accepts a single argument.

run.config:
  engine: php
  engine.config:
    apache_default_gateway: "index.php"

apache_php_interpreter

Specify which PHP interpreter you would like Apache to use.

  • fpm (default)
  • mod_php
run.config:
  engine: php
  engine.config:
    apache_php_interpreter: fpm

apache_modules

Specify which Apache modules to enable or disable. View the full list of available Apache Modules. By default, all modules are enabled.

run.config:
  engine: php
  engine.config:
    apache_modules

apache_max_spares

Sets Apaches MaxSpareServers directive.

run.config:
  engine: php
  engine.config:
    apache_max_spares: 10

apache_max_clients

Sets Apache's MaxClients directive. **Note:**This configuration must be less than or equal to the apache_server_limit.

run.config:
engine: php
  engine.config:
    apache_max_clients: 128

apache_server_limit

Sets Apaches ServerLimit directive. Note: This configuration must be greater than or equal to the apache_max_clients.

run.config:
  engine: php
  engine.config:
    apache_server_limit: 128

apache_max_requests

Sets Apache's MaxRequestsPerChild directive.

run.config:
  engine: php
  engine.config:
    apache_max_requests: 10000

apache_static_expire

Adds far future expires to your header, setting the number of seconds static assets are cached. By default, static asset caching is not enabled. We only recommend using this directive on apps whose static assets do not change often.

run.config:
  engine: php
  engine.config:
    apache_static_expire: 86400

apache_log_level

Sets Apache's LogLevel directive.

run.config:
  engine: php
  engine.config:
    apache_log_level: warn

apache_access_log

Enables or disables the Apache Access log.

run.config:
  engine: php
  engine.config:
    apache_access_log: false

Nginx Settings

These settings are used to configure nginx. They only apply when using nginx as your webserver.

nginx_document_root

The public root of your web application. For instance, if you like to house your app in /public for security or organizational purposes, you can specify that here. The default is the /.

Note: If both this setting and the global document_root are set, the nginx_document_root will take precedence.

run.config:
  engine: php
  engine.config:
    nginx_document_root: '/'

nginx_index_list

When a path is not specified in the url, these files are served in order in which they're listed.

run.config:
  engine: php
  engine.config:
    nginx_index_list:
      - index.php
      - index.html

nginx_default_gateway

When a path is not specified in the url, this files is served. This is similar to nginx_index_list except it only accepts a single argument.

run.config:
  engine: php
  engine.config:
    nginx_default_gateway: 'index.php'

Built-In PHP Web Server Settings

The following setting is used to configure the built-in PHP web server available in PHP 5.4+. These settings only apply when using builtin as your webserver.

builtin_document_root

The public root of your web application. For instance, if you like to house your app in /public for security or organizational purposes, you can specify that here. The default is the /.

Note: If both this setting and the global document_root are set, the builtin_document_root will take precedence.

run.config:
  engine: php
  engine.config:
    builtin_document_root: '/'

PHP-FPM Settings

These settings only apply when using fpm as your apache_php_interpreter.

php_fpm_events_mechanism

Sets events.mechanism setting in the php-fpm.conf which specifies the events mechanism FPM will use. More information is available in PHP's documentation.

run.config:
  engine: php
  engine.config:
    php_fpm_events_mechanism: 'epoll'

php_fpm_max_children

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

run.config:
  engine: php
  engine.config:
    php_fpm_max_children: 20

php_fpm_max_spare_servers

The desired maximum number of idle server processes.

run.config:
  engine: php
  engine.config:
    php_fpm_max_spare_servers: 1

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.

run.config:
  engine: php
  engine.config:
    php_fpm_max_requests: 128

PHP GeoIP Settings

The following settings are used to configure the GeoIP PHP extension.

geoip_custom_directory

Sets the geoip.custom_directory PHP setting. When specifying the path to the directory, it should be relative to the root of your repo.

Note: When using the geoip php extension, you need to provide your own GeoIP database. Free databases are [available for download from Maxmind]http://dev.maxmind.com/geoip/legacy/geolite/#Downloads. Maxmind also provides subscription databases that tend to be more accurate.

run.config:
  engine: php
  engine.config:
    geoip_custom_directory: 'app/GeoIP/'

PHP Memcache Settings

The following settings are used to configure the PHP Memcache driver.

memcache_chunk_size

Sets the memcache.chunk_size PHP setting.

run.config:
  engine: php
  engine.config:
    memcache_chunk_size: 8192

memcache_hash_strategy

Sets the memcache.hash_strategy PHP setting

run.config:
  engine: php
  engine.config:
    memcache_hash_strategy: 'standard'

PHP Mongo Settings

The following settings are used to configure the PHP Mongo driver.

mongo_native_long

Sets the mongo.native_long PHP setting.

run.config:
  engine: php
  engine.config:
    mongo_native_long: 1

mongo_allow_empty_keys

Sets the mongo.allow_empty_keys PHP setting

run.config:
  engine: php
  engine.config:
    mongo_allow_empty_keys: 0

mongo_cmd

Sets the mongo.cmd PHP setting.

run.config:
  engine: php
  engine.config:
    mongo_cmd: '$'

mongo_long_as_object

Sets the mongo.long_as_object PHP setting.

run.config:
  engine: php
  engine.config:
    mongo_long_as_object: 0

PHP APC Settings

The following settings are used to configure APC, a PHP byte-code caching engine available in PHP versions 5.3 and 5.4.

apc_shm_size

Sets the apc.shm_size PHP setting.

run.config:
  engine: php
  engine.config:
    apc_shm_size: '32M'

apc_num_files_hint

Sets the apc.num_files_hint PHP setting.

run.config:
  engine: php
  engine.config:
    apc_num_files_hint: 1000

apc_user_entries_hint

Sets the apc.user_entries_hint PHP setting.

run.config:
  engine: php
  engine.config:
    apc_user_entries_hint: 4096

apc_filters

Sets the apc.filters PHP setting.

run.config:
  engine: php
  engine.config:
    apc_filters: ''

PHP eAccelerator Settings

The following settings are used to configure eAccelerator, a PHP byte-code caching engine available in PHP versions 5.3 and 5.4.

eaccelerator_shm_max

Sets the eaccelerator.shm_max setting.

run.config:
  engine: php
  engine.config:
    eaccelerator_shm_max: '0'

eaccelerator_shm_size

Sets the eaccelerator.shm_size setting.

run.config:
  engine: php
  engine.config:
    eaccelerator_shm_size: '0'

eaccelerator_filter

Sets the eaccelerator.filter setting.

run.config:
  engine: php
  engine.config:
     eaccelerator_filter: ''

PHP Opcache Settings

The following settings are used to configure the OPcache PHP byte-code caching engine.

opcache_memory_consumption

Sets the opcache.memory_consumption PHP setting.

run.config:
  engine: php
  engine.config:
    opcache_memory_consumption: 64

opcache_validate_timestamps

Sets the opcache.validate_timestamps PHP setting.

run.config:
  engine: php
  engine.config:
    opcache_validate_timestamps: 1

opcache_revalidate_freq

Sets the opcache.revalidate_freq PHP setting

run.config:
  engine: php
  engine.config:
    opcache_revalidate_freq: 2

opcache_revalidate_path

Sets the opcache.revalidate_path PHP setting.

run.config:
  engine: php
  engine.config:
    opcache_revalidate_path: 0

opcache_save_comments

Sets the opcache.save_comments PHP setting.

run.config:
  engine: php
  engine.config:
    opcache_save_comments: 1

opcache_load_comments

Sets the opcache_load_comments PHP setting.

run.config:
  engine: php
  engine.config:
    opcache_load_comments: 1

opcache_enable_file_override

Sets the opcache.enable_file_override PHP setting.

run.config:
  engine: php
  engine.config:
    opcache_enable_file_override: 0

opcache_optimization_level

Sets the opcache.optimization_level PHP setting.

run.config:
  engine: php
  engine.config:
    opcache_optimization_level: '0xffffffff'

opcache_inherited_hack

Sets the opcache.inherited_hack PHP setting.

run.config:
  engine: php
  engine.config:
    opcache_inherited_hack: 1

opcache_dups_fix

Sets the opcache.dups_fix PHP setting.

run.config:
  engine: php
  engine.config:
    opcache_dups_fix: 0

opcache_blacklist_filename

Sets the opcache.blacklist_filename PHP setting.

run.config:
  engine: php
  engine.config:
    opcache_blacklist_filename: ''

PHP XCache Settings

The following settings are used to configure the XCache PHP byte-code caching engine.

xcache_size

Sets the xcache.size setting.

run.config:
  engine: php
  engine.config:
    xcache_size: 0

xcache_var_size

Sets the xcache.var_size setting.

run.config:
  engine: php
  engine.config:
    xcache_var_size: 0

xcache_admin_user

Sets the xcache.admin.user setting.

run.config:
  engine: php
  engine.config:
    xcache_admin_user: 'mOo'

xcache_admin_pass

Sets the xcache_admin_pass setting.

run.config:
  engine: php
  engine.config:
    xcache_admin_pass: ''

PHP New Relic Settings

The following settings are used to configure the PHP New Relic Agent.

newrelic_capture_params

Sets the newrelic.capture_params setting.

run.config:
  engine: php
  engine.config:
    newrelic_capture_params: false

newrelic_ignored_params

Sets the newrelic.ignored_params setting.

run.config:
  engine: php
  engine.config:
    newrelic_ignored_params: ''

newrelic_loglevel

Sets the newrelic.loglevel setting.

run.config:
  engine: php
  engine.config:
    newrelic_loglevel: 'info'

newrelic_framework

Sets the newrelic.framework setting.

run.config:
  engine: php
  engine.config:
    newrelic_framework: 'laravel'

newrelic_framework_drupal_modules

Sets the newrelic.framework.drupal.modules setting.

run.config:
  engine: php
  engine.config:
    newrelic_framework_drupal_modules: true

newrelic_browser_monitoring_auto_instrument

Sets the newrelic.browser_monitoring_auto_instrument setting.

run.config:
  engine: php
  engine.config:
    newrelic_browser_monitoring_auto_instrument: true

newrelic_transaction_tracer_enabled

Sets the newrelic.transaction_tracer.enabled setting.

run.config:
  engine: php
  engine.config:
    newrelic_transaction_tracer_enabled: true

newrelic_transaction_tracer_detail

Sets the newrelic.transaction_tracer.detail setting.

run.config:
  engine: php
  engine.config:
    newrelic_transaction_tracer_detail: 1

newrelic_transaction_tracer_record_sql

Sets the newrelic.transaction_tracer.record_sql setting.

run.config:
  engine: php
  engine.config:
    newrelic_transaction_tracer_record_sql: 'obfuscated'

newrelic_transaction_tracer_threshold

Sets the newrelic.transaction_tracer.threshold setting.

run.config:
  engine: php
  engine.config:
    newrelic_transaction_tracer_threshold: 'apdex_f'

newrelic_transaction_tracer_explain_threshold

Sets the newrelic.transaction_tracer.explain_threshold setting.

run.config:
  engine: php
  engine.config:
    newrelic_transaction_tracer_explain_threshold: '500'

newrelic_transaction_tracer_stack_trace_threshold

Sets the newrelic.transaction_tracer.stack_trace_threshold setting.

run.config:
  engine: php
  engine.config:
    newrelic_transaction_tracer_stack_trace_threshold: '500'

newrelic_transaction_tracer_slow_sql

Sets the newrelic.transaction_tracer.slow_sql setting.

run.config:
  engine: php
  engine.config:
    newrelic_transaction_tracer_slow_sql: true

newrelic_transaction.tracer_custom

Sets the newrelic.transaction_tracer.custom setting.

run.config:
  engine: php
  engine.config:
    newrelic_transaction_tracer_custom: ''

newrelic_error_collector_enabled

Sets the newrelic.error_collector.enabled setting.

run.config:
  engine: php
  engine.config:
    newrelic_error_collector_enabled: true

newrelic_error_collector_record_database_errors

Sets the newrelic.error_collector.record_database_errors setting.

run.config:
  engine: php
  engine.config:
    newrelic_error_collector_record_database_errors: true

newrelic_webtransaction_name_files

Sets the newrelic.webtransaction.name.files setting.

run.config:
  engine: php
  engine.config:
    newrelic_webtransaction_name_files: ''

newrelic_webtransaction_name_functions

Sets the newrelic.webtransaction.name.functions setting.

run.config:
  engine: php
  engine.config:
    newrelic_webtransaction_name_functions: ''

newrelic_webtransaction_name_remove_trailing_path

Sets the newrelic.webtransaction.name_remove_trailing_path setting.

run.config:
  engine: php
  engine.config:
    newrelic_webtransaction_name_remove_trailing_path: false

Help & Support

This is a generic (non-framework-specific) PHP engine provided by Nanobox. If you need help with this engine, you can reach out to us in the #nanobox IRC channel. If you are running into an issue with the engine, feel free to create a new issue on this project.