Contents¶

Introduction¶

puppet-php is a module for managing PHP using puppet.

Why Use puppet-php¶

it’s very fast to install, a few minutes tops.
it supports all PHP SAPIs out of the box.
it supports a lot of PHP extensions out of the box.
it’s is very flexible and has tons of configuration options, and sane defaults.
it aims to stay out of your way, and if it happens to get in your way, you can change the undesired behavior very easily.
it removes the boilerplate code from your manifests, which mean less code to maintain, and less code to spend time unit testing.
it uses the MIT license.

Source code¶

The source can be found at github.com/jippi/puppet-php

License¶

The project is released under the permissive MIT license.

Bugs¶

If you happen to stumble upon a bug, please feel free to create a pull request with a fix (optionally with a test), and a description of the bug and how it was resolved.

You can also create an issue with a description to raise awareness of the bug.

Features¶

If you have a good idea for a feature, please join us on IRC and let’s discuss it. Pull requests are always more than welcome.

Support / Questions¶

You can find me on IRC in the #puppet channel on irc.freenode.net for any support or questions. My alias is Jippi

Installation¶

Installing composer is quick and simple.

Requirements¶

Debian / Ubuntu
puppet 3.2+

puppet module¶

puppet module install nodes/php

Using git submodule¶

git submodule add git@github.com:jippi/puppet-php.git modules/php

Class dependencies¶

Most of the inter-class dependencies is already taken care of internally in the plugin, though the configuration below is recommended to force the correct flow of installation, configuration and services

# Install extensions
Php::Extension <| |>
  # Configure extensions
  -> Php::Config <| |>
  # Reload webserver
  ~> Service["apache2"]

Note

The module will automatically detect if you use FPM and reload it when relevant PHP configuration has changed

Quick Start¶

You are busy, and you just want to get things done™, so let’s get going.

After installation, you are ready to roll.

Simple install¶

Install PHP-FPM, PHP CLI and the APC extension.

include php

class { ['php::fpm', 'php::cli', 'php::extension::apc']:

}

Advanced install¶

Install PHP-FPM, PHP CLI and the APC extension with custom configuration.

include php

class { 'php::cli': }

class { 'php::fpm':
  emergency_restart_threshold  => 5,
  emergency_restart_interval   => '1m',
  rlimit_files                 => 32768,
  events_mechanism             => 'epoll'
}

class { 'php::extension::apc':
  settings => [
    # Augeas commands, one command per array entry
    'set .anon/apc.enabled' => 1
  ]
}

Configuration¶

The configuration functions all take two arguments, $file and $config

They all rely exclusively on augeas for configuration and thus, configuration is done using augeas commands for maximum flexibility.

The puppet-php module includes a custom lens backported from the augeas project, so it can support all PHP ini and FPM pool configurations out of the box.

php::config¶

The most basic configuration function in puppet-php.

It’s basically a wrapper for an augeas block, with the small twist that it automatically uses the internal augeas lens for PHP and for faster modification time.

Note

This function does not trigger any refresh of services out of the box

Example code, configuring PHP APC to be enabled and use more memory than default.

php::config { 'a-unique-name':
  file    => '/path/to/the/ini/file',
  config  => [
    'set .anon/apc.enabled 1',
    'set .anon/apc.shm_size 64M'
  ]
}

Alternatively this configuration can be achieved with our dwim (Do what I mean) interface:

php::config { 'enabled=1':
  file    => '/path/to/the/ini/file',
  section => 'APC',
}
php::config { 'shm_size=64M':
  file    => '/path/to/the/ini/file',
  section => 'APC',
}

Or.. more verbosely:

php::config { 'Enable APC':
  setting => 'enable',
  value   => '1'
  file    => '/path/to/the/ini/file',
  section => 'APC',
}
php::config { 'Configure APC shm size':
  setting => 'shm_size',
  value   => '64M',
  file    => '/path/to/the/ini/file',
  section => 'APC',
}

but it’s more useful for terse settings such as:

php::apache::config { 'upload_max_filesize=20M': }

php::fpm::config¶

This function works exactly as php::config, with the added benefit that any modifications done through this function, ensures that PHP FPM is reloaded.

Note

The default value for $file in this function is the actual PHP FPM configuration file

php::apache::config¶

This function works exactly as php::config, with the added benefit that any modifications done through this function, ensures that apache is reloaded.

Note

The default value for $file in this function is the actual PHP apache configuration file

php::cli::config¶

This function works exactly as php::config, with no automatic service reloading.

It’s left there mostly for completeness sake, and for more precise and easy manifest authoring.

Note

The default value for $file in this function is the actual PHP CLI configuration file

SAPI¶

puppet-php currently supports the SAPIs shown below.

Common arguments¶

