robofirm/php Puppet Module

Table of Contents

1. Module Description
2. Setup - The basics of getting started with robofirm/php
3. Usage - Configuration options and additional functionality
4. Reference - An under-the-hood peek at what the module is doing and how
5. Limitations - OS compatibility, etc.
6. Development - Guide for contributing to the module

Module description

This module installs PHP FPM with extensions and provides the ability to configure php settings, php extensions, and FPM pools via hiera data. To reduce complexity, this module does not and will not support mod_php with Apache. PHP FPM is independent from the web server and can be used with Apache, Nginx, or other software.

This module supports PHP 7.0, 7.1, 7.2, 7.3 and 7.4. This module also supports removal of a version that it has installed and installation of another version making it easy to upgrade existing servers.

Setup

Add this to your profile:

include php

Usage

All configuration is done via Hiera. Here is an example common configuration:

php::version: 7.4
php::extensions:
  gd: {}
  ioncube-loader: {}
  intl: {}
  mbstring: {}
  mcrypt: {}
  mysql: {}
  pecl-zendopcache: {}
  pdo: {}
  posix: {}
  redis: {}
  soap: {}
  xml: {}
php::fpm_pools:
  www:
    settings:
      group: nginx
      catch_workers_output: "yes"
php::settings:
  Date:
    date.timezone: America/New_York
  PHP:
    expose_php: "off"
    post_max_size: 10M
    memory_limit: 512M
    realpath_cache_size: 32k
    realpath_cache_ttl: 7200
    upload_max_filesize: 10M
php::cli_settings:
  Date:
    date.timezone: America/New_York
  PHP:
    max_execution_time: 0
    memory_limit: 1024M

Note, the quotation marks around "off" and "yes". These are reserved words in Hiera and will automatically be converted to boolean values if the quotes are omitted.

We highly recommend sticking to the Hiera method, but you can manually configure resources as well. The available resources are php, php::fpm, php::fpm_pool, and php::extension.

Resource signatures:

