jump to navigation

A tour of the PHP.INI configuration file July 3, 2010

Posted by Tournas Dimitrios in PHP.

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.

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 semi-colon 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 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

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 tags:

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

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"

Activating extensions
A number of different extensions are available for PHP. On UNIX systems, extensions need to be built at compile-time; on Windows, binary DLL files are included with the PHP distributions. The extension_dir variable contains the name of the directory PHP should look in for these extensions.

extension_dir = "C:\Program Files\Internet

The Windows PHP distribution comes with over 20 different extensions, and they’re all listed (though commented out) in the php.ini file. To activate a particular extension, simply remove the semicolon at the beginning of the line and restart the server. To deactivate an extension (say, for better performance), add a semicolon to comment out the line.

If the extension is not listed in the file, use the extension variable, and pass it the file name of the corresponding DLL.

Setting extension-specific variables

Extension-specific variables are stored in separate sections of the configuration file. For example, all the variables related to the MySQL extension should be in the [MySQL] section of the php.ini file.
If you’re going to use PHP’s mail() function, there are three variables you may need to set. The SMTP and sendmail_from variables (on Windows) or the sendmail_path variable (on UNIX) are used when sending e-mail messages through PHP’s mail() function. On Windows, these variables set the SMTP server to be used and the From: address to display in e-mail messages; on UNIX, the sendmail_path variable sets the path of the MTA (mail transfer agent) for mail delivery:

SMTP = myserver.localnet.com
sendmail_from = me@localhost.com
sendmail_path = /usr/sbin/sendmail

The java.class.path, java.home, java.library and java.library.path variables all set the directories to look in for Java classes and libraries. These values are used by the Java extension, so make sure you set them correctly if you want PHP to integrate correctly with your Java applications:

java.class.path = .\php_java.jar
java.home = c:\jdk
java.library = c:\jdk\jre\bin\hotspot\jvm.dll
java.library.path = .\

The session.save_path variable specifies the temporary directory for session information. Normally, this defaults to /tmp, but since this directory does not exist on Windows systems, you must reset it to the appropriate Windows temporary directory or else the session handler will pop up unsightly error messages whenever you call session_start(). You can also control how long a session cookie remains valid, in seconds, with the session.cookie_lifetime variable:

session.save_path = c:\windows\temp
session.cookie_lifetime = 1800

Security settings

There are a number of variables in php.ini related to the security of your PHP installation. The most interesting of these is the safe_mode variable, recommended for ISPs and shared-hosting services as it limits the things a user can do with PHP:

safe_mode = Off

With safe mode turned on, you can specify which directories are searched for files with the safe_mode_include_dir variable. You can also restrict the types of programs a PHP script can run with the exec() command by placing the program binaries in a special directory and telling PHP about it via the safe_mode_include_dir variable. Only binaries in this directory will be accessible via exec():

safe_mode_include_dir = /usr/local/lib/php/safe-include
safe_mode_exec_dir = /usr/local/lib/php/safe-bin

You can restrict file operations with the open_basedir variable, which sets the named directory as the root for file operations. When this value is set, files outside the named directory tree will be inaccessible to PHP. This is a good way to restrict a shared system’s users to their own home or Web directories:

open_basedir = /home/web/

The max_execution_time variable sets the maximum number of seconds PHP will wait for a script to finish executing before forcibly terminating it. This comes in handy when your script spirals into an infinite loop. However it can trip you up if you have a legitimate activity that takes time to complete—for example, a large file upload. In such situations you should consider increasing this value to avoid having PHP shut down your script when it’s in the middle of something important.

max_execution_time = 90

Configuring file uploads and form variables

If the security configurations we discussed earlier aren’t enough, you can secure your system even further by either turning off file uploads, through the file_uploads variable, or by setting a limit on the maximum size of an upload with upload_max_filesize. Generally you’ll want to set a fairly small file size unless you have an application that is designed to accept files, such as an image gallery or a Web-based FTP service:

file_uploads = On
upload_max_filesize = 2M

If you’re not interested in uploading files but use a lot of forms in your PHP application, there are two variables that will be of particular interest to you—first, the register_globals variable, the cause of much heartache to longtime PHP developers. In PHP 3.x, this variable was On by default, leading form variables to be automatically converted to PHP variables when a form was submitted.
Security concerns led to this variable being set to Off in PHP 4.x. As a result, form variables could only be accessed through the special $_GET and $_POST arrays. This broke many scripts written in PHP 3.x, and forced developers to rewrite and retest their scripts. For example, the value entered into the field would be available as $email in a PHP 3.x script, but as $_POST[’email’] or $_GET[’email’] in a PHP 4.x script.
You should generally set this variable to Off, as that offers greater security against script attacks through forms. For compatibility with older PHP 3.x scripts, turn it On:

register_globals = Off

Also related to form submission is the post_max_size variable, which controls the maximum amount of data that PHP will accept in a single form submission with the POST method. It’s unlikely you’ll ever need to increase this from the default value of 8 MB; instead, you should probably reduce it to a more realistic figure. However, if you’re planning on using the file upload features of PHP, keep this value greater than the value of upload_max_filesize.

post_max_size = 8M

New in PHP 5 is the max_input_time variable, which sets a time limit in seconds for receiving input data through POST, GET, and PUT. If your application is running over a slow link, it is sometimes worthwhile to explore increasing this value to allow the script more time to receive input data.

max_input_time = 90

Tweaking performance
There are even some values you can tweak to improve the performance of the PHP interpreter. In order to avoid runaway scripts using up all the available memory on the system, PHP allows you to define limits on memory usage. This value is set via the memory_limit variable, and it specifies the maximum memory a single script may use:

memory_limit = 8M

The memory_limit value should generally be higher than the value of post_max_size.
Another thing you can do to improve performance is disable the $argc and $argv variables, which store the number of arguments passed to an application on the command line as well as the actual argument values.

register_argc_argv = false

Similarly, disable the $HTTP_GET_VARS and $HTTP_POST_VARS arrays, since you’re unlikely to use them in the modern world of $_GET and $_POST. Disabling these features can improve performance, but is only available in PHP 5 via the register_long_arrays variable.

register_long_arrays = false

The ini_set() function
Finally, a note on the ini_set() function. While PHP reads all its settings at startup from the php.ini configuration file, it also lets you override those settings on a per-script basis with the very cool ini_set() function. This function accepts two arguments: the name of the configuration variable to alter, and its new value. Here is an example, which increases the maximum execution time for the script in which it appears:

ini_set('max_execution_time', 600);
// more code

The setting only affects the script in which it is set. Once the script has completed executing, the original value of the variable is restored automatically.
If your PHP applications are running on a shared server, it’s unlikely that you will have access to the master php.ini configuration file. The ini_set() function can help significantly by allowing you to reconfigure PHP on the fly for your special needs.
View latest official php.ini


No comments yet — be the first.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s