These arguments are available for all SAPIs, though their defaults may be different across SAPIs.

$ensure defaults to installed.
$package default depends on SAPI.
$provider` default to undef.
$inifile default depends on SAPI.
$settings defaults to [ ] (empty array).

php::apache¶

Installs the mod_php PHP SAPI for apache.

$package defaults to libapache2-mod-php5.
$inifile defaults to /etc/php5/apache2/php.ini.
$service_name defaults to apache2.

Note

This class will not install Apache for you, please use a relevant module for that.

php::fpm¶

Installs the FPM PHP SAPI.

$package defaults to php5-fpm.
$inifile defaults to /etc/php5/fpm/php.ini.
$service_name defaults to php5-fpm.
$service_ensure defaults to running.
$service_enable defaults to true.
$service_has_status defaults to true.

php::cli¶

Installs the CLI PHP SAPI.

$package defaults to php5-cli.
$inifile defaults to /etc/php5/cli/php.ini.

Extensions¶

Common arguments¶

These arguments are available for all extensions, though their defaults may be different across SAPIs.

$ensure defaults to installed.
$package default depends on extension.
$provider` default depends on extension.
$inifile default depends on extension.
$settings defaults to [ ] (empty array).

apc¶

Class name: php::extension::apc.

$package defaults to php-apc for Squeeze, Wheezy, Lucid, Precise, Quantal and Raring. Other OS versions will default to php5-apcu.
$inifile defaults to ${php::params::config_root_ini}/apc.ini

apcu¶

Class name: php::extension::apcu.

$package defaults to php5-apcu
$inifile defaults to ${php::params::config_root_ini}/apcu.ini

curl¶

Class name: php::extension::curl.

$package defaults to php5-curl
$inifile defaults to ${php::params::config_root_ini}/curl.ini

gd¶

Class name: php::extension::gd.

$package defaults to php5-gd
$inifile defaults to ${php::params::config_root_ini}/gd.ini

gearman¶

Class name: php::extension::gearman.

$package defaults to php5-gearman
$inifile defaults to ${php::params::config_root_ini}/gearman.ini

http¶

Class name: php::extension::http.

$package defaults to php5-http
$inifile defaults to ${php::params::config_root_ini}/http.ini

igbinary¶

Note

The package requires the build-essential and php5-dev system packages.

Class name: php::extension::igbinary.

$package defaults to igbinary
$provider defaults to pecl
$inifile defaults to ${php::params::config_root_ini}/igbinary.ini
$settings defaults to ['set ".anon/extension" "igbinary.so"']

imagick¶

Class name: php::extension::imagick.

$package defaults to php5-imagick
$inifile defaults to ${php::params::config_root_ini}/imagick.ini

imap¶

Class name: php::extension::imap.

$package defaults to php5-imap
$inifile defaults to ${php::params::config_root_ini}/imap.ini

intl¶

Class name: php::extension::intl.

$package defaults to php5-intl
$inifile defaults to ${php::params::config_root_ini}/intl.ini

ldap¶

FIX ME

Class name: php::extension::ldap.

$package defaults to php5-ldap
$inifile defaults to ${php::params::config_root_ini}/ldap.ini

mcrypt¶

Class name: php::extension::mcrypt.

$package defaults to php5-mcrypt
$inifile defaults to ${php::params::config_root_ini}/mcrypt.ini

memcache¶

FIX ME

Class name: php::extension::memcache.

$package defaults to php5-memcache
$inifile defaults to ${php::params::config_root_ini}/memcache.ini

memcached¶

FIX ME

Class name: php::extension::memcached.

$package defaults to php5-memcached
$inifile defaults to ${php::params::config_root_ini}/memcached.ini

mongo¶

FIX ME

Class name: php::extension::mongo.

$package defaults to mongo
$provider defaults to pecl
$inifile defaults to ${php::params::config_root_ini}/mongo.ini

mysql¶

Class name: php::extension::mysql.

$package defaults to php5-mysql
$inifile defaults to ${php::params::config_root_ini}/mysql.ini

mysqlnd¶

Class name: php::extension::mysqlnd.

$package defaults to php5-mysqlnd
$inifile defaults to ${php::params::config_root_ini}/mysqlnd.ini

newrelic¶

Note

This extension requires the NewRelic PHP apt repository to be added beforehand.

Class name: php::extension::newrelic.

$package defaults to php5-newrelic
$inifile defaults to ${php::params::config_root_ini}/newrelic.ini

oauth¶

Class name: php::extension::oauth.

$package defaults to php5-oauth
$inifile defaults to ${php::params::config_root_ini}/oauth.ini

opcache¶

Class name: php::extension::opcache.

$package defaults to undef
$inifile defaults to ${php::params::config_root_ini}/opcache.ini