class php (
  Enum['absent', 'present', 'latest'] $ensure = 'present',
  Float $version                              = 7.4,
  Boolean $manage_repos                       = true,
  Optional[Hash] $service                     = {
    enable => true,
    ensure => running,
  },
  Optional[Hash] $extensions                  = { },
  Optional[Hash] $fpm_pools                   = { },
  Optional[Hash] $settings                    = { },
  Optional[Hash] $cli_settings                = { },
) {

class php::fpm (
  Enum['absent', 'present', 'latest'] $ensure = 'present',
  Float $version = 7.4,
  Hash $service = {
    enable => true,
    ensure => running,
  },
  Hash $settings = {},
  Hash $cli_settings = {},
) {}

define php::fpm_pool (
  Enum['absent', 'present'] $ensure = 'present',
  Hash $settings = {},
) {}

define php::extension (
  Enum['absent', 'present', 'latest'] $ensure = 'present',
  Float $php_version = 7.4,
  Hash $settings = {},
  Hash $cli_settings = {},
) {}

Configuration Reference

Note that while we will try our hardest to keep this reference up to date, there may be discrepencies. You can find these settings on your own by exploring the code starting from this entry point manifests/init.pp.

ensure

• Type: Enum["absent", "present", "latest"]
• Required: Yes
• Default: "present"

present installs PHP FPM

absent uninstalls PHP FPM and extensions

latest installs PHP FPM and updates it to the latest minor version within the given major version constraint

version

• Type: Float
• Required: Yes
• Default: 7.4

The major PHP version to install. Current valid values are 7.0, 7.1, 7.2, 7.3, and 7.4 but will expand as new PHP versions are released.

manage_repos

• Type: Boolean
• Required: Yes
• Default: true

Whether or not to manage repos. If set to false, this module assumes that the repos have already been set up and depends directly on the package names.

extensions

• Type: Hash
• Required: No
• Default: {}

A hash of extensions, each with these options:

ensure

• Type: Enum["absent", "present", "latest"]
• Required: Yes
• Default: "present"

present installs the extension

absent uninstalls the extension

latest installs the extension and updates it to the latest version for the given PHP FPM version

settings

• Type: Hash
• Required: No
• Default: {}

A hash of settings in ini format. These are used directly to modify the extension's ini file in php.d. The sections, keys, and values will be specific to the extension.

Here is an example for configuring Zend OpCache:

php::extensions:
  pecl-zendopcache:
    settings:
      opcache.memory_consumption: 768
      opcache.max_accelerated_files: 60000
      opcache.interned_strings_buffer: 12
      opcache.save_comments: 0
      opcache.load_comments: 0

cli_settings

• Type: Hash
• Required: No
• Default: {}

A hash of settings in ini format as above, but for command line PHP.

fpm_pools

• Type: Hash
• Required: No
• Default: {}

ensure

• Type: Enum["absent", "present"]
• Required: Yes
• Default: "present"

present installs the pool

absent uninstalls the pool

settings

• Type: Hash
• Required: No
• Default: {}

A hash of settings in ini format. These are used directly to modify the pool's conf file in pool.d.

Example pool configuration:

php::fpm_pools:
  www:
    settings:
      group: nginx
      catch_workers_output: "yes"
      pm: dynamic
      pm.max_children: 5
      pm.start_servers: 3
      pm.min_spare_servers: 2
      pm.max_spare_servers: 4
      pm.max_requests: 200

settings

• Type: Hash
• Required: No
• Default: {}

A hash of settings in ini format. These are used directly to modify the php.ini file. See the example configuration at the beginning of the Usage section for format.

Example:

php::settings:
  Date:
    date.timezone: America/New_York
  PHP:
    expose_php: "off"
    max_execution_time: 18000
    max_input_time: 200

cli_settings

• Type: Hash
• Required: No
• Default: {}

A hash of settings in ini format as above, but for command line PHP.

Reference

This module is intended to directly expose PHP FPM settings as much as possible via ini files, so that you can rely directly on PHP documentation. We don't want you to have to understand the inner workings of the module to use it.

Limitations

OS Support is currently limited to CentOS or RedHat. There are no immediate plans to support other operating systems as it would add complexity and doesn't fit our current needs.

Remi repos are used and are configured by this module using the example42/yum repository manager module, unless manage_repos is set to false.

Development

Open source is new to us at Robofirm, so this is TBD. Please raise issues in our Bitbucket issue tracker.

Robofirm PHP Puppet Module Changelog

2.1.0

• Added support for PHP 8.1 and 8.2
• Updated to default to PHP 8.2

2.0.1

• Added ability to manage php fpm service
• Updated to default to PHP 7.4

2.0.0

• Removed deprecated yum module dependency
• Added php 7.3, 7.4 support
• Removed php 5.x support

1.1.2

• Fixed dependency issue with checking php-fpm service status

1.1.1

• Internal updates. Updated Bitbucket repo URLs in README and metadata.json

1.1.0

• Added PHP 7.2 support

1.0.4

• Reverted to Hiera 4 syntax to continue to support Hiera 4.3 - 4.8.

1.0.3

• Updated requirements to Puppet >= 4.9.0 < 6.0.0
• Generalized OS support to version 7 for RedHat and CentOS
• Updated Readme to include ioncube and redis; commonly used php extensions

1.0.2

• Added epel repo include if set to manage repos. Some php extensions like mcrypt require the epel repo to be enabled to install dependencies like libmcrypt. I decided not to depend on the libmcrypt package in this case because yum already manages this dependency for the remi repo.

1.0.1

• Fixed PHP 7.0 and 7.1 lib, etc, and log dir symlinks
• Made removal of PHP remove all php extensions; Not just those listed in hiera data. Also addresses the issue of package removal dependency.

1.0.0

• Tagging this module as stable

0.2.7

• Added php::fpm_pools, php::settings, and php::cli_settings to hiera deep merge
• Ran all code through Puppet lint
• Added Puppet lint to Bitbucket Pipelines
• Fixed issue where using php::ensure: latest would cause some symlinks to be removed

0.2.6

• Added timezone setting for cli in example configuration

0.2.5

• Removed boilerplate setup instructions
• Cleaned up README
• Added MIT license
• Added humans.txt

0.2.4

• Fixed changelog

0.2.3

• Updated readme

0.2.2

• Updated to correctly restart php-fpm service when needed
• Updated to remove all php extensions when removing php
• Updated to remove symlinks when removing php
• Updated to only make symlinks if they are not already the expected path
• Improved handling of custom group in combination with writable paths for error log, session save, and wsdlcache

0.2.1

• Updated metadata.json
• Expanded documentation for public consumption

0.2.0

• Fixed issues with installing PHP 5.5 and 5.6 on RedHat
• Made behavior when removing PHP more complete