PHP installing configuring testing examples - php.ini
After installing PHP, the next step would be configuring its many options. In order to do this,
you must edit the configuration file, which should be called “php.ini”. PHP reads this file when it starts,
so you shouldn’t expect your changes to apply as soon as you’ve modified the file, you have to restart the web-server
after you’ve changed PHP’s configuration file!
The configuration file is not provided with PHP; instead, there are two templates which should help you
decide on PHP settings: a development purposes template “php.ini-dist” - and a production site template
“php.ini-recommended”. If no configuration file is used, then PHP will use the factory settings.
If you intend to use PHP for learning and development, you should definitely use the first template.
If you will use PHP for production purposes, you should go with the second template. This second one makes PHP more
efficient and more secure. Unfortunately, this way of improving PHP’s performance may make it incompatible with some applications,
and may prove to be difficult to develop with. So go ahead and choose the one it suits you best, and then copy it under the name
“php.ini” in its intended location - you can find out where PHP looks for its configuration file if you read the documentation.
The locations of the configuration file may differ for each platform, so, for example, on UNIX-systems you should place it in “/usr/local/lib/”;
on a Windows system, the default location is the Windows directory. A “php.ini” file in the current working directory will override one
in the default location, so it’s easy to change the behavior of PHP on a per-directory basis.
The configuration file is fully commented, so you can go over each one setting and see the effect on your application, and then decide
weather to modify it or not. Changing the values is actually very easy, you just have to open the configuration file in your
favorite text file editor, and simply modify the settings according to your needs. Again, remember to restart the web-server
after you’ve altered the configuration file.
The settings in the php.ini file take the form of a setting name and a value separated by an equals sign. White spaces between
these two are ignored; a semicolon instructs PHP not to take into consideration the text that follows the semicolon, until the
end of the line. Most settings’ names are suggestive to their behavior, and you will find some useful descriptions before
each setting.
One of the most powerful features of PHP is the ability to customize its behavior through a configuration file. In this first article,
we're going to cover some of the ways the php.ini file can be used and how it might help you. The second article will outline
in detail many of the more frequently used directives of the php.ini file.
Using the PHP configuration file can make administration of PHP as simple as administration of Apache! Depending on your web server
preferences, that could be good or bad. But we'll just assume it's good for the sake of this article. The php.ini file is used by
PHP to simplify post-installation configuration of PHP and gives you one place for all of PHP's runtime configurations. Wouldn't
it just be a pain to have to recompile PHP for every little change in behavior?
When PHP fires up its engines, one of the first thing it does is to look for the php.ini file so that it can read into memory the
directives defined therein. It looks for php.ini in the current working directory, the path designated by the environmental variable PHPRC,
and in the path defined at compile time. Most of the time when you compile PHP, it places a copy of the ini file in /usr/local/lib/php/.
If you are on a Unix machine, you may be able to type locate php.ini or find / -name php.ini -print and have it tell you the location of the
php.ini file. If you have installed it on a Windows machine, use the "Find -> Files or Folders" option from the Start Menu.
As I said before, the php.ini file provides the advantage of allowing you to dynamically customize PHP. Well, dynamically is only half true.
If you're running PHP as an Apache module, the configuration directives reside in memory until a new Apache process has been started.
Since a CGI program starts a new process each time, the configuration information is re-read each time PHP is used as a CGI program,
thus giving the impression of dynamic configuration. Otherwise, the PHP configuration remains unchanged until the web server is restarted.
If you are using Apache, apachectl restart will do the trick.
In previous versions of PHP you could include the configuration directives as Apache directives in either the httpd.conf or .htaccess files.
With version 4.x, all directives must reside in the php.ini file with the exception of php_value, php_flag, php_admin_value, and php_admin_flag.
The following is a brief description of what these four directives do as well as their usage:
php_value name value
This directive allows you to essentially define your own directives. Just enter the directive php_value followed by the name of
your custom directive and then the value that should be associated with that directive.
php_flag name on|off
This directive is similar to php_value except that it allows you to define a custom directive with a Boolean ("on" or "off") value.
php_admin_value name value
Also similar to php_value, this directive can only be defined in the Apache httpd.conf file.
php_admin_flag name on|off
The Boolean version of php_admin_value.
Because of the power of php.ini, some security issues must be noted or the world will end. OK, well, it might not actually "end."
But it sure might feel as if it did. If you're using PHP as a CGI, then you should always set the safe_mode directive to "On."
Then set the safe_mode_exec_dir directive. By doing this, you're ensuring that the user can only access information contained in his document root.
Also note that if you enable dynamic module loading with the enable_dl directive, it's possible the safe_mode restrictions could be bypassed.
The structure of the php.ini file is a standard "directive = value" syntax, very much in the style of Windows .ini files. Lines consisting
of only white space and lines beginning with a semicolon are ignored. The semicolon is used to add comments to the file. To give a directive
an empty value, you can either leave the value blank or use the word none. Sections are defined with "[" and "]" with the section name
sandwiched in between (i.e., "[custom stuff]"). You probably don't need to worry about sections very much except to make reading the
configuration file a little easier.
Now that you have located your php.ini file, it can be edited with any text editor. In Unix, vi is the standard, with pico and emacs
popular alternatives. Windows users can use Notepad, but be careful when using programs like Microsoft Word that change the format of the document.
System administration is best done with a text editor instead of a word processor.
In the next article I cover in detail some of the more powerful directives of the PHP configuration file, so stay tuned!
Running PHP as an Apache module
When using PHP as an Apache module, you can also change the configuration settings using directives in Apache configuration files
(e.g. httpd.conf) and .htaccess files. You will need "AllowOverride Options" or "AllowOverride All" privileges to do so.
With PHP 4 and PHP 5, there are several Apache directives that allow you to change the PHP configuration from within the Apache
configuration files. For a listing of which directives are PHP_INI_ALL, PHP_INI_PERDIR, or PHP_INI_SYSTEM, have a look at the List of php.ini directives appendix.
Note: With PHP 3, there are Apache directives that correspond to each configuration setting in the php3.ini name, except the name is
prefixed by "php3_".
php_value name value
Sets the value of the specified directive. Can be used only with PHP_INI_ALL and PHP_INI_PERDIR type directives. To clear a
previously set value use none as the value.
Note: Don't use php_value to set boolean values. php_flag (see below) should be used instead.
php_flag name on|off
Used to set a boolean configuration directive. Can be used only with PHP_INI_ALL and PHP_INI_PERDIR type directives.
php_admin_value name value
Sets the value of the specified directive. This can not be used in .htaccess files. Any directive type set with php_admin_value
can not be overridden by .htaccess. To clear a previously set value use none as the value.
php_admin_flag name on|off
Used to set a boolean configuration directive. This can not be used in .htaccess files. Any directive type set with php_admin_flag
can not be overridden by .htaccess.
Example#1 Apache configuration example
<IfModule mod_php5.c>
php_value include_path ".:/usr/local/lib/php"
php_admin_flag safe_mode on
</IfModule>
<IfModule mod_php4.c>
php_value include_path ".:/usr/local/lib/php"
php_admin_flag safe_mode on
</IfModule>
<IfModule mod_php3.c>
php3_include_path ".:/usr/local/lib/php"
php3_safe_mode on
</IfModule>
Caution
PHP constants do not exist outside of PHP. For example, in httpd.conf you can not use PHP constants such as E_ALL or E_NOTICE to set
the error_reporting directive as they will have no meaning and will evaluate to 0. Use the associated bitmask values instead.
These constants can be used in php.ini
Changing PHP configuration via the Windows registry
When running PHP on Windows, the configuration values can be modified on a per-directory basis using the Windows registry.
The configuration values are stored in the registry key HKLM\SOFTWARE\PHP\Per Directory Values, in the sub-keys corresponding to the path names.
For example, configuration values for the directory c:\inetpub\wwwroot would be stored in the key HKLM\SOFTWARE\PHP\Per
Directory Values\c\inetpub\wwwroot. The settings for the directory would be active for any script running from this directory or any subdirectory of it.
The values under the key should have the name of the PHP configuration directive and the string value. PHP constants in the values are not parsed.
However, only configuration values changeable in PHP_INI_USER can be set this way, PHP_INI_PERDIR values can not.
Other interfaces to PHP
Regardless of how you run PHP, you can change certain values at runtime of your scripts through ini_set().
See the documentation on the ini_set() page for more information.
If you are interested in a complete list of configuration settings on your system with their current values,
you can execute the phpinfo() function, and review the resulting page. You can also access the values of individual
configuration directives at runtime using ini_get() or get_cfg_var().
To change the configuration for php running as cgi those handy module commands won't work.. The work-around is being
able to tell php to start with a custom php.ini file.. configured the way you want.
With multiple custom php.ini files
-------------------------------------------
/site/ini/1/php.ini
/site/ini/2/php.ini
/site/ini/3/php.ini
--
The trick is creating a wrapper script to set the location of the php.ini file that php will use. Then it exec's the php cgi.
shell script /cgi-bin/phpini.cgi
-------------------------------------------
#!/bin/sh
export PHPRC=/site/ini/1
exec /cgi-bin/php5.cgi
--
Now all you have to do is setup Apache to run php files through the wrapper script instead of just executing the php cgi.
In your .htaccess or httpd.conf file
-------------------------------------------
AddHandler php-cgi .php
Action php-cgi /cgi-bin/phpini.cgi
--
So to change the configuration of php you just need to change the PHPRC variable to point to a different directory
containing your customized php.ini.. You could also create multiple shell wrapper scripts and create multiple Handler's+Actions in .htaccess..
in your .htaccess
-------------------------------------------
AddHandler php-cgi1 .php1
Action php-cgi1 /cgi-bin/phpini-1.cgi
AddHandler php-cgi2 .php2
Action php-cgi2 /cgi-bin/phpini-2.cgi
AddHandler php-cgi3 .php3
Action php-cgi3 /cgi-bin/phpini-3.cgi
--
The only caveat here is that it seems like you would have to rename the file extensions, but there are ways around that too ->
http://www.askapache.com/php/custom-phpini-tips-and-tricks.html
It is not possible to unset a config option using php_value.
This caused me problems with auto_prepend_file settings where I wanted to have a global file auto included, with an exception for only one site.
The solution used to be to use auto_prepend_file /dev/null, but this now causes errors, so I just create and include blank.inc now instead.
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:
[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
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.
