<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-type" content="text/html; charset=utf-8" />
<meta http-equiv="Content-Language" content="en-us" />
<meta name="ROBOTS" content="ALL" />
<meta http-equiv="imagetoolbar" content="no" />
<meta name="MSSmartTagsPreventParsing" content="true" />
<meta name="Keywords" content="cherokee web server httpd http" />
<meta name="Description" content="Cherokee is a flexible, very fast, lightweight Web server. It is implemented entirely in C, and has no dependencies beyond a standard C library. It is embeddable and extensible with plug-ins. It supports on-the-fly configuration by reading files or strings, TLS/SSL (via GNUTLS or OpenSSL), virtual hosts, authentication, cache friendly features, PHP, custom error management, and much more." />
<link href="media/css/cherokee_doc.css" rel="stylesheet" type="text/css" media="all" />
</head>
<body>
<h2 id="_a_href_index_html_index_a_8594_a_href_cookbook_html_cookbook_a"><a href="index.html">Index</a> → <a href="cookbook.html">Cookbook</a></h2>
<div class="sectionbody">
</div>
<h2 id="_cookbook_setting_up_php">Cookbook: Setting up PHP</h2>
<div class="sectionbody">
<div class="paragraph"><p>There is not much to learn to configure PHP with Cherokee.
Cherokee-admin ships a one-click wizard that will do everything for
you. It will look for the PHP interpreter, it will check whether it
support FastCGI, and then it’ll perform all the necessary operations
to set it up on Cherokee. It is a piece of cake.</p></div>
<div class="paragraph"><p>If PHP-fpm binaries are found, those will be prioritized over the
regular binaries.</p></div>
<div class="paragraph"><p>There is also a
<a href="http://www.cherokee-project.com/screencasts.html#php">screencast</a>
available at the
<a href="http://www.cherokee-project.com/">Cherokee-Project website</a> to
demonstrate how easy it is to use the PHP wizard.</p></div>
<div class="paragraph"><p><span class="image">
<a class="image" href="http://www.cherokee-project.com/screencasts.html#php">
<img src="media/images/screencast.png" alt="media/images/screencast.png" />
</a>
</span></p></div>
<div class="paragraph"><p>It requires a single operation to get PHP configured on a pre-existing
Virtual Server: Choose the virtual server your want to configure, and
click on the <tt>Behavior</tt> tab and trigger the <tt>Rule panel</tt> by clicking
on the <tt>Rule Management</tt> button. Once in there, use the <tt>Add</tt> button
at the top of the panel to see the available wizards.</p></div>
<div class="imageblock">
<div class="content">
<img src="media/images/admin_vserver_wizard.png" alt="media/images/admin_vserver_wizard.png" />
</div>
<div class="image-title">Wizards</div>
</div>
<div class="paragraph"><p>Now select <tt>Languages</tt> and run the PHP wizard. And, that’s it. If you
had <tt>php-fpm</tt> or <tt>php-cgi</tt> installed in your system, PHP should be
configured now.</p></div>
<h3 id="php_fastcgi">PHP FastCGI support</h3><div style="clear:left"></div>
<div class="paragraph"><p>Note that only FastCGI-enabled binaries of PHP will work with the
FastCGI handler. Many prepackaged versions already enable this by
default. If yours does not, you will need to build a suitable
binary. You can check this with the <tt>-v</tt> parameter:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>$ php-cgi -v
PHP 5.2.10 (cgi-fcgi) (built: Jul 11 2009 15:33:11)
Copyright (c) 1997-2009 The PHP Group
Zend Engine v2.2.0, Copyright (c) 1998-2009 Zend Technologies</tt></pre>
</div></div>
<div class="paragraph"><p>You cannot proceed unless the <strong>"cgi-fcgi"</strong> string is present.</p></div>
<h3 id="php_env">PHP process Environment Variables</h3><div style="clear:left"></div>
<div class="paragraph"><p>To specify Environment Variables at the Information Source level
be sure to uncheck <strong>Inherit Environment</strong>. This will display the
form to enter variables and values.</p></div>
<div class="paragraph"><p>The <strong>PHP_FCGI_CHILDREN</strong> environment variable is mandatory for PHP
FastCGI servers. It defines how much children should serve the
requests coming from the webserver.</p></div>
<div class="paragraph"><p>If you define <strong>PHP_FCGI_MAX_REQUESTS</strong>, the value must be negative if
you do not want the PHP process to ever be restarted. If you leave it
unset, PHP will take the default value (500), after which it will be
restarted. It is generally a good idea to let PHP be restarted to free
up resources and possible memory leaks.</p></div>
<h3 id="advanced">Advanced configuration</h3><div style="clear:left"></div>
<div class="paragraph"><p>Once PHP is configured, you are free to tweak the configuration to
adapt it to your specific needs. You may want to change some of the
php-cgi parameters, or even point Cherokee to use distributed PHP
execution.</p></div>
<div class="paragraph"><p>This example shows a typical usage of FastCGI. It only uses one
<a href="config_info_sources.html">information source</a> nicknamed <tt>php</tt> in
this case. This connects to a FastCGI server located in localhost in
port 47990. If no server is running, the webserver will run the
FastCGI server by issuing the command defined as the <strong>Interpreter</strong>
sub-parameter of the information source that is being accessed.</p></div>
<div class="imageblock">
<div class="content">
<img src="media/images/admin_handler_fastcgi1.png" alt="media/images/admin_handler_fastcgi1.png" />
</div>
<div class="image-title">FastCGI rule sample</div>
</div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Common CGI options in FastCGI rule</caption>
<col width="50%" />
<col width="50%" />
<thead>
<tr>
<th align="left" valign="top">Checkbox </th>
<th align="left" valign="top"> Value</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">Error Handler</p></td>
<td align="left" valign="top"><p class="table">Checked</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Check file</p></td>
<td align="left" valign="top"><p class="table">Checked</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Pass request</p></td>
<td align="left" valign="top"><p class="table">Checked</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">Allow XSendfile</p></td>
<td align="left" valign="top"><p class="table">Unchecked</p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>This other example shows a typical usage of multiple FastCGI servers.
It connects to FastCGI servers in several locations. If no server is
running in the local computer, the webserver will run the FastCGI
server by issuing the specified command. Note that for <strong>remote</strong>
FastCGI servers, you are responsible for running the FastCGI services
there manually.</p></div>
<div class="imageblock">
<div class="content">
<img src="media/images/admin_handler_fastcgi2.png" alt="media/images/admin_handler_fastcgi2.png" />
</div>
<div class="image-title">Load balancing among information sources</div>
</div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<caption class="title">Load balancing among information sources</caption>
<col width="50%" />
<col width="50%" />
<thead>
<tr>
<th align="left" valign="top">Nick </th>
<th align="left" valign="top"> Host</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">PHP interpreter</p></td>
<td align="left" valign="top"><p class="table">localhost:47990</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">PHP interpreter 2</p></td>
<td align="left" valign="top"><p class="table">php2.cluster:47990</p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">PHP interpreter 3</p></td>
<td align="left" valign="top"><p class="table">php3.cluster:47990</p></td>
</tr>
</tbody>
</table>
</div>
<h3 id="multi-site">Multi-site support</h3><div style="clear:left"></div>
<div class="paragraph"><p>An even more advanced scenario would be one that required custom PHP
settings for each virtual host.</p></div>
<div class="paragraph"><p>In such a scenario several information sources are required. Some
settings can be set simply by providing ENV variables to customize the
FastCGI behavior. Others can only be specified in the <tt>php.ini</tt>
configuration file, which is read by <tt>php-cgi</tt> on start-up.</p></div>
<div class="paragraph"><p>The location of this file is platform dependent, so you will need to
refer to PHP’s documentation. It is the file located in
<em>/etc/php5/cgi/php.ini</em> on Debian/Ubuntu systems,
<em>/opt/local/etc/php5/php.ini</em> on MacPorts, etc.</p></div>
<h4 id="_php_configuration_file">PHP configuration file</h4>
<div class="paragraph"><p>You will have to customize and specify different <tt>php.ini</tt> files for
each information source. A nifty trick to do this and provide custom
environment variables is by wrapping the required parameters in a
simple script such as this one:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>#!/bin/sh
export PHP_FCGI_MAX_REQUESTS=250
export PHP_FCGI_CHILDREN=4
exec /usr/local/bin/php-cgi $@
# EOF</tt></pre>
</div></div>
<div class="paragraph"><p>It just calls the real <tt>php-cgi</tt> with the ENV variables to customize the
FastCGI behavior, passing the parameters along. The same wrapper can
be used for every information source, providing a different <tt>-c
path/php.ini</tt> for each one of them.</p></div>
<div class="paragraph"><p>Bare in mind that every information source will need its own port to
run.</p></div>
<div class="paragraph"><p>Assuming that two customized information sources were required, simply
specifying different interpreters for each one of them would suffice.</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="10%" />
<col width="90%" />
<thead>
<tr>
<th align="left" valign="top">VHost </th>
<th align="left" valign="top"> Interpreter</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">1</p></td>
<td align="left" valign="top"><p class="table"><tt>/usr/local/bin/php-cgi -c /usr/local/etc/php/php-vhost1.ini -b 127.0.0.1:2998</tt></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">2</p></td>
<td align="left" valign="top"><p class="table"><tt>/usr/local/bin/php-cgi -c /usr/local/etc/php/php-vhost2.ini -b 127.0.0.1:2999</tt></p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>This, in turn, would produce configuration entries similar to the
following ones:</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>source!1!nick = php-vhost1
source!1!interpreter = /usr/local/bin/php-cgi -c /usr/local/etc/php/php-vhost1.ini -b 127.0.0.1:2998
...
source!2!nick = php-vhost2
source!2!interpreter = /usr/local/bin/php-cgi -c /usr/local/etc/php/php-vhost2.ini -b 127.0.0.1:2999</tt></pre>
</div></div>
<h4 id="_php_configuration_variables">PHP configuration variables</h4>
<div class="paragraph"><p>The variables specified in <tt>php.ini</tt> can also be overridden setting a
custom environment variable on a per-virtual-server basis.</p></div>
<div class="paragraph"><p>Just access the PHP rule of your virtual server, <tt>Extensions php</tt>, and
select the <tt>Handler</tt> tab to be able to set a custom environment
variable for the <tt>FastCGI</tt> handler.</p></div>
<div class="paragraph"><p>You will need to provide the values in the following format:</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="50%" />
<col width="50%" />
<thead>
<tr>
<th align="left" valign="top">Name </th>
<th align="left" valign="top"> Value</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">PHP_ADMIN_VALUE</p></td>
<td align="left" valign="top"><p class="table"><tt>memory_limit=128M</tt></p></td>
</tr>
</tbody>
</table>
</div>
<div class="paragraph"><p>This will set the memory limit for the virtual server only. Any
<tt>php.ini</tt> variable can be set using this procedure.</p></div>
<div class="paragraph"><p>Also, it is possible to manually specify every <tt>php.ini</tt> as a
parameter of the interpreter thanks to the <tt>-d</tt> argument of
PHP. Assuming you had to separate virtual servers, each with its own
PHP information source, you could customize each of them directly
editing the information source. This example would specify different
memory limits for both information sources.</p></div>
<div class="tableblock">
<table rules="all"
width="100%"
frame="border"
cellspacing="0" cellpadding="4">
<col width="10%" />
<col width="90%" />
<thead>
<tr>
<th align="left" valign="top">VHost </th>
<th align="left" valign="top"> Interpreter</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left" valign="top"><p class="table">1</p></td>
<td align="left" valign="top"><p class="table"><tt>/usr/local/bin/php-cgi -d memory_limit=256M -b 127.0.0.1:2998</tt></p></td>
</tr>
<tr>
<td align="left" valign="top"><p class="table">2</p></td>
<td align="left" valign="top"><p class="table"><tt>/usr/local/bin/php-cgi -d memory_limit=32M -b 127.0.0.1:2999</tt></p></td>
</tr>
</tbody>
</table>
</div>
<h3 id="upload_limits">PHP upload limits</h3><div style="clear:left"></div>
<div class="paragraph"><p>Every now and then this issue pops up: an HTTP error 400 appears
repeatedly when uploading files to a PHP back-end.</p></div>
<div class="paragraph"><p>PHP has several limits in-place which can be configured through its
<tt>php.ini</tt> configuration file.</p></div>
<div class="paragraph"><p>Two entries are related to this issue. Tweak them according to your
necessities. In this example, we are rising the limit to 200MB.</p></div>
<div class="listingblock">
<div class="content">
<pre><tt>; Maximum size of POST data that PHP will accept.
post_max_size = 200M
; Maximum allowed size for uploaded files.
upload_max_filesize = 200M</tt></pre>
</div></div>
</div>
<div id="footer">
<div id="footer-text">
</div>
</div>
</body>
</html>
