A tour of the PHP.INI configuration file, part 1

Learn to edit the php.ini file to suit your needs. This configuration file lets you alter many aspects of PHP's behavior, including setting file paths and directories, changing session and database parameters, and activating extensions.

You don't often need to fiddle with PHP's settings—the language usually works fine with its out-of-the-box configuration. But the creators of PHP, being developers themselves, were well aware that users might occasionally need to tweak the language's behavior for specialized applications. That's why they exposed a number of PHP's variables through a configuration file, called php.ini. This configuration file allows you to alter many aspects of PHP's behavior, including setting file paths and directories, changing session and database parameters, and activating extensions.

Editor's Note

"A tour of the PHP.INI configuration file, part 2" will publish July 22, 2004.

The PHP configuration file

Before beginning with the tour, a quick note on how PHP's configuration file is structured. This file is named php.ini for a reason—it follows the INI file structure popular in many Windows applications. It's an ASCII text file is broken into named sections, each containing variables related to that section. Each section looks something like this:


The section name is in square braces at the top, followed by any number of name-value pairs, with each pair on a separate line. As with regular PHP code, variable names are case sensitive and cannot contain spaces, while the values may be numeric, string, or Boolean.

Semicolons placed at the beginning of a line serve as comment markers. This makes it easy to enable or disable PHP features; rather than deleting a line, you can comment it out so that it isn't parsed. This is handy if you think you might want to re-enable a feature at a later date, you don't have to delete it out of the file.

In order for PHP to recognize it, the php.ini file must be located either in the current directory, the directory defined in the $PHPRC environment variable, or the directory specified at compile time (for Windows PHP, this is the main Windows directory).

After making changes to PHP's configuration through the php.ini file, you'll need to restart the Web server for your changes to take effect (assuming, of course, that you're using PHP through the Web server). For command-line usage of PHP, the configuration file will be read every time you invoke the PHP binary program.

Setting parser options

The first stop on this tour is also one of the more important ones: options related to the language interpreter. The first item here is the engine variable, which controls whether the PHP engine should be "on" or "off". Turning the engine off means that embedded PHP code will not be parsed by the Web server. It doesn't usually make sense to do this, so leave it on.

engine = On

The short_open_tag variable controls whether the parser should recognize the shortcut <?...?> tags, as well as the standard <?php...?> tags. Turn this off if you anticipate conflicts with other languages, or if you want to apply strict syntactical rules to your PHP code.

short_open_tag = On

Normally, session, cookie or HTTP header data in a PHP script must be sent before any output is generated by the script. If this is not possible in your application, you can enable what PHP calls output buffering, with the output_buffering variable.

With output buffering on, PHP stores the output of your script in a special memory buffer and sends it only when explicitly told to do so. This allows you to send special HTTP headers and cookie data even in the middle or at the end of your script; however, it can degrade performance marginally.

output_buffering = Off

You can also pass the output_buffering variable a number indicating the size of the buffer, for example:

output_buffering = 2048

When PHP starts up, it adds a message stating its version number to the Web server's standard header. To turn this off, set the expose_php variable to false. This is useful if, for example, you want to mask the capabilities of your Web server from potential hackers.

expose_php = On

Now let's look at how to set the search path and handle errors.

Setting the PHP search path

You can set a search path for PHP with the include_path variable, which accepts a list of directories. PHP will automatically check these directories when it encounters references to files without a path prefix.

If you have function libraries or classes that you use frequently, list their locations here to simplify file lookups. This is also a good place to add the path to PHP's PEAR directory, which contains many reusable classes.

include_path = ".:/usr/local/lib/php/pear:"

Windows users can specify multiple locations by separating them with semicolons; UNIX users must use colons instead.

Two interesting variables in this context are auto_prepend_file and auto_append_file. These variables specify files that PHP automatically appends to the beginning or end of any PHP document. This is mostly used to append a header or footer to pages generated in PHP, saving you a few lines of code in each PHP document you write. The downside is that the files specified here will be appended to *all* PHP documents, so these variables are best suited for single-application servers.

The files may be either PHP scripts or regular HTML documents. Embedded PHP code must be surrounded by the standard <?php...?> tags:

auto_prepend_file = /home/web/includes/header.php
auto_append_file = /home/web/includes/legal.php

Handling errors

PHP errors fall into four categories: parsing errors, notices about code bugs such as uninitialized variables, warnings (aka non-fatal errors), and fatal errors. Normally, when PHP encounters either a parsing, non-fatal or fatal error, it displays the error and—if the error is fatal—also stops script processing at that point. You can alter this behavior with the error_reporting variable, which accepts a bitfield of error codes and only displays errors matching those codes.

error_reporting =  E_ALL

To turn off the display of errors—recommended in production code—set the display_errors variable to false, and instead write the messages to an error log with the log_errors variable.

Doing this is good for security too—by turning off errors, you hide system-specific information that unscrupulous users could use to try and damage your site or application. You should instead write these errors to a custom log file or to the system logger, by setting the error_log variable to either a file name or the special value "syslog". Remember to check these log files regularly to keep an eye on what's happening inside your application.

display_errors = Off
log_errors = On
error_log = "error.log"

Come back Thursday (July 22) for the second part of this tutorial. I'll take you deeper into the php.ini file, showing you the settings to configure file uploads and form parsing, run PHP in restricted mode for greater security, activate extensions, set resource limits for memory usage, and disable legacy features for better performance.