pgsql¶

Class name: php::extension::pgsql.

$package defaults to php5-pgsql
$inifile defaults to ${php::params::config_root_ini}/pgsql.ini

redis¶

Class name: php::extension::redis.

$package defaults to php5-redis
$inifile defaults to ${php::params::config_root_ini}/redis.ini

ssh2¶

Class name: php::extension::ssh2.

$package defaults to php5-ssh2
$inifile defaults to ${php::params::config_root_ini}/ssh2.ini

uploadprogress¶

Note

The package requires the build-essential and php5-dev system packages.

Class name: php::extension::uploadprogress.

$package defaults to uploadprogress
$provider defaults to pecl
$inifile defaults to ${php::params::config_root_ini}/uploadprogress.ini
$settings defaults to ['set ".anon/extension" "uploadprogress.so"']

xcache¶

FIX ME

Class name: php::extension::xcache.

$package defaults to php5-xcache
$inifile defaults to ${php::params::config_root_ini}/xcache.ini

xdebug¶

FIX ME

Class name: php::extension::xdebug.

$package defaults to php5-xdebug
$installdir defaults to /usr/lib/php5/20121212
$inifile defaults to ${php::params::config_root_ini}/xdebug.ini
$settings defaults to ["set .anon/zend_extension '${install_dir}/xdebug.so'"]

Composer¶

Easily install composer, the Dependency Manager for PHP.

Installation¶

Class name: php::composer

$source defaults to https://getcomposer.org/composer.phar
$destination defaults to /usr/local/bin/composer

Auto update¶

Automatically update composer every $max_age days

Class name: php::composer::auto_update

$max_age defaults to 30 (days)
$source defaults to https://getcomposer.org/composer.phar
$destination defaults to /usr/local/bin/composer

Examples¶

# Install with defaults
class { 'php::composer':

}

# Install with defaults + auto-update
class { ['php::composer', 'php::composer::auto_update']:

}

# Install from different source
class { 'php::composer':
  source => 'https://example.com/composer.phar'
}

# Install to different destination
class { 'php::composer':
  destination => '/usr/bin/composer'
}

phpunit¶

Install PHPunit

Installation¶

Class: php::phpunit

$ensure defaults to installed
$package defaults to pear.phpunit.de/PHPUnit
$provider defaults to pear

Examples¶

# Install with defaults
class { 'php::phpunit':

}

# Install with auto-update
class { 'php::phpunit':
  ensure => latest
}

# Install with sticky version
class { 'php::phpunit':
  ensure => '3.7.29'
}

Examples¶

Generic / CLI¶

class roles::php($version = 'installed') {

  include php
  include php::apt
  include php::params
  include php::pear
  include php::composer
  include php::composer::auto_update

  # Extensions must be installed before they are configured
  Php::Extension <| |> -> Php::Config <| |>

  # Ensure base packages is installed in the correct order
  # and before any php extensions
  Package['php5-common']
    -> Package['php5-dev']
    -> Package['php5-cli']
    -> Php::Extension <| |>

  class {
    # Base packages
    [ 'php::dev', 'php::cli' ]:
      ensure => $version;

    # PHP extensions
    [
      'php::extension::curl', 'php::extension::gd', 'php::extension::imagick',
      'php::extension::mcrypt', 'php::extension::mysql', 'php::extension::ssh2',
      'php::extension::redis', 'php::extension::http', 'php::extension::opcache'
    ]:
      ensure => $version;

    [ 'php::extension::igbinary' ]:
      ensure => installed
  }

  # Install APC user cache only (php 5.5 uses OptCache instead of APC)
  php::extension { 'php5-apcu':
    ensure    => $version,
    package   => 'php5-apcu',
    provider  => 'apt'
  }

  # Install the INTL extension
  php::extension { 'php5-intl':
    ensure    => $version,
    package   => 'php5-intl',
    provider  => 'apt'
  }

  create_resources('php::config', hiera_hash('php_config', {}))
  create_resources('php::cli::config', hiera_hash('php_cli_config', {}))

}

FPM¶

class roles::php_fpm($version = 'installed') {

  include php
  include php::apt
  include php::params

  class { 'php::fpm':
    ensure => $version,
    emergency_restart_threshold  => 5,
    emergency_restart_interval   => '1m',
    rlimit_files                 => 32768,
    events_mechanism             => 'epoll'
  }

  create_resources('php::fpm::pool',  hiera_hash('php_fpm_pool', {}))
  create_resources('php::fpm::config',  hiera_hash('php_fpm_config', {}))

  Php::Extension <| |> ~> Service['php5-fpm']

  exec { "restart-php5-fpm":
    command  => "service php5-fpm restart",
    schedule => hourly
  }

}