diff options
Diffstat (limited to 'INSTALL')
-rw-r--r-- | INSTALL | 2097 |
1 files changed, 0 insertions, 2097 deletions
diff --git a/INSTALL b/INSTALL deleted file mode 100644 index 957b6fac45..0000000000 --- a/INSTALL +++ /dev/null @@ -1,2097 +0,0 @@ -Installing PHP - _________________________________________________________________ - - Table of Contents - Preface - 1. General Installation Considerations - 2. Installation on Unix systems - - Apache 1.3.x on Unix systems - Apache 2.0 on Unix systems - Caudium - fhttpd related notes - Sun, iPlanet and Netscape servers on Sun Solaris - CGI and commandline setups - HP-UX specific installation notes - OpenBSD installation notes - Solaris specific installation tips - Gentoo installation notes - Debian GNU/Linux installation notes - - 3. Installation on Mac OS X - - Using Packages - Compiling for OS X Server - Compiling for MacOS X Client - - 4. Installation of PECL extensions - - Introduction to PECL Installations - Downloading PECL extensions - PECL for Windows users - Compiling shared PECL extensions with PEAR - Compiling shared PECL extensions with phpize - Compiling PECL extensions statically into PHP - - 5. Problems? - - Read the FAQ - Other problems - Bug reports - - 6. Runtime Configuration - - The configuration file - How to change configuration settings - - 7. Installation FAQ - _________________________________________________________________ - -Preface - - These installation instructions were generated from the HTML version - of the PHP Manual so formatting and linking have been altered. See the - online and updated version at: http://php.net/install.unix - _________________________________________________________________ - -Chapter 1. General Installation Considerations - - Before starting the installation, first you need to know what do you - want to use PHP for. There are three main fields you can use PHP, as - described in the What can PHP do? section: - - * Server-side scripting - * Command line scripting - * Client-side GUI applications - - For the first and most common form, you need three things: PHP itself, - a web server and a web browser. You probably already have a web - browser, and depending on your operating system setup, you may also - have a web server (e.g. Apache on Linux and MacOS X; IIS on Windows). - You may also rent webspace at a company. This way, you don't need to - set up anything on your own, only write your PHP scripts, upload it to - the server you rent, and see the results in your browser. - - While setting up the server and PHP on your own, you have two choices - for the method of connecting PHP to the server. For many servers PHP - has a direct module interface (also called SAPI). These servers - include Apache, Microsoft Internet Information Server, Netscape and - iPlanet servers. Many other servers have support for ISAPI, the - Microsoft module interface (OmniHTTPd for example). If PHP has no - module support for your web server, you can always use it as a CGI or - FastCGI processor. This means you set up your server to use the CGI - executable of PHP to process all PHP file requests on the server. - - If you are also interested to use PHP for command line scripting (e.g. - write scripts autogenerating some images for you offline, or - processing text files depending on some arguments you pass to them), - you always need the command line executable. For more information, - read the section about writing command line PHP applications. In this - case, you need no server and no browser. - - With PHP you can also write desktop GUI applications using the PHP-GTK - extension. This is a completely different approach than writing web - pages, as you do not output any HTML, but manage windows and objects - within them. For more information about PHP-GTK, please visit the site - dedicated to this extension. PHP-GTK is not included in the official - PHP distribution. - - From now on, this section deals with setting up PHP for web servers on - Unix and Windows with server module interfaces and CGI executables. - You will also find information on the command line executable in the - following sections. - - PHP source code and binary distributions for Windows can be found at - http://www.php.net/downloads.php. We recommend you to choose a mirror - nearest to you for downloading the distributions. - _________________________________________________________________ - -Chapter 2. Installation on Unix systems - - This section will guide you through the general configuration and - installation of PHP on Unix systems. Be sure to investigate any - sections specific to your platform or web server before you begin the - process. - - As our manual outlines in the General Installation Considerations - section, we are mainly dealing with web centric setups of PHP in this - section, although we will cover setting up PHP for command line usage - as well. - - There are several ways to install PHP for the Unix platform, either - with a compile and configure process, or through various pre-packaged - methods. This documentation is mainly focused around the process of - compiling and configuring PHP. Many Unix like systems have some sort - of package installation system. This can assist in setting up a - standard configuration, but if you need to have a different set of - features (such as a secure server, or a different database driver), - you may need to build PHP and/or your webserver. If you are unfamiliar - with building and compiling your own software, it is worth checking to - see whether somebody has already built a packaged version of PHP with - the features you need. - - Prerequisite knowledge and software for compiling: - - * Basic Unix skills (being able to operate "make" and a C compiler) - * An ANSI C compiler - * flex: Version 2.5.4 - * bison: Version 1.28 (preferred), 1.35, or 1.75 - * A web server - * Any module specific components (such as gd, pdf libs, etc.) - - The initial PHP setup and configuration process is controlled by the - use of the commandline options of the configure script. You could get - a list of all available options along with short explanations running - ./configure --help. Our manual documents the different options - separately. You will find the core options in the appendix, while the - different extension specific options are descibed on the reference - pages. - - When PHP is configured, you are ready to build the module and/or - executables. The command make should take care of this. If it fails - and you can't figure out why, see the Problems section. - _________________________________________________________________ - -Apache 1.3.x on Unix systems - - This section contains notes and hints specific to Apache installs of - PHP on Unix platforms. We also have instructions and notes for Apache - 2 on a separate page. - - You can select arguments to add to the configure on line 10 below from - the list of core configure options and from extension specific options - described at the respective places in the manual. The version numbers - have been omitted here, to ensure the instructions are not incorrect. - You will need to replace the 'xxx' here with the correct values from - your files. - - Example 2-1. Installation Instructions (Apache Shared Module Version) - for PHP -1. gunzip apache_xxx.tar.gz -2. tar -xvf apache_xxx.tar -3. gunzip php-xxx.tar.gz -4. tar -xvf php-xxx.tar -5. cd apache_xxx -6. ./configure --prefix=/www --enable-module=so -7. make -8. make install -9. cd ../php-xxx - -10. Now, configure your PHP. This is where you customize your PHP - with various options, like which extensions will be enabled. Do a - ./configure --help for a list of available options. In our example - we'll do a simple configure with Apache 1 and MySQL support. Your - path to apxs may differ from our example. - - ./configure --with-mysql --with-apxs=/www/bin/apxs - -11. make -12. make install - - If you decide to change your configure options after installation, - you only need to repeat the last three steps. You only need to - restart apache for the new module to take effect. A recompile of - Apache is not needed. - - Note that unless told otherwise, 'make install' will also install PEAR, - various PHP tools such as phpize, install the PHP CLI, and more. - -13. Setup your php.ini file: - - cp php.ini-dist /usr/local/lib/php.ini - - You may edit your .ini file to set PHP options. If you prefer your - php.ini in another location, use --with-config-file-path=/some/path in - step 10. - - If you instead choose php.ini-recommended, be certain to read the list - of changes within, as they affect how PHP behaves. - -14. Edit your httpd.conf to load the PHP module. The path on the right hand - side of the LoadModule statement must point to the path of the PHP - module on your system. The make install from above may have already - added this for you, but be sure to check. - - For PHP 4: - - LoadModule php4_module libexec/libphp4.so - - For PHP 5: - - LoadModule php5_module libexec/libphp5.so - -15. And in the AddModule section of httpd.conf, somewhere under the - ClearModuleList, add this: - - For PHP 4: - - AddModule mod_php4.c - - For PHP 5: - - AddModule mod_php5.c - -16. Tell Apache to parse certain extensions as PHP. For example, - let's have Apache parse the .php extension as PHP. You could - have any extension(s) parse as PHP by simply adding more, with - each separated by a space. We'll add .phtml to demonstrate. - - AddType application/x-httpd-php .php .phtml - - It's also common to setup the .phps extension to show highlighted PHP - source, this can be done with: - - AddType application/x-httpd-php-source .phps - -17. Use your normal procedure for starting the Apache server. (You must - stop and restart the server, not just cause the server to reload by - using a HUP or USR1 signal.) - - Alternatively, to install PHP as a static object: - - Example 2-2. Installation Instructions (Static Module Installation for - Apache) for PHP -1. gunzip -c apache_1.3.x.tar.gz | tar xf - -2. cd apache_1.3.x -3. ./configure -4. cd .. - -5. gunzip -c php-5.x.y.tar.gz | tar xf - -6. cd php-5.x.y -7. ./configure --with-mysql --with-apache=../apache_1.3.x -8. make -9. make install - -10. cd ../apache_1.3.x - -11. ./configure --prefix=/www --activate-module=src/modules/php5/libphp5.a - (The above line is correct! Yes, we know libphp5.a does not exist at this - stage. It isn't supposed to. It will be created.) - -12. make - (you should now have an httpd binary which you can copy to your Apache bin -dir if - it is your first install then you need to "make install" as well) - -13. cd ../php-5.x.y -14. cp php.ini-dist /usr/local/lib/php.ini - -15. You can edit /usr/local/lib/php.ini file to set PHP options. - Edit your httpd.conf or srm.conf file and add: - AddType application/x-httpd-php .php - - Note: Replace php-5 by php-4 and php5 by php4 in PHP 4. - - Depending on your Apache install and Unix variant, there are many - possible ways to stop and restart the server. Below are some typical - lines used in restarting the server, for different apache/unix - installations. You should replace /path/to/ with the path to these - applications on your systems. - - Example 2-3. Example commands for restarting Apache -1. Several Linux and SysV variants: -/etc/rc.d/init.d/httpd restart - -2. Using apachectl scripts: -/path/to/apachectl stop -/path/to/apachectl start - -3. httpdctl and httpsdctl (Using OpenSSL), similar to apachectl: -/path/to/httpsdctl stop -/path/to/httpsdctl start - -4. Using mod_ssl, or another SSL server, you may want to manually -stop and start: -/path/to/apachectl stop -/path/to/apachectl startssl - - The locations of the apachectl and http(s)dctl binaries often vary. If - your system has locate or whereis or which commands, these can assist - you in finding your server control programs. - - Different examples of compiling PHP for apache are as follows: - - ./configure --with-apxs --with-pgsql - - This will create a libphp5.so (or libphp4.so in PHP 4) shared library - that is loaded into Apache using a LoadModule line in Apache's - httpd.conf file. The PostgreSQL support is embedded into this library. - - ./configure --with-apxs --with-pgsql=shared - - This will create a libphp4.so shared library for Apache, but it will - also create a pgsql.so shared library that is loaded into PHP either - by using the extension directive in php.ini file or by loading it - explicitly in a script using the dl() function. - - ./configure --with-apache=/path/to/apache_source --with-pgsql - - This will create a libmodphp5.a library, a mod_php5.c and some - accompanying files and copy this into the src/modules/php5 directory - in the Apache source tree. Then you compile Apache using - --activate-module=src/modules/php5/libphp5.a and the Apache build - system will create libphp5.a and link it statically into the httpd - binary (replace php5 by php4 in PHP 4). The PostgreSQL support is - included directly into this httpd binary, so the final result here is - a single httpd binary that includes all of Apache and all of PHP. - - ./configure --with-apache=/path/to/apache_source --with-pgsql=shared - - Same as before, except instead of including PostgreSQL support - directly into the final httpd you will get a pgsql.so shared library - that you can load into PHP from either the php.ini file or directly - using dl(). - - When choosing to build PHP in different ways, you should consider the - advantages and drawbacks of each method. Building as a shared object - will mean that you can compile apache separately, and don't have to - recompile everything as you add to, or change, PHP. Building PHP into - apache (static method) means that PHP will load and run faster. For - more information, see the Apache webpage on DSO support. - - Note: Apache's default httpd.conf currently ships with a section - that looks like this: - -User nobody -Group "#-1" - - Unless you change that to "Group nogroup" or something like that - ("Group daemon" is also very common) PHP will not be able to open - files. - - Note: Make sure you specify the installed version of apxs when - using --with-apxs=/path/to/apxs. You must NOT use the apxs version - that is in the apache sources but the one that is actually - installed on your system. - _________________________________________________________________ - -Apache 2.0 on Unix systems - - This section contains notes and hints specific to Apache 2.0 installs - of PHP on Unix systems. - - Warning - - We do not recommend using a threaded MPM in production with Apache2. - Use the prefork MPM instead, or use Apache1. For information on why, - read the related FAQ entry on using Apache2 with a threaded MPM - - You are highly encouraged to take a look at the Apache Documentation - to get a basic understanding of the Apache 2.0 Server. - - PHP and Apache 2.0.x compatibility notes: The following versions of - PHP are known to work with the most recent version of Apache 2.0.x: - - * PHP 4.3.0 or later available at http://www.php.net/downloads.php. - * the latest stable development version. Get the source code - http://snaps.php.net/php5-latest.tar.gz or download binaries for - Windows http://snaps.php.net/win32/php5-win32-latest.zip. - * a prerelease version downloadable from http://qa.php.net/. - * you have always the option to obtain PHP through anonymous CVS. - - These versions of PHP are compatible to Apache 2.0.40 and later. - - Apache 2.0 SAPI-support started with PHP 4.2.0. PHP 4.2.3 works - with Apache 2.0.39, don't use any other version of Apache with PHP - 4.2.3. However, the recommended setup is to use PHP 4.3.0 or later - with the most recent version of Apache2. - - All mentioned versions of PHP will work still with Apache 1.3.x. - - Download the most recent version of Apache 2.0 and a fitting PHP - version from the above mentioned places. This quick guide covers only - the basics to get started with Apache 2.0 and PHP. For more - information read the Apache Documentation. The version numbers have - been omitted here, to ensure the instructions are not incorrect. You - will need to replace the 'NN' here with the correct values from your - files. - - Example 2-4. Installation Instructions (Apache 2 Shared Module - Version) -1. gzip -d httpd-2_0_NN.tar.gz -2. tar xvf httpd-2_0_NN.tar -3. gunzip php-NN.tar.gz -4. tar -xvf php-NN.tar -5. cd httpd-2_0_NN -6. ./configure --enable-so -7. make -8. make install - - Now you have Apache 2.0.NN available under /usr/local/apache2, - configured with loadable module support and the standard MPM prefork. - To test the installation use your normal procedure for starting - the Apache server, e.g.: - /usr/local/apache2/bin/apachectl start - and stop the server to go on with the configuration for PHP: - /usr/local/apache2/bin/apachectl stop. - -9. cd ../php-NN - -10. Now, configure your PHP. This is where you customize your PHP - with various options, like which extensions will be enabled. Do a - ./configure --help for a list of available options. In our example - we'll do a simple configure with Apache 2 and MySQL support. Your - path to apxs may differ, in fact, the binary may even be named apxs2 on - your system. - - ./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-mysql - -11. make -12. make install - - If you decide to change your configure options after installation, - you only need to repeat the last three steps. You only need to - restart apache for the new module to take effect. A recompile of - Apache is not needed. - - Note that unless told otherwise, 'make install' will also install PEAR, - various PHP tools such as phpize, install the PHP CLI, and more. - -13. Setup your php.ini - - cp php.ini-dist /usr/local/lib/php.ini - - You may edit your .ini file to set PHP options. If you prefer having - php.ini in another location, use --with-config-file-path=/some/path in - step 10. - - If you instead choose php.ini-recommended, be certain to read the list - of changes within, as they affect how PHP behaves. - -14. Edit your httpd.conf to load the PHP module. The path on the right hand - side of the LoadModule statement must point to the path of the PHP - module on your system. The make install from above may have already - added this for you, but be sure to check. - - For PHP 4: - - LoadModule php4_module modules/libphp4.so - - For PHP 5: - - LoadModule php5_module modules/libphp5.so - -15. Tell Apache to parse certain extensions as PHP. For example, - let's have Apache parse the .php extension as PHP. You could - have any extension(s) parse as PHP by simply adding more, with - each separated by a space. We'll add .phtml to demonstrate. - - AddType application/x-httpd-php .php .phtml - - It's also common to setup the .phps extension to show highlighted PHP - source, this can be done with: - - AddType application/x-httpd-php-source .phps - -16. Use your normal procedure for starting the Apache server, e.g.: - - /usr/local/apache2/bin/apachectl start - - Following the steps above you will have a running Apache 2.0 with - support for PHP as SAPI module. Of course there are many more - configuration options available for both, Apache and PHP. For more - information use ./configure --help in the corresponding source tree. - In case you wish to build a multithreaded version of Apache 2.0 you - must overwrite the standard MPM-Module prefork either with worker or - perchild. To do so append to your configure line in step 6 above - either the option --with-mpm=worker or --with-mpm=perchild. Take care - about the consequences and understand what you are doing. For more - information read the Apache documentation about the MPM-Modules. - - Note: If you want to use content negotiation, read the Apache - MultiViews FAQ. - - Note: To build a multithreaded version of Apache your system must - support threads. This also implies to build PHP with experimental - Zend Thread Safety (ZTS). Therefore not all extensions might be - available. The recommended setup is to build Apache with the - standard prefork MPM-Module. - _________________________________________________________________ - -Caudium - - PHP 4 can be built as a Pike module for the Caudium webserver. Note - that this is not supported with PHP 3. Follow the simple instructions - below to install PHP 4 for Caudium. - - Example 2-5. Caudium Installation Instructions -1. Make sure you have Caudium installed prior to attempting to - install PHP 4. For PHP 4 to work correctly, you will need Pike - 7.0.268 or newer. For the sake of this example we assume that - Caudium is installed in /opt/caudium/server/. -2. Change directory to php-x.y.z (where x.y.z is the version number). -3. ./configure --with-caudium=/opt/caudium/server -4. make -5. make install -6. Restart Caudium if it's currently running. -7. Log into the graphical configuration interface and go to the - virtual server where you want to add PHP 4 support. -8. Click Add Module and locate and then add the PHP 4 Script Support module. -9. If the documentation says that the 'PHP 4 interpreter isn't - available', make sure that you restarted the server. If you did - check /opt/caudium/logs/debug/default.1 for any errors related to - <filename>PHP4.so</filename>. Also make sure that - <filename>caudium/server/lib/[pike-version]/PHP4.so</filename> - is present. -10. Configure the PHP Script Support module if needed. - - You can of course compile your Caudium module with support for the - various extensions available in PHP 4. See the reference pages for - extension specific configure options. - - Note: When compiling PHP 4 with MySQL support you must make sure - that the normal MySQL client code is used. Otherwise there might be - conflicts if your Pike already has MySQL support. You do this by - specifying a MySQL install directory the --with-mysql option. - _________________________________________________________________ - -fhttpd related notes - - To build PHP as an fhttpd module, answer "yes" to "Build as an fhttpd - module?" (the --with-fhttpd=DIR option to configure) and specify the - fhttpd source base directory. The default directory is - /usr/local/src/fhttpd. If you are running fhttpd, building PHP as a - module will give better performance, more control and remote execution - capability. - - Note: Support for fhttpd is no longer available as of PHP 4.3.0. - _________________________________________________________________ - -Sun, iPlanet and Netscape servers on Sun Solaris - - This section contains notes and hints specific to Sun Java System Web - Server, Sun ONE Web Server, iPlanet and Netscape server installs of - PHP on Sun Solaris. - - From PHP 4.3.3 on you can use PHP scripts with the NSAPI module to - generate custom directory listings and error pages. Additional - functions for Apache compatibility are also available. For support in - current webservers read the note about subrequests. - - You can find more information about setting up PHP for the Netscape - Enterprise Server (NES) here: - http://benoit.noss.free.fr/php/install-php4.html - - To build PHP with Sun JSWS/Sun ONE WS/iPlanet/Netscape webservers, - enter the proper install directory for the --with-nsapi=[DIR] option. - The default directory is usually /opt/netscape/suitespot/. Please also - read /php-xxx-version/sapi/nsapi/nsapi-readme.txt. - - 1. Install the following packages from http://www.sunfreeware.com/ or - another download site: - - autoconf-2.13 - automake-1.4 - bison-1_25-sol26-sparc-local - flex-2_5_4a-sol26-sparc-local - gcc-2_95_2-sol26-sparc-local - gzip-1.2.4-sol26-sparc-local - m4-1_4-sol26-sparc-local - make-3_76_1-sol26-sparc-local - mysql-3.23.24-beta (if you want mysql support) - perl-5_005_03-sol26-sparc-local - tar-1.13 (GNU tar) - 2. Make sure your path includes the proper directories - PATH=.:/usr/local/bin:/usr/sbin:/usr/bin:/usr/ccs/bin and make it - available to your system export PATH. - 3. gunzip php-x.x.x.tar.gz (if you have a .gz dist, otherwise go to - 4). - 4. tar xvf php-x.x.x.tar - 5. Change to your extracted PHP directory: cd ../php-x.x.x - 6. For the following step, make sure /opt/netscape/suitespot/ is - where your netscape server is installed. Otherwise, change to the - correct path and run: - -./configure --with-mysql=/usr/local/mysql \ ---with-nsapi=/opt/netscape/suitespot/ \ ---enable-libgcc - - 7. Run make followed by make install. - - After performing the base install and reading the appropriate readme - file, you may need to perform some additional configuration steps. - - Configuration Instructions for Sun/iPlanet/Netscape. Firstly you may - need to add some paths to the LD_LIBRARY_PATH environment for the - server to find all the shared libs. This can best done in the start - script for your webserver. The start script is often located in: - /path/to/server/https-servername/start. You may also need to edit the - configuration files that are located in: - /path/to/server/https-servername/config/. - - 1. Add the following line to mime.types (you can do that by the - administration server): - -type=magnus-internal/x-httpd-php exts=php - - 2. Edit magnus.conf (for servers >= 6) or obj.conf (for servers < 6) - and add the following, shlib will vary depending on your system, - it will be something like /opt/netscape/suitespot/bin/libphp4.so. - You should place the following lines after mime types init. - -Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="/o -pt/netscape/suitespot/bin/libphp4.so" -Init fn="php4_init" LateInit="yes" errorString="Failed to initialize PHP!" [php -_ini="/path/to/php.ini"] - - (PHP >= 4.3.3) The php_ini parameter is optional but with it you - can place your php.ini in your webserver config directory. - 3. Configure the default object in obj.conf (for virtual server - classes [version 6.0+] in their vserver.obj.conf): - -<Object name="default"> -. -. -. -.#NOTE this next line should happen after all 'ObjectType' and before all 'AddL -og' lines -Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inik -ey=value ...] -. -. -</Object> - - (PHP >= 4.3.3) As additional parameters you can add some special - php.ini-values, for example you can set a - docroot="/path/to/docroot" specific to the context php4_execute is - called. For boolean ini-keys please use 0/1 as value, not - "On","Off",... (this will not work correctly), e.g. - zlib.output_compression=1 instead of zlib.output_compression="On" - 4. This is only needed if you want to configure a directory that only - consists of PHP scripts (same like a cgi-bin directory): - -<Object name="x-httpd-php"> -ObjectType fn="force-type" type="magnus-internal/x-httpd-php" -Service fn=php4_execute [inikey=value inikey=value ...] -</Object> - - After that you can configure a directory in the Administration - server and assign it the style x-httpd-php. All files in it will - get executed as PHP. This is nice to hide PHP usage by renaming - files to .html. - 5. Setup of authentication: PHP authentication cannot be used with - any other authentication. ALL AUTHENTICATION IS PASSED TO YOUR PHP - SCRIPT. To configure PHP Authentication for the entire server, add - the following line to your default object: - -<Object name="default"> -AuthTrans fn=php4_auth_trans -. -. -. -</Object> - - 6. To use PHP Authentication on a single directory, add the - following: - -<Object ppath="d:\path\to\authenticated\dir\*"> -AuthTrans fn=php4_auth_trans -</Object> - - Note: The stacksize that PHP uses depends on the configuration of - the webserver. If you get crashes with very large PHP scripts, it - is recommended to raise it with the Admin Server (in the section - "MAGNUS EDITOR"). - _________________________________________________________________ - -CGI environment and recommended modifications in php.ini - - Important when writing PHP scripts is the fact that Sun JSWS/Sun ONE - WS/iPlanet/Netscape is a multithreaded web server. Because of that all - requests are running in the same process space (the space of the - webserver itself) and this space has only one environment. If you want - to get CGI variables like PATH_INFO, HTTP_HOST etc. it is not the - correct way to try this in the old PHP 3.x way with getenv() or a - similar way (register globals to environment, $_ENV). You would only - get the environment of the running webserver without any valid CGI - variables! - - Note: Why are there (invalid) CGI variables in the environment? - - Answer: This is because you started the webserver process from the - admin server which runs the startup script of the webserver, you - wanted to start, as a CGI script (a CGI script inside of the admin - server!). This is why the environment of the started webserver has - some CGI environment variables in it. You can test this by starting - the webserver not from the administration server. Use the command - line as root user and start it manually - you will see there are no - CGI-like environment variables. - - Simply change your scripts to get CGI variables in the correct way for - PHP 4.x by using the superglobal $_SERVER. If you have older scripts - which use $HTTP_HOST, etc., you should turn on register_globals in - php.ini and change the variable order too (important: remove "E" from - it, because you do not need the environment here): -variables_order = "GPCS" -register_globals = On - _________________________________________________________________ - -Special use for error pages or self-made directory listings (PHP >= 4.3.3) - - You can use PHP to generate the error pages for "404 Not Found" or - similar. Add the following line to the object in obj.conf for every - error page you want to overwrite: -Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value ini -key=value...] - - where XXX is the HTTP error code. Please delete any other Error - directives which could interfere with yours. If you want to place a - page for all errors that could exist, leave the code parameter out. - Your script can get the HTTP status code with $_SERVER['ERROR_TYPE']. - - Another possibility is to generate self-made directory listings. Just - create a PHP script which displays a directory listing and replace the - corresponding default Service line for - type="magnus-internal/directory" in obj.conf with the following: -Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/scr -ipt.php" [inikey=value inikey=value...] - - For both error and directory listing pages the original URI and - translated URI are in the variables $_SERVER['PATH_INFO'] and - $_SERVER['PATH_TRANSLATED']. - _________________________________________________________________ - -Note about nsapi_virtual() and subrequests (PHP >= 4.3.3) - - The NSAPI module now supports the nsapi_virtual() function (alias: - virtual()) to make subrequests on the webserver and insert the result - in the webpage. This function uses some undocumented features from the - NSAPI library. On Unix the module automatically looks for the needed - functions and uses them if available. If not, nsapi_virtual() is - disabled. - - Note: But be warned: Support for nsapi_virtual() is EXPERIMENTAL!!! - _________________________________________________________________ - -CGI and commandline setups - - The default is to build PHP as a CGI program. This creates a - commandline interpreter, which can be used for CGI processing, or for - non-web-related PHP scripting. If you are running a web server PHP has - module support for, you should generally go for that solution for - performance reasons. However, the CGI version enables users to run - different PHP-enabled pages under different user-ids. - - Warning - - By using the CGI setup, your server is open to several possible - attacks. Please read our CGI security section to learn how to defend - yourself from those attacks. - - As of PHP 4.3.0, some important additions have happened to PHP. A new - SAPI named CLI also exists and it has the same name as the CGI binary. - What is installed at {PREFIX}/bin/php depends on your configure line - and this is described in detail in the manual section named Using PHP - from the command line. For further details please read that section of - the manual. - _________________________________________________________________ - -Testing - - If you have built PHP as a CGI program, you may test your build by - typing make test. It is always a good idea to test your build. This - way you may catch a problem with PHP on your platform early instead of - having to struggle with it later. - _________________________________________________________________ - -Benchmarking - - If you have built PHP 3 as a CGI program, you may benchmark your build - by typing make bench. Note that if safe mode is on by default, the - benchmark may not be able to finish if it takes longer then the 30 - seconds allowed. This is because the set_time_limit() can not be used - in safe mode. Use the max_execution_time configuration setting to - control this time for your own scripts. make bench ignores the - configuration file. - - Note: make bench is only available for PHP 3. - _________________________________________________________________ - -Using Variables - - Some server supplied environment variables are not defined in the - current CGI/1.1 specification. Only the following variables are - defined there: AUTH_TYPE, CONTENT_LENGTH, CONTENT_TYPE, - GATEWAY_INTERFACE, PATH_INFO, PATH_TRANSLATED, QUERY_STRING, - REMOTE_ADDR, REMOTE_HOST, REMOTE_IDENT, REMOTE_USER, REQUEST_METHOD, - SCRIPT_NAME, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL, and - SERVER_SOFTWARE. Everything else should be treated as 'vendor - extensions'. - _________________________________________________________________ - -HP-UX specific installation notes - - This section contains notes and hints specific to installing PHP on - HP-UX systems. (Contributed by paul_mckay at clearwater-it dot co dot - uk). - - Note: These tips were written for PHP 4.0.4 and Apache 1.3.9. - - 1. You need gzip, download a binary distribution from - http://hpux.connect.org.uk/ftp/hpux/Gnu/gzip-1.2.4a/gzip-1.2.4a-sd - -10.20.depot.Z uncompress the file and install using swinstall. - 2. You need gcc, download a binary distribution from - http://gatekeep.cs.utah.edu/ftp/hpux/Gnu/gcc-2.95.2/gcc-2.95.2-sd- - 10.20.depot.gz. uncompress this file and install gcc using - swinstall. - 3. You need the GNU binutils, you can download a binary distribution - from - http://hpux.connect.org.uk/ftp/hpux/Gnu/binutils-2.9.1/binutils-2. - 9.1-sd-10.20.depot.gz. uncompress this file and install binutils - using swinstall. - 4. You now need bison, you can download a binary distribution from - http://hpux.connect.org.uk/ftp/hpux/Gnu/bison-1.28/bison-1.28-sd-1 - 0.20.depot.gz, install as above. - 5. You now need flex, you need to download the source from one of the - http://www.gnu.org mirrors. It is in the non-gnu directory of the - ftp site. Download the file, gunzip, then tar -xvf it. Go into the - newly created flex directory and run ./configure, followed by - make, and then make install. - If you have errors here, it's probably because gcc etc. are not in - your PATH so add them to your PATH. - 6. Download the PHP and apache sources. - 7. gunzip and tar -xvf them. We need to hack a couple of files so - that they can compile OK. - 8. Firstly the configure file needs to be hacked because it seems to - lose track of the fact that you are a hpux machine, there will be - a better way of doing this but a cheap and cheerful hack is to put - lt_target=hpux10.20 on line 47286 of the configure script. - 9. Next, the Apache GuessOS file needs to be hacked. Under - apache_1.3.9/src/helpers change line 89 from echo - "hp${HPUXMACH}-hpux${HPUXVER}"; exit 0 to: echo - "hp${HPUXMACH}-hp-hpux${HPUXVER}"; exit 0 - 10. You cannot install PHP as a shared object under HP-UX so you must - compile it as a static, just follow the instructions at the Apache - page. - 11. PHP and Apache should have compiled OK, but Apache won't start. - you need to create a new user for Apache, e.g. www, or apache. You - then change lines 252 and 253 of the conf/httpd.conf in Apache so - that instead of - -User nobody -Group nogroup - - you have something like - -User www -Group sys - - This is because you can't run Apache as nobody under hp-ux. Apache - and PHP should then work. - _________________________________________________________________ - -OpenBSD installation notes - - This section contains notes and hints specific to installing PHP on - OpenBSD 3.6. - _________________________________________________________________ - -Using Binary Packages - - Using binary packages to install PHP on OpenBSD is the recommended and - simplest method. The core package has been separated from the various - modules, and each can be installed and removed independently from the - others. The files you need can be found on your OpenBSD CD or on the - FTP site. - - The main package you need to install is php4-core-4.3.8.tgz, which - contains the basic engine (plus gettext and iconv). Next, take a look - at the module packages, such as php4-mysql-4.3.8.tgz or - php4-imap-4.3.8.tgz. You need to use the phpxs command to activate and - deactivate these modules in your php.ini. - - Example 2-6. OpenBSD Package Install Example -# pkg_add php4-core-4.3.8.tgz -# /usr/local/sbin/phpxs -s -# cp /usr/local/share/doc/php4/php.ini-recommended /var/www/conf/php.ini - (add in mysql) -# pkg_add php4-mysql-4.3.8.tgz -# /usr/local/sbin/phpxs -a mysql - (add in imap) -# pkg_add php4-imap-4.3.8.tgz -# /usr/local/sbin/phpxs -a imap - (remove mysql as a test) -# pkg_delete php4-mysql-4.3.8 -# /usr/local/sbin/phpxs -r mysql - (install the PEAR libraries) -# pkg_add php4-pear-4.3.8.tgz - - Read the packages(7) manual page for more information about binary - packages on OpenBSD. - _________________________________________________________________ - -Using Ports - - You can also compile up PHP from source using the ports tree. However, - this is only recommended for users familiar with OpenBSD. The PHP 4 - port is split into two sub-directories: core and extensions. The - extensions directory generates sub-packages for all of the supported - PHP modules. If you find you do not want to create some of these - modules, use the no_* FLAVOR. For example, to skip building the imap - module, set the FLAVOR to no_imap. - _________________________________________________________________ - -Common Problems - - * The default install of Apache runs inside a chroot(2) jail, which - will restrict PHP scripts to accessing files under /var/www. You - will therefore need to create a /var/www/tmp directory for PHP - session files to be stored, or use an alternative session backend. - In addition, database sockets need to be placed inside the jail or - listen on the localhost interface. If you use network functions, - some files from /etc such as /etc/resolv.conf and /etc/services - will need to be moved into /var/www/etc. The OpenBSD PEAR package - automatically installs into the correct chroot directories, so no - special modification is needed there. More information on the - OpenBSD Apache is available in the OpenBSD FAQ. - * The OpenBSD 3.6 package for the gd extension requires XFree86 to - be installed. If you do not wish to use some of the font features - that require X11, install the php4-gd-4.3.8-no_x11.tgz package - instead. - _________________________________________________________________ - -Older Releases - - Older releases of OpenBSD used the FLAVORS system to compile up a - statically linked PHP. Since it is hard to generate binary packages - using this method, it is now deprecated. You can still use the old - stable ports trees if you wish, but they are unsupported by the - OpenBSD team. If you have any comments about this, the current - maintainer for the port is Anil Madhavapeddy (avsm at openbsd dot - org). - _________________________________________________________________ - -Solaris specific installation tips - - This section contains notes and hints specific to installing PHP on - Solaris systems. - _________________________________________________________________ - -Required software - - Solaris installs often lack C compilers and their related tools. Read - this FAQ for information on why using GNU versions for some of these - tools is necessary. The required software is as follows: - - * gcc (recommended, other C compilers may work) - * make - * flex - * bison - * m4 - * autoconf - * automake - * perl - * gzip - * tar - * GNU sed - - In addition, you will need to install (and possibly compile) any - additional software specific to your configuration, such as Oracle or - MySQL. - _________________________________________________________________ - -Using Packages - - You can simplify the Solaris install process by using pkgadd to - install most of your needed components. - _________________________________________________________________ - -Gentoo installation notes - - This section contains notes and hints specific to installing PHP on - Gentoo Linux. - _________________________________________________________________ - -Using Portage (emerge) - - While you can just download the PHP source and compile it yourself, - using Gentoo's packaging system is the simplest and cleanest method of - installing PHP. If you are not familiar with building software on - Linux, this is the way to go. - - If you have built your Gentoo system so far, you are probably used to - Portage already. Installing Apache and PHP is no different than the - other system tools. - - The first decision you need to make is whether you want to install - Apache 1.3.x or Apache 2.x. While both can be used with PHP, the steps - given below will use Apache 1.3.x. Another thing to consider is - whether your local Portage tree is up to date. If you have not updated - it recently, you need to run emerge sync before anything else. This - way, you will be using the most recent stable version of Apache and - PHP. - - Now that everything is in place, you can use the following example to - install Apache and PHP: - - Example 2-7. Gentoo Install Example with Apache 1.3 -# emerge \<apache-2 -# USE="-*" emerge php mod_php -# ebuild /var/db/pkg/dev-php/mod_php-<your PHP version>/mod_php-<your PHP versi -on>.ebuild config -# nano /etc/conf.d/apache - Add "-D PHP4" to APACHE_OPTS - -# rc-update add apache default -# /etc/init.d/apache start - - You can read more about emerge in the excellent Portage Manual - provided on the Gentoo website. - - If you need to use Apache 2, you can simply use emerge apache in the - last example. - _________________________________________________________________ - -Better control on configuration - - In the last section, PHP was emerged without any activated modules. As - of this writing, the only module activated by default with Portage is - XML which is needed by PEAR. This may not be what you want and you - will soon discover that you need more activated modules, like MySQL, - gettext, GD, etc. - - When you compile PHP from source yourself, you need to activate - modules via the configure command. With Gentoo, you can simply provide - USE flags which will be passed to the configure script automatically. - To see which USE flags to use with emerge, you can try: - - Example 2-8. Getting the list of valid USE flags -# USE="-*" emerge -pv php - -[ebuild N ] dev-php/php-4.3.6-r1 -X -berkdb -crypt -curl -debug -doc --fdftk -firebird -flash -freetds -gd -gd-external -gdbm -gmp -hardenedphp --imap -informix -ipv6 -java -jpeg -kerberos -ldap -mcal -memlimit -mssql --mysql -ncurses -nls -oci8 -odbc -pam -pdflib -png -postgres -qt -readline --snmp -spell -ssl -tiff -truetype -xml2 -yaz 3,876 kB - - As you can see from the last output, PHP considers a lot of USE flags. - Look at them closely and choose what you need. If you choose a flag - and you do not have the proper libraries, Portage will compile them - for you. It is a good idea to use emerge -pv again to see what Portage - will compile in accordance to your USE flags. As an example, if you do - not have X installed and you choose to include X in the USE flags, - Portage will compile X prior to PHP, which can take a couple of hours. - - If you choose to compile PHP with MySQL, cURL and GD support, the - command will look something like this: - - Example 2-9. Install PHP with USE flags - # USE="-* curl mysql gd" emerge php mod_php - - As in the last example, do not forget to emerge php as well as - mod_php. php is responsible for the command line version of PHP as - mod_php is for the Apache module version of PHP. - _________________________________________________________________ - -Common Problems - - * If you see the PHP source instead of the result the script should - produce, you have probably forgot to edit /etc/conf.d/apache. - Apache needs to be started with the -D PHP4 flag. To see if the - flag is present, you should be able to see it when using ps ax | - grep apache while Apache is running. - * Due to slotting problems, you might end up with more than one - version of PHP installed on your system. If this is the case, you - need to unmerge the old versions manually by using emerge unmerge - mod_php-<old version>. - * If you cannot emerge PHP because of Java, try putting -* in front - of your USE flags like in the above examples. - * If you are having problems configuring Apache and PHP, you can - always search the Gentoo Forums. Try searching with the keywords - "Apache PHP". - _________________________________________________________________ - -Debian GNU/Linux installation notes - - This section contains notes and hints specific to installing PHP on - Debian GNU/Linux. - _________________________________________________________________ - -Using APT - - While you can just download the PHP source and compile it yourself, - using Debian's packaging system is the simplest and cleanest method of - installing PHP. If you are not familiar with building software on - Linux, this is the way to go. - - The first decision you need to make is whether you want to install - Apache 1.3.x or Apache 2.x. The corresponding PHP packages are - respectively named libapache-mod-php* and libapache2-mod-php*. The - steps given below will use Apache 1.3.x. Please note that, as of this - writing, there is no official Debian packages of PHP 5. Then the steps - given below will install PHP 4. - - PHP is available in Debian as CGI or CLI flavour too, named - respectively php4-cgi and php4-cli. If you need them, you'll just have - to reproduce the following steps with the good package names. Another - special package you'd want to install is php4-pear. It contains a - minimal PEAR installation and the pear commandline utility. - - If you need more recent packages of PHP than the Debian's stable ones - or if some PHP modules lacks the Debian official repository, perhaps - you should take a look at http://www.apt-get.org/. One of the results - found should be Dotdeb. This unofficial repository is maintained by - Guillaume Plessis and contains Debian packages of the most recent - versions of PHP 4 and PHP 5. To use it, just add the to following two - lines to your /etc/apt/sources.lists and run apt-get update : - - Example 2-10. The two Dotdeb related lines -deb http://packages.dotdeb.org stable all -deb-src http://packages.dotdeb.org stable all - - The last thing to consider is whether your list of packages is up to - date. If you have not updated it recently, you need to run apt-get - update before anything else. This way, you will be using the most - recent stable version of the Apache and PHP packages. - - Now that everything is in place, you can use the following example to - install Apache and PHP: - - Example 2-11. Debian Install Example with Apache 1.3 - # apt-get install libapache-mod-php4 - - APT will automatically install the PHP 4 module for Apache 1.3, and - all its dependencies and then activate it. If you're not asked to - restart Apache during the install process, you'll have to do it - manually : - - Example 2-12. Stopping and starting Apache once PHP 4 is installed -# /etc/init.d/apache stop -# /etc/init.d/apache start - _________________________________________________________________ - -Better control on configuration - - In the last section, PHP was installed with only core modules. This - may not be what you want and you will soon discover that you need more - activated modules, like MySQL, cURL, GD, etc. - - When you compile PHP from source yourself, you need to activate - modules via the configure command. With APT, you just have to install - additional packages. They're all named 'php4-*' (or 'php5-*' if you - installed PHP 5 from a third party repository). - - Example 2-13. Getting the list of PHP additional packages - # dpkg -l 'php4-*' - - As you can see from the last output, there's a lot of PHP modules that - you can install (excluding the php4-cgi, php4-cli or php4-pear special - packages). Look at them closely and choose what you need. If you - choose a module and you do not have the proper libraries, APT will - automatically install all the dependencies for you. - - If you choose to add the MySQL, cURL and GD support to PHP the command - will look something like this: - - Example 2-14. Install PHP with MySQL, cURL and GD - # apt-get install php4-mysql php4-curl php4-gd - - APT will automatically add the appropriate lines to your different - php.ini (/etc/php4/apache/php.ini, /etc/php4/cgi/php.ini, etc). - - Example 2-15. These lines activate MySQL, cURL and GD into PHP -extension=mysql.so -extension=curl.so -extension=gd.so - - You'll only have to stop/start Apache as previously to activate the - modules. - _________________________________________________________________ - -Common Problems - - * If you see the PHP source instead of the result the script should - produce, APT has probably not included /etc/apache/conf.d/php4 in - your Apache 1.3 configuration. Please ensure that the following - line is present in your /etc/apache/httpd.conf file then - stop/start Apache: - - Example 2-16. This line activates PHP 4 into Apache -# Include /etc/apache/conf.d/ - - * If you installed an additional module and if its functions are not - available in your scripts, please ensure that the appropriate line - is present in your php.ini, as seen before. APT may fail during - the installation of the additional module, due to a confusing - debconf configuration. - _________________________________________________________________ - -Chapter 3. Installation on Mac OS X - - This section contains notes and hints specific to installing PHP on - Mac OS X. There are two slightly different versions of Mac OS X, - Client and Server, our manual deals with installing PHP on both - systems. Note that PHP is not available for MacOS 9 and earlier - versions. - _________________________________________________________________ - -Using Packages - - There are a few pre-packaged and pre-compiled versions of PHP for Mac - OS X. This can help in setting up a standard configuration, but if you - need to have a different set of features (such as a secure server, or - a different database driver), you may need to build PHP and/or your - web server yourself. If you are unfamiliar with building and compiling - your own software, it's worth checking whether somebody has already - built a packaged version of PHP with the features you need. - _________________________________________________________________ - -Compiling for OS X Server - - Mac OS X Server install. - - 1. Get the latest distributions of Apache and PHP. - 2. Untar them, and run the configure program on Apache like so. - -./configure --exec-prefix=/usr \ ---localstatedir=/var \ ---mandir=/usr/share/man \ ---libexecdir=/System/Library/Apache/Modules \ ---iconsdir=/System/Library/Apache/Icons \ ---includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \ ---enable-shared=max \ ---enable-module=most \ ---target=apache - - 3. If you want the compiler to do some optimization, you may also - want to add this line: - -setenv OPTIM=-O2 - - 4. Next, go to the PHP 4 source directory and configure it. - -./configure --prefix=/usr \ - --sysconfdir=/etc \ - --localstatedir=/var \ - --mandir=/usr/share/man \ - --with-xml \ - --with-apache=/src/apache_1.3.12 - - If you have any other additions (MySQL, GD, etc.), be sure to add - them here. For the --with-apache string, put in the path to your - apache source directory, for example /src/apache_1.3.12. - 5. Type make and make install. This will add a directory to your - Apache source directory under src/modules/php4. - 6. Now, reconfigure Apache to build in PHP 4. - -./configure --exec-prefix=/usr \ ---localstatedir=/var \ ---mandir=/usr/share/man \ ---libexecdir=/System/Library/Apache/Modules \ ---iconsdir=/System/Library/Apache/Icons \ ---includedir=/System/Library/Frameworks/Apache.framework/Versions/1.3/Headers \ ---enable-shared=max \ ---enable-module=most \ ---target=apache \ ---activate-module=src/modules/php4/libphp4.a - - You may get a message telling you that libmodphp4.a is out of - date. If so, go to the src/modules/php4 directory inside your - Apache source directory and run this command: ranlib libmodphp4.a. - Then go back to the root of the Apache source directory and run - the above configure command again. That'll bring the link table up - to date. Run make and make install again. - 7. Copy and rename the php.ini-dist file to your bin directory from - your PHP 4 source directory: cp php.ini-dist - /usr/local/bin/php.ini or (if your don't have a local directory) - cp php.ini-dist /usr/bin/php.ini. - _________________________________________________________________ - -Compiling for MacOS X Client - - The following instructions will help you install a PHP module for the - Apache web server included in MacOS X. This version includes support - for the MySQL and PostgreSQL databases. These instructions are - graciously provided by Marc Liyanage. - - Warning - - Be careful when you do this, you could screw up your Apache web - server! - - Do this to install: - - 1. Open a terminal window. - 2. Type wget - http://www.diax.ch/users/liyanage/software/macosx/libphp4.so.gz, - wait for the download to finish. - 3. Type gunzip libphp4.so.gz. - 4. Type sudo apxs -i -a -n php4 libphp4.so - 5. Now type sudo open -a TextEdit /etc/httpd/httpd.conf. TextEdit - will open with the web server configuration file. Locate these two - lines towards the end of the file: (Use the Find command) - -#AddType application/x-httpd-php .php -#AddType application/x-httpd-php-source .phps - - Remove the two hash marks (#), then save the file and quit - TextEdit. - 6. Finally, type sudo apachectl graceful to restart the web server. - - PHP should now be up and running. You can test it by dropping a file - into your Sites folder which is called test.php. Into that file, write - this line: <?php phpinfo() ?>. - - Now open up 127.0.0.1/~your_username/test.php in your web browser. You - should see a status table with information about the PHP module. - _________________________________________________________________ - -Chapter 4. Installation of PECL extensions - -Introduction to PECL Installations - - PECL is a repository of PHP extensions that are made available to you - via the PEAR packaging system. This section of the manual is intended - to demonstrate how to obtain and install PECL extensions. - - These instructions assume /your/phpsrcdir/ is the path to the PHP - source distribution, and that extname is the name of the PECL - extension. Adjust accordingly. These instructions also assume a - familiarity with the pear command. - - To be useful, a shared extension must be built, installed, and loaded. - The methods described below provide you with various instructions on - how to build and install the extensions, but they do not automatically - load them. Extensions can be loaded by adding an extension directive. - To this php.ini file, or through the use of the dl() function. - - When building PHP modules, it's important to have known-good versions - of the required tools (autoconf, automake, libtool, etc.) See the - Anonymous CVS Instructions for details on the required tools, and - required versions. - _________________________________________________________________ - -Downloading PECL extensions - - There are several options for downloading PECL extensions, such as: - - * http://pecl.php.net - The PECL web site contains information about the different - extensions that are offered by the PHP Development Team. The - information available here includes: ChangeLog, release notes, - requirements and other similar details. - * pear download extname - PECL extensions that have releases listed on the PECL web site are - available for download and installation using the pear command. - Specific revisions may also be specified. - * CVS - Most PECL extensions also reside in CVS. A web-based view may be - seen at http://cvs.php.net/pecl/. To download straight from CVS, - the following sequence of commands may be used. Note that phpfi is - the password for user cvsread: - -$ cvs -d:pserver:cvsread@cvs.php.net:/repository login -$ cvs -d:pserver:cvsread@cvs.php.net:/repository co pecl/extname - - * Windows downloads - Windows users may find compiled PECL binaries by downloading the - Collection of PECL modules from the PHP Downloads page, and by - retrieving a PECL Snapshot. To compile PHP under Windows, read the - Win32 Build README. - _________________________________________________________________ - -PECL for Windows users - - As with any other PHP extension DLL, installation is as simple as - copying the PECL extension DLLs into the extension_dir folder and - loading them from php.ini. For example, add the following line to your - php.ini: - - extension=php_extname.dll - - After doing this, restart the web server. - _________________________________________________________________ - -Compiling shared PECL extensions with PEAR - - PEAR makes it easy to create shared PHP extensions. Using the pear - command, do the following: - - $ pear install extname - - This will download the source for extname, compile, and install - extname.so into your extension_dir. extname.so may then be loaded via - php.ini - - By default, the pear command will not install packages that are marked - with the alpha or beta state. If no stable packages are available, you - may install a beta package using the following command: - - $ pear install extname-beta - - You may also install a specific version using this variant: - - $ pear install extname-0.1 - _________________________________________________________________ - -Compiling shared PECL extensions with phpize - - Sometimes, using the pear installer is not an option. This could be - because you're behind a firewall, or it could be because the extension - you want to install is not available as a PEAR compatible package, - such as unreleased extensions from CVS. If you need to build such an - extension, you can use the lower-level build tools to perform the - build manually. - - The phpize command is used to prepare the build environment for a PHP - extension. In the following sample, the sources for an extension are - in a directory named extname: - -$ cd extname -$ phpize -$ ./configure -$ make -# make install - - A successful install will have created extname.so and put it into the - PHP extensions directory. You'll need to and adjust php.ini and add an - extension=extname.so line before you can use the extension. - _________________________________________________________________ - -Compiling PECL extensions statically into PHP - - You might find that you need to build a PECL extension statically into - your PHP binary. To do this, you'll need to place the extension source - under the php-src/ext/ directory and tell the PHP build system to - regenerate its configure script. - -$ cd /your/phpsrcdir/ext -$ pear download extname -$ gzip -d < extname.tgz | tar -xvf - -$ mv extname-x.x.x extname - - This will result in the following directory: - - /your/phpsrcdir/ext/extname - - From here, force PHP to rebuild the configure script, and then build - PHP as normal: - -$ cd /your/phpsrcdir -$ rm configure -$ ./buildconf --force -$ ./configure --help -$ ./configure --with-extname --enable-someotherext --with-foobar -$ make -$ make install - - Note: To run the 'buildconf' script you need autoconf 2.13 and - automake 1.4+ (newer versions of autoconf may work, but are not - supported). - - Whether --enable-extname or --with-extname is used depends on the - extension. Typically an extension that does not require external - libraries uses --enable. To be sure, run the following after - buildconf: - - $ ./configure --help | grep extname - _________________________________________________________________ - -Chapter 5. Problems? - -Read the FAQ - - Some problems are more common than others. The most common ones are - listed in the PHP FAQ, part of this manual. - _________________________________________________________________ - -Other problems - - If you are still stuck, someone on the PHP installation mailing list - may be able to help you. You should check out the archive first, in - case someone already answered someone else who had the same problem as - you. The archives are available from the support page on - http://www.php.net/support.php. To subscribe to the PHP installation - mailing list, send an empty mail to - php-install-subscribe@lists.php.net. The mailing list address is - php-install@lists.php.net. - - If you want to get help on the mailing list, please try to be precise - and give the necessary details about your environment (which operating - system, what PHP version, what web server, if you are running PHP as - CGI or a server module, safe mode, etc...), and preferably enough code - to make others able to reproduce and test your problem. - _________________________________________________________________ - -Bug reports - - If you think you have found a bug in PHP, please report it. The PHP - developers probably don't know about it, and unless you report it, - chances are it won't be fixed. You can report bugs using the - bug-tracking system at http://bugs.php.net/. Please do not send bug - reports in mailing list or personal letters. The bug system is also - suitable to submit feature requests. - - Read the How to report a bug document before submitting any bug - reports! - _________________________________________________________________ - -Chapter 6. Runtime Configuration - -The configuration file - - The configuration file (called php3.ini in PHP 3, and simply php.ini - as of PHP 4) is read when PHP starts up. For the server module - versions of PHP, this happens only once when the web server is - started. For the CGI and CLI version, it happens on every invocation. - - php.ini is searched in these locations (in order): - - * SAPI module specific location (PHPIniDir directive in Apache 2, -c - command line option in CGI and CLI, php_ini parameter in NSAPI, - PHP_INI_PATH environment variable in THTTPD) - * HKEY_LOCAL_MACHINE\SOFTWARE\PHP\IniFilePath (Windows Registry - location) - * The PHPRC environment variable - * Current working directory (for CLI) - * The web server's directory (for SAPI modules), or directory of PHP - (otherwise in Windows) - * Windows directory (C:\windows or C:\winnt) (for Windows), or - --with-config-file-path compile time option - - If php-SAPI.ini exists (where SAPI is used SAPI, so the filename is - e.g. php-cli.ini or php-apache.ini), it's used instead of php.ini. - SAPI name can be determined by php_sapi_name(). - - Note: The Apache web server changes the directory to root at - startup causing PHP to attempt to read php.ini from the root - filesystem if it exists. - - The php.ini directives handled by extensions are documented - respectively on the pages of the extensions themselves. The list of - the core directives is available in the appendix. Probably not all PHP - directives are documented in the manual though. For a complete list of - directives available in your PHP version, please read your well - commented php.ini file. Alternatively, you may find the the latest - php.ini from CVS helpful too. - - Example 6-1. php.ini example -; any text on a line after an unquoted semicolon (;) is ignored -[php] ; section markers (text within square brackets) are also ignored -; Boolean values can be set to either: -; true, on, yes -; or false, off, no, none -register_globals = off -track_errors = yes - -; you can enclose strings in double-quotes -include_path = ".:/usr/local/lib/php" - -; backslashes are treated the same as any other character -include_path = ".;c:\php\lib" - - Since PHP 5.1.0, it is possible to refer to existing .ini variables - from within .ini files. Example: open_basedir = ${open_basedir} - ":/new/dir". - _________________________________________________________________ - -How to change configuration settings - -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 or virtualhost directives. - 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 or - virtualhost directives. - - Example 6-2. 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(). - _________________________________________________________________ - -Chapter 7. Installation FAQ - - This section holds common questions about the way to install PHP. PHP - is available for almost any OS (except maybe for MacOS before OSX), - and almost any web server. - - To install PHP, follow the instructions in the INSTALL file located in - the distribution. Windows users should also read the install.txt file. - There are also some helpful hints for Windows users here. - - 1. Why shouldn't I use Apache2 with a threaded MPM in a production - environment? - - 2. Unix/Windows: Where should my php.ini file be located? - 3. Unix: I installed PHP, but every time I load a document, I get the - message 'Document Contains No Data'! What's going on here? - - 4. Unix: I installed PHP using RPMS, but Apache isn't processing the - PHP pages! What's going on here? - - 5. Unix: I installed PHP 3 using RPMS, but it doesn't compile with the - database support I need! What's going on here? - - 6. Unix: I patched Apache with the FrontPage extensions patch, and - suddenly PHP stopped working. Is PHP incompatible with the - Apache FrontPage extensions? - - 7. Unix/Windows: I have installed PHP, but when I try to access a PHP - script file via my browser, I get a blank screen. - - 8. Unix/Windows: I have installed PHP, but when try to access a PHP - script file via my browser, I get a server 500 error. - - 9. Some operating systems: I have installed PHP without errors, but - when I try to start apache I get undefined symbol errors: - -[mybox:user /src/php4] root# apachectl configtest - apachectl: /usr/local/apache/bin/httpd Undefined symbols: - _compress - _uncompress - - 10. Windows: I have installed PHP, but when I to access a PHP script - file via my browser, I get the error: - -cgi error: - The specified CGI application misbehaved by not - returning a complete set of HTTP headers. - The headers it did return are: - - 11. Windows: I've followed all the instructions, but still can't get - PHP and IIS to work together! - - 12. When running PHP as CGI with IIS, PWS, OmniHTTPD or Xitami, I get - the following error: Security Alert! PHP CGI cannot be accessed - directly.. - - 13. How do I know if my php.ini is being found and read? It seems like - it isn't as my changes aren't being implemented. - - 14. How do I add my PHP directory to the PATH on Windows? - 15. How do I make the php.ini file available to PHP on windows? - 16. Is it possible to use Apache content negotiation (MultiViews - option) with PHP? - - 17. Is PHP limited to process GET and POST request methods only? - - 1. Why shouldn't I use Apache2 with a threaded MPM in a production - environment? - - PHP is glue. It is the glue used to build cool web applications by - sticking dozens of 3rd-party libraries together and making it all - appear as one coherent entity through an intuitive and easy to learn - language interface. The flexibility and power of PHP relies on the - stability and robustness of the underlying platform. It needs a - working OS, a working web server and working 3rd-party libraries to - glue together. When any of these stop working PHP needs ways to - identify the problems and fix them quickly. When you make the - underlying framework more complex by not having completely separate - execution threads, completely separate memory segments and a strong - sandbox for each request to play in, feet of clay are introduced into - PHP's system. - - If you feel you have to use a threaded MPM, look at a FastCGI - configuration where PHP is running in its own memory space. - - And finally, this warning against using a threaded MPM is not as - strong for Windows systems because most libraries on that platform - tend to be threadsafe. - - 2. Unix/Windows: Where should my php.ini file be located? - - By default on Unix it should be in /usr/local/lib which is - <install-path>/lib. Most people will want to change this at - compile-time with the --with-config-file-path flag. You would, for - example, set it with something like: - --with-config-file-path=/etc - - And then you would copy php.ini-dist from the distribution to - /etc/php.ini and edit it to make any local changes you want. - --with-config-file-scan-dir=PATH - - On Windows the default path for the php.ini file is the Windows - directory. If you're using the Apache webserver, php.ini is first - searched in the Apaches install directory, e.g. c:\program - files\apache group\apache. This way you can have different php.ini - files for different versions of Apache on the same machine. - - See also the chapter about the configuration file. - - 3. Unix: I installed PHP, but every time I load a document, I get the - message 'Document Contains No Data'! What's going on here? - - This probably means that PHP is having some sort of problem and is - core-dumping. Look in your server error log to see if this is the - case, and then try to reproduce the problem with a small test case. If - you know how to use 'gdb', it is very helpful when you can provide a - backtrace with your bug report to help the developers pinpoint the - problem. If you are using PHP as an Apache module try something like: - - * Stop your httpd processes - * gdb httpd - * Stop your httpd processes - * > run -X -f /path/to/httpd.conf - * Then fetch the URL causing the problem with your browser - * > run -X -f /path/to/httpd.conf - * If you are getting a core dump, gdb should inform you of this now - * type: bt - * You should include your backtrace in your bug report. This should - be submitted to http://bugs.php.net/ - - If your script uses the regular expression functions (ereg() and - friends), you should make sure that you compiled PHP and Apache with - the same regular expression package. This should happen automatically - with PHP and Apache 1.3.x - - 4. Unix: I installed PHP using RPMS, but Apache isn't processing the - PHP pages! What's going on here? - - Assuming you installed both Apache and PHP from RPM packages, you need - to uncomment or add some or all of the following lines in your - httpd.conf file: -# Extra Modules -AddModule mod_php.c -AddModule mod_php3.c -AddModule mod_perl.c - -# Extra Modules -LoadModule php_module modules/mod_php.so -LoadModule php3_module modules/libphp3.so # for PHP 3 -LoadModule php4_module modules/libphp4.so # for PHP 4 -LoadModule perl_module modules/libperl.so - - And add: -AddType application/x-httpd-php3 .php3 # for PHP 3 -AddType application/x-httpd-php .php # for PHP 4 - - ... to the global properties, or to the properties of the - VirtualDomain you want to have PHP support added to. - - 5. Unix: I installed PHP 3 using RPMS, but it doesn't compile with the - database support I need! What's going on here? - - Due to the way PHP 3 built, it is not easy to build a complete - flexible PHP RPM. This issue is addressed in PHP 4. For PHP 3, we - currently suggest you use the mechanism described in the - INSTALL.REDHAT file in the PHP distribution. If you insist on using an - RPM version of PHP 3, read on... - - The RPM packagers are setting up the RPMS to install without database - support to simplify installations and because RPMS use /usr/ instead - of the standard /usr/local/ directory for files. You need to tell the - RPM spec file which databases to support and the location of the - top-level of your database server. - - This example will explain the process of adding support for the - popular MySQL database server, using the mod installation for Apache. - - Of course all of this information can be adjusted for any database - server that PHP supports. We will assume you installed MySQL and - Apache completely with RPMS for this example as well. - - * First remove mod_php3 : - -rpm -e mod_php3 - - * Then get the source rpm and INSTALL it, NOT --rebuild - -rpm -Uvh mod_php3-3.0.5-2.src.rpm - - * Then edit the /usr/src/redhat/SPECS/mod_php3.spec file - In the %build section add the database support you want, and the - path. - For MySQL you would add --with-mysql=/usr The %build section will - look something like this: - -./configure --prefix=/usr \ ---with-apxs=/usr/sbin/apxs \ ---with-config-file-path=/usr/lib \ ---enable-debug=no \ ---enable-safe-mode \ ---with-exec-dir=/usr/bin \ ---with-mysql=/usr \ ---with-system-regex - - * Once this modification is made then build the binary rpm as - follows: - -rpm -bb /usr/src/redhat/SPECS/mod_php3.spec - - * Then install the rpm - -rpm -ivh /usr/src/redhat/RPMS/i386/mod_php3-3.0.5-2.i386.rpm - - Make sure you restart Apache, and you now have PHP 3 with MySQL - support using RPM's. Note that it is probably much easier to just - build from the distribution tarball of PHP 3 and follow the - instructions in INSTALL.REDHAT found in that distribution. - - 6. Unix: I patched Apache with the FrontPage extensions patch, and - suddenly PHP stopped working. Is PHP incompatible with the Apache - FrontPage extensions? - - No, PHP works fine with the FrontPage extensions. The problem is that - the FrontPage patch modifies several Apache structures, that PHP - relies on. Recompiling PHP (using 'make clean ; make') after the FP - patch is applied would solve the problem. - - 7. Unix/Windows: I have installed PHP, but when I try to access a PHP - script file via my browser, I get a blank screen. - - Do a 'view source' in the web browser and you will probably find that - you can see the source code of your PHP script. This means that the - web server did not send the script to PHP for interpretation. - Something is wrong with the server configuration - double check the - server configuration against the PHP installation instructions. - - 8. Unix/Windows: I have installed PHP, but when try to access a PHP - script file via my browser, I get a server 500 error. - - Something went wrong when the server tried to run PHP. To get to see a - sensible error message, from the command line, change to the directory - containing the PHP executable (php.exe on Windows) and run php -i. If - PHP has any problems running, then a suitable error message will be - displayed which will give you a clue as to what needs to be done next. - If you get a screen full of HTML codes (the output of the phpinfo() - function) then PHP is working, and your problem may be related to your - server configuration which you should double check. - - 9. Some operating systems: I have installed PHP without errors, but - when I try to start apache I get undefined symbol errors: -[mybox:user /src/php4] root# apachectl configtest - apachectl: /usr/local/apache/bin/httpd Undefined symbols: - _compress - _uncompress - - This has actually nothing to do with PHP, but with the MySQL client - libraries. Some need --with-zlib, others do not. This is also covered - in the MySQL FAQ. - - 10. Windows: I have installed PHP, but when I to access a PHP script - file via my browser, I get the error: -cgi error: - The specified CGI application misbehaved by not - returning a complete set of HTTP headers. - The headers it did return are: - - This error message means that PHP failed to output anything at all. To - get to see a sensible error message, from the command line, change to - the directory containing the PHP executable (php.exe on Windows) and - run php -i. If PHP has any problems running, then a suitable error - message will be displayed which will give you a clue as to what needs - to be done next. If you get a screen full of HTML codes (the output of - the phpinfo() function) then PHP is working. - - Once PHP is working at the command line, try accessing the script via - the browser again. If it still fails then it could be one of the - following: - - * File permissions on your PHP script, php.exe, php4ts.dll, php.ini - or any PHP extensions you are trying to load are such that the - anonymous internet user ISUR_<machinename> cannot access them. - * The script file does not exist (or possibly isn't where you think - it is relative to your web root directory). Note that for IIS you - can trap this error by ticking the 'check file exists' box when - setting up the script mappings in the Internet Services Manager. - If a script file does not exist then the server will return a 404 - error instead. There is also the additional benefit that IIS will - do any authentication required for you based on the NTLanMan - permissions on your script file. - - 11. Windows: I've followed all the instructions, but still can't get - PHP and IIS to work together! - - Make sure any user who needs to run a PHP script has the rights to run - php.exe! IIS uses an anonymous user which is added at the time IIS is - installed. This user needs rights to php.exe. Also, any authenticated - user will also need rights to execute php.exe. And for IIS4 you need - to tell it that PHP is a script engine. Also, you will want to read - this faq. - - 12. When running PHP as CGI with IIS, PWS, OmniHTTPD or Xitami, I get - the following error: Security Alert! PHP CGI cannot be accessed - directly.. - - You must set the cgi.force_redirect directive to 0. It defaults to 1 - so be sure the directive isn't commented out (with a ;). Like all - directives, this is set in php.ini - - Because the default is 1, it's critical that you're 100% sure that the - correct php.ini file is being read. Read this faq for details. - - 13. How do I know if my php.ini is being found and read? It seems like - it isn't as my changes aren't being implemented. - - To be sure your php.ini is being read by PHP, make a call to phpinfo() - and near the top will be a listing called Configuration File - (php.ini). This will tell you where PHP is looking for php.ini and - whether or not it's being read. If just a directory PATH exists than - it's not being read and you should put your php.ini in that directory. - If php.ini is included within the PATH than it is being read. - - If php.ini is being read and you're running PHP as a module, then be - sure to restart your web server after making changes to php.ini - - 14. How do I add my PHP directory to the PATH on Windows? - - On Windows NT, 2000, XP and 2003: - - * Go to Control Panel and open the System icon (Start -> Settings -> - Control Panel -> System, or just Start -> Control Panel -> System - for Windows XP/2003) - * Go to the Advanced tab - * Click on the 'Environment Variables' button - * Look into the 'System Variables' pane - * Find the Path entry (you may need to scroll to find it) - * Double click on the Path entry - * Enter your PHP directory ant the end, including ';' before (e.g. - ;C:\php) - * Press OK and restart your computer - - On Windows 98/Me you need to edit the autoexec.bat file: - - * Open the Notepad (Start -> Run and enter notepad) - * Open the C:\autoexec.bat file - * Locate the line with PATH=C:\WINDOWS;C:\WINDOWS\COMMAND;..... and - add: ;C:\php to the end of the line - * Save the file and restart your computer - - Note: Be sure to reboot after following the steps above to ensure - that the PATH changes are applied. - - The PHP manual used to promote the copying of files into the Windows - system directory, this is because this directory (C:\Windows, - C:\WINNT, etc.) is by default in the systems PATH. Copying files into - the Windows system directory has long since been deprecated and may - cause problems. - - 15. How do I make the php.ini file available to PHP on windows? - - There are several ways of doing this. If you are using Apache, read - their installation specific instructions (Apache 1, Apache 2), - otherwise you must set the PHPRC environment variable: - - On Windows NT, 2000, XP and 2003: - - * Go to Control Panel and open the System icon (Start -> Settings -> - Control Panel -> System, or just Start -> Control Panel -> System - for Windows XP/2003) - * Go to the Advanced tab - * Click on the 'Environment Variables' button - * Look into the 'System variables' pane - * Click on 'New' and enter 'PHPRC' as the variable name and the - directory where php.ini is located as the variable value (e.g. - C:\php) - * Press OK and restart your computer - - On Windows 98/Me you need to edit the autoexec.bat file: - - * Open the Notepad (Start -> Run and enter notepad) - * Open the C:\autoexec.bat file - * Add a new line to the end of the file: set PHPRC=C:\php (replace - C:\php with the directory where php.ini is located). Please note - that the path cannot contain spaces. For instance, if you have - installed PHP in C:\Program Files\PHP, you would enter - C:\PROGRA~1\PHP instead. - * Save the file and restart your computer - - 16. Is it possible to use Apache content negotiation (MultiViews - option) with PHP? - - If links to PHP files include extension, everything works perfect. - This FAQ is only for the case when links to PHP files don't include - extension and you want to use content negotiation to choose PHP files - from URL with no extension. In this case, replace the line AddType - application/x-httpd-php .php with: -# PHP 4 -AddHandler php-script php -AddType text/html php - -# PHP 5 -AddHandler php5-script php -AddType text/html php - - This solution doesn't work for Apache 1 as PHP module doesn't catch - php-script. - - 17. Is PHP limited to process GET and POST request methods only? - - No, it is possible to handle any request method, e.g. CONNECT. Proper - response status can be sent with header(). If only GET and POST - methods should be handled, it can be achieved with this Apache - configuration: -<LimitExcept GET POST> -Deny from all -</LimitExcept> |