A.5 Modifying PHP Configuration Directives

Earlier chapters in the book mention various PHP configuration directives. These are settings that affect the behavior of the PHP interpreter, such as how errors are reported, where the PHP interpreter looks for included files and extensions, and much more.

Read this section when you encounter a configuration directive you want to alter or are curious as to how you can tweak the PHP interpreter's settings (whether you are using PHP on your own computer or with a hosting provider). For example, changing the output_buffering directive (as discussed in Section 8.6) makes your life much easier if you are working with cookies and sessions.

The values of configuration directives can be changed in a few places: in the PHP interpreter's php.ini configuration file, in Apache's httpd.conf or .htaccess configuration files, and in your PHP programs. Not all configuration directives can be changed in all places. If you can edit your php.ini or httpd.conf file, it's easiest to set PHP configuration directives there. But if you can't change those files because of server permissions, then you can still change some settings in your PHP programs.

The php.ini file holds system-wide configuration for the PHP interpreter. When the web server process starts up, the PHP interpreter reads the php.ini file and adjusts its configuration accordingly. To find the location of your system's php.ini file, examine the output from the phpinfo( ) function. This function prints a report of the PHP interpreter's configuration. The tiny program in Example A-3 produces a page that looks like the one in Figure A-21.

Figure A-21. Output of phpinfo( )

Example A-3. Getting configuration details with phpinfo( )

<?php phpinfo( ); ?>

In Figure A-21, the sixth line (Configuration File (php.ini) Path) shows that the php.ini file is /usr/local/lib/php.ini. Your php.ini file may be in a different place.

In the php.ini file, lines that begin with a semicolon (;) are comments. Lines that set values for configuration directives look like those shown in Example A-4.

Example A-4. Sample lines in php.ini

; How to specify directories on Unix: forward slash for a separator
; and a colon between the directory names
include_path = ".:/usr/local/lib/php/includes"

; How to specify directories on Windows: backslash for a separator
; and a semicolon between the directory names
; Windows: "\path1;\path2"
include_path = ".;c:\php\includes"

; Report all errors but notices and coding standards violations
error_reporting = E_ALL & ~E_STRICT

; Record errors in the error log
log_errors = On

; Don't automatically create variables from form data
register_globals = Off

; An uploaded file can't be more than 2 megabytes
upload_max_filesize = 2M

; Sessions expire after 1440 seconds
session.gc_maxlifetime = 1440

The error_reporting configuration directive is set by combining built-in constants with logical operators. For example, the line error_reporting = E_ALL & ~E_STRICT sets error_reporting to E_ALL but not E_STRICT. The operators you can use are & ("and"), | ("either ... or"), and ~ ("not"). So, to the PHP interpreter, E_ALL & ~E_STRICT means E_ALL and not E_STRICT. You may find it easier to read "and not" as "but not," as in E_ALL but not E_STRICT. The setting E_ALL | E_STRICT means either E_ALL or E_STRICT.

When setting a configuration directive whose value is a number (such as upload_max_filesize), you can use M or K at the end of the number to multiply by 1,048,576 or 1,024. Setting upload_max_filesize = 2M is the same as setting upload_max_filesize = 2097152. There are 1,048,576 bytes in a megabyte, and 2,097,152 = 2 * 1,048,576.

To change a configuration directive in Apache's httpd.conf or .htaccess file, you must use a slightly different syntax, shown in Example A-5.

Example A-5. Sample PHP configuration lines in httpd.conf

; How to specify directories on Unix: forward slash for a separator
; and a colon between the directory names
php_value include_path ".:/usr/local/lib/php/includes"

; How to specify directories on Windows: backslash for a separator
; and a semicolon between the directory names
; Windows: "\path1;\path2"
php_value include_path ".;c:\php\includes"

; Report all errors but notices and coding standards violations
php_value error_reporting "E_ALL & ~E_STRICT"

; Record errors in the error log
php_flag log_errors On

; Don't automatically create variables from form data
php_flag register_globals Off

; An uploaded file can't be more than 2 megabytes
php_value upload_max_filesize 2M

; Sessions expire after 1440 seconds
php_value session.gc_maxlifetime 1440

The php_flag and php_value words in Example A-5 tell Apache that the rest of the line is a PHP configuration directive. After php_flag, put the name of the configuration directive and then On or Off. After php_value, put the name of the directive and then its value. If the value has spaces in it (such as E_ALL & ~E_STRICT), you must put it in quotes. There is no equals sign between the name of the configuration directive and the value.

To change a configuration directive from within a PHP program, use the ini_set( ) function. Example A-6 sets error_reporting from within a PHP program.

