Getting started

Support for different PHP versions

The debops.php role supports management of multiple PHP versions; only one PHP version can be managed at a time. By default the role will install and configure the PHP version provided with the current OS release.

The role checks for existence of php7.3, php and php5.6 APT packages (by default in that order) and based on available versions installs either php7.3-*, the version preferred by the php package or php5.6-* APT packages. If multiple versions of the PHP packages are available, the first found one wins. To force an older version in case the newer one is installed, you can change the order of the packages used for the version detection using the php__version_preference list.

To learn how to specify different PHP packages for installation, refer to php__packages documentation.

PHP packages provided by Ondřej Surý

Ondřej Surý is a member of the Debian PHP Maintainers team and maintains Debian PHP5 and PHP7 packages. He also provides an external APT package repository of PHP5 and PHP7 packages (among other things) for Debian and Ubuntu distributions.

The debops.php role can use the packages from the Ondřej Surý repositories to provide PHP7 packages on Debian Jessie. Remember that these packages DO NOT fall under the Debian Stable security support and may contain bugs.

To enable the custom APT repository, add in the Ansible inventory:

php__sury: True

This will add the required OpenPGP keys and APT repositories. The order of the package versions should ensure that the PHP7 packages will be installed on Debian Jessie.

Custom environment role

The debops.php provides a small, custom role debops.php/env which should be added to the playbook or role dependencies before the main role and other roles that use configuration from debops.php, like debops.logrotate. The debops.php/env role configures custom APT repositories if they are enabled and prepares the facts needed by other roles to function correctly. See the provided playbook to see an example usage.

PHP Composer installation

The debops.php role will install the PHP Composer, a dependency manager for PHP. The version from the OS repositories will be preferred. On older OS releases (including Debian Stretch), a known upstream binary will be downloaded and installed instead.

Layout of the php.ini configuration

The main /etc/php5,/7.0/*/php.ini files maintained by the OS distribution are not modified by the debops.php role to allow an easy upgrade process. Instead, a custom php.ini configuration is stored in /etc/php5,/7.0/ansible/*.ini files generated using a simple template, which are then linked to each of the PHP SAPI directories in /etc/php5,/7.0/*/conf.d/ which are read by the PHP interpreters. This allows for configuration synchronization between different PHP interpreters. To learn more about this process refer to php__configuration documentation.

Information stored in Ansible local facts

The PHP version configured on a host is available for other Ansible roles through the Ansible local facts. The specific variables are:

ansible_local.php.version

Short version of the PHP environment, used in package names. Either 5 or 7.0.

ansible_local.php.long_version

Longer version of the PHP environment, used for version comparison. For example, 5.6.22 or 7.0.8. This variable might be inaccurate in case of the minor or major version upgrade.

The Ansible local facts are used by the debops.php role to ensure idempotent operation. In case that you want to upgrade a host to a newer PHP release without uninstalling the older one, you can set php__reset to True, so that the role can re-detect the available PHP versions. After one role run, you should set php__reset back to its default value.

Example inventory

To enable management of a PHP environment on a host, you need to include that host in the [debops_service_php] Ansible inventory group:

[debops_service_php]
hostname

The default configuration included in the role will install the base PHP cli and fpm packages and create a PHP-FPM pool meant to be used by the www-data user which is a common user account used to serve PHP applications packaged on Debian systems. To deploy your own applications you should consider creating a custom system account and a corresponding PHP-FPM pool to securely separate it from other applications. To learn how to do that, refer to the php__pools documentation.

Example playbook

If you are using this role without DebOps, here's an example Ansible playbook that uses the debops.php role:

---

- name: Install and manage PHP environment
  collections: [ 'debops.debops', 'debops.roles01',
                 'debops.roles02', 'debops.roles03' ]
  hosts: [ 'debops_service_php' ]
  become: True

  environment: '{{ inventory__environment | d({})
                   | combine(inventory__group_environment | d({}))
                   | combine(inventory__host_environment  | d({})) }}'

  pre_tasks:

    - name: Apply keyring configuration for php environment
      ansible.builtin.import_role:
        name: 'keyring'
      vars:
        keyring__dependent_apt_keys:
          - '{{ php__keyring__dependent_apt_keys }}'
      tags: [ 'role::keyring', 'skip::keyring', 'role::php' ]

    - name: Prepare php environment
      ansible.builtin.import_role:
        name: 'php'
        tasks_from: 'main_env'
      tags: [ 'role::php', 'role::php:env', 'role::logrotate' ]

  roles:

    - role: apt_preferences
      tags: [ 'role::apt_preferences', 'skip::apt_preferences' ]
      apt_preferences__dependent_list:
        - '{{ php__apt_preferences__dependent_list }}'

    - role: cron
      tags: [ 'role::cron', 'skip::cron' ]

    - role: logrotate
      tags: [ 'role::logrotate', 'skip::logrotate' ]
      logrotate__dependent_config:
        - '{{ php__logrotate__dependent_config }}'

    - role: php
      tags: [ 'role::php', 'skip::php' ]

Ansible tags

You can use Ansible --tags or --skip-tags parameters to limit what tasks are performed during Ansible run. This can be used after a host was first configured to speed up playbook execution, when you are sure that most of the configuration is already in the desired state.

Available role tags:

role::php

Main role tag, should be used in the playbook to execute all tasks.

role::php:config

Generate the PHP and PHP-FPM configuration.

role::php:pools

Generate only PHP-FPM pool configuration.