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 toinstalled
.$package
default depends on SAPI.$provider`
default toundef
.$inifile
default depends on SAPI.$settings
defaults to[ ]
(empty array).
php::apache¶
Installs the mod_php
PHP SAPI for apache.
$package
defaults tolibapache2-mod-php5
.$inifile
defaults to/etc/php5/apache2/php.ini
.$service_name
defaults toapache2
.
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 tophp5-fpm
.$inifile
defaults to/etc/php5/fpm/php.ini
.$service_name
defaults tophp5-fpm
.$service_ensure
defaults torunning
.$service_enable
defaults totrue
.$service_has_status
defaults totrue
.
php::cli¶
Installs the CLI
PHP SAPI.
$package
defaults tophp5-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 toinstalled
.$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 tophp-apc
for Squeeze, Wheezy, Lucid, Precise, Quantal and Raring. Other OS versions will default tophp5-apcu
.$inifile
defaults to${php::params::config_root_ini}/apc.ini
apcu¶
Class name: php::extension::apcu
.
$package
defaults tophp5-apcu
$inifile
defaults to${php::params::config_root_ini}/apcu.ini
curl¶
Class name: php::extension::curl
.
$package
defaults tophp5-curl
$inifile
defaults to${php::params::config_root_ini}/curl.ini
gd¶
Class name: php::extension::gd
.
$package
defaults tophp5-gd
$inifile
defaults to${php::params::config_root_ini}/gd.ini
gearman¶
Class name: php::extension::gearman
.
$package
defaults tophp5-gearman
$inifile
defaults to${php::params::config_root_ini}/gearman.ini
http¶
Class name: php::extension::http
.
$package
defaults tophp5-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 toigbinary
$provider
defaults topecl
$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 tophp5-imagick
$inifile
defaults to${php::params::config_root_ini}/imagick.ini
imap¶
Class name: php::extension::imap
.
$package
defaults tophp5-imap
$inifile
defaults to${php::params::config_root_ini}/imap.ini
intl¶
Class name: php::extension::intl
.
$package
defaults tophp5-intl
$inifile
defaults to${php::params::config_root_ini}/intl.ini
ldap¶
FIX ME
Class name: php::extension::ldap
.
$package
defaults tophp5-ldap
$inifile
defaults to${php::params::config_root_ini}/ldap.ini
mcrypt¶
Class name: php::extension::mcrypt
.
$package
defaults tophp5-mcrypt
$inifile
defaults to${php::params::config_root_ini}/mcrypt.ini
memcache¶
FIX ME
Class name: php::extension::memcache
.
$package
defaults tophp5-memcache
$inifile
defaults to${php::params::config_root_ini}/memcache.ini
memcached¶
FIX ME
Class name: php::extension::memcached
.
$package
defaults tophp5-memcached
$inifile
defaults to${php::params::config_root_ini}/memcached.ini
mongo¶
FIX ME
Class name: php::extension::mongo
.
$package
defaults tomongo
$provider
defaults topecl
$inifile
defaults to${php::params::config_root_ini}/mongo.ini
mysql¶
Class name: php::extension::mysql
.
$package
defaults tophp5-mysql
$inifile
defaults to${php::params::config_root_ini}/mysql.ini
mysqlnd¶
Class name: php::extension::mysqlnd
.
$package
defaults tophp5-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 tophp5-newrelic
$inifile
defaults to${php::params::config_root_ini}/newrelic.ini
oauth¶
Class name: php::extension::oauth
.
$package
defaults tophp5-oauth
$inifile
defaults to${php::params::config_root_ini}/oauth.ini
opcache¶
Class name: php::extension::opcache
.
$package
defaults toundef
$inifile
defaults to${php::params::config_root_ini}/opcache.ini
pgsql¶
Class name: php::extension::pgsql
.
$package
defaults tophp5-pgsql
$inifile
defaults to${php::params::config_root_ini}/pgsql.ini
redis¶
Class name: php::extension::redis
.
$package
defaults tophp5-redis
$inifile
defaults to${php::params::config_root_ini}/redis.ini
ssh2¶
Class name: php::extension::ssh2
.
$package
defaults tophp5-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 touploadprogress
$provider
defaults topecl
$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 tophp5-xcache
$inifile
defaults to${php::params::config_root_ini}/xcache.ini
xdebug¶
FIX ME
Class name: php::extension::xdebug
.
$package
defaults tophp5-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 tohttps://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 to30
(days)$source
defaults tohttps://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 toinstalled
$package
defaults topear.phpunit.de/PHPUnit
$provider
defaults topear
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
}
}