Example A-6. Changing a configuration directive with ini_set( )

ini_set('error_reporting',E_ALL & ~E_STRICT);

The first argument to ini_set( ) is the name of the configuration directive to set. The second argument is the value to which you want to set the configuration directive. For error_reporting, that value is the same logical expression as you'd put in php.ini. For configuration directives whose values are strings or integers, pass the string or integer to ini_set( ). For configuration directives whose value is On or Off, pass 1 (for On) or 0 (for Off) to ini_set( ).

To find the value of a configuration directive from within a program, use ini_get( ). Pass it the name of the configuration directive, and it returns the value. This is useful for adding a directory onto the include_path, as shown in Example A-7.

Example A-7. Changing include_path with ini_get( ) and ini_set( )

// These lines add /home/ireneo/php to the end of the include_path
$include_path = ini_get('include_path');
ini_set('include_path',$include_path . ':/home/ireneo/php');

As mentioned earlier, not all configuration directives can be set in all places. There are some configuration directives that cannot be set from within your PHP programs. These are directives that the PHP interpreter must know about before it starts reading your program, such as output_buffering. The output_buffering directive makes a change to the interpreter's behavior that must be active before the interpreter gets a look at your program, so you can't set output_buffering with ini_set( ). In addition, some configuration directives are prohibited from being set in Apache .htaccess files and some from being set in the Apache httpd.conf file. All configuration directives can be set in the php.ini file.

The PHP Manual entry for ini_set( ) (http://www.php.net/ini_set) contains a table describing which configuration directives can be set in which places.

Some useful configuration directives to know about are listed in Table A-1.

Table A-1. Useful configuration directives

Directive	Recommended value	Description
allow_url_fopen	On	Whether to allow functions such as file_get_contents( ) to work with URLs in addition to local files.
auto_append_file		Set this to a filename to have the PHP code in that file run after the PHP interpreter runs a program. This is useful for printing out a common page footer.
auto_prepend_file		Set this to a filename to have the PHP code in that file run before the PHP interpreter runs a program. This is useful for defining functions or including files that you use on your entire site.
browscap		Set this to the filename of a browser capabilities file. See Section 13.4.
display_errors	On for debugging, Off for production	When this is on, the PHP interpreter prints errors as part of your program output.
error_reporting	E_ALL	This controls what kinds of errors the PHP interpreter reports. See Section 12.1.
extension		Each extension line in php.ini loads a PHP extension. The extension library must be present on your system to load it.
extension_dir		What directory the PHP interpreter looks in to find extensions specified by the extension directive.
file_uploads	On	Whether to allow file uploads via forms.
include_path		A list of directories that the PHP interpreter looks for files loaded via include, require, include_once, and require_once.
log_errors	On	When this is on, the PHP interpreter puts program errors in the web server error log.
magic_quotes_gpc	Off	When this is on, the PHP interpreter automatically escapes submitted form data to prepare it for inclusion in an SQL query. See the Warning in Chapter 7 in Section 7.5.
magic_quotes_runtime	Off	When this is on, the PHP interpreter automatically escapes data read from an external file to prepare it for inclusion in an SQL query.
output_buffering	On	When this is on, the PHP interpreter waits until your script runs before it sends HTTP headers, making it easier to use cookies and sessions. See Section 8.6 in Chapter 8.
register_globals	Off	When this is on, the PHP interpreter creates individual variables for each submitted form or URL variable. For example, the global variable dinner would contain the value of the submitted form parameter dinner. Turning this on opens your PHP programs up to lots of security risks. Do not turn this on.
session.auto_start	On (if you're using sessions)	When this is on, the PHP interpreter starts a session at the beginning of each page, so you don't have to call session_start( ).
session.gc_maxlifetime	1440	The number of seconds that a session should last. The default value of 1440 is fine for most applications.
session.gc_probability	1	The likelihood (out of 100) that expired sessions are cleaned up at the beginning of any request. The default value of 1 is fine for most applications.
SMTP		This directive is only used on Windows. It is the hostname of an SMTP server that should be used to send messages when you call the mail( ) function.
short_open_tag	Off	When this directive is on, you can start a PHP block with <? as well as <?php. Since not all servers are configured to accept short tags, it's good practice to leave this off and always use the <?php start tag.
track_errors	On for debugging, Off for production	When this is on, the PHP interpreter stores an error message in the global variable $php_errormsg when it encounters a problem. See Section 10.6.
upload_max_filesize	2M	The maximum permitted size for an file uploaded via a form. Unless you are building an application that requires users to upload very large files, don't increase this value. Lots of large uploaded files can clog your server.