PHP ini

The PHP configuration file

php.ini 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:

[MySection]
variable="value"
anothervariable="anothervalue"

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

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

.

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, 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 Tools\Apache\bin\php4\extensions"

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:

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:

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:

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:

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():

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:

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.

If the you think security configurations 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:

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 <input type="text" name="email"> 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:

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 .

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.

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:

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.

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.

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:

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.