embedaddon/php/INSTALL - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / INSTALL
Revision 1.1.1.1 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Tue Feb 21 23:47:51 2012 UTC (12 years, 4 months ago) by misho
Branches: php, MAIN
CVS tags: v5_4_3elwix, v5_4_17p0, v5_3_10, HEAD

php

1: __________________________________________________________________ 2: 3: Installing PHP 4: __________________________________________________________________ 5: 6: * General Installation Considerations 7: * Installation on Unix systems 8: + Apache 1.3.x on Unix systems 9: + Apache 2.x on Unix systems 10: + Lighttpd 1.4 on Unix systems 11: + Sun, iPlanet and Netscape servers on Sun Solaris 12: + CGI and command line setups 13: + HP-UX specific installation notes 14: + OpenBSD installation notes 15: + Solaris specific installation tips 16: + Debian GNU/Linux installation notes 17: * Installation on Mac OS X 18: + Using Packages 19: + Using the bundled PHP 20: + Compiling PHP on Mac OS X 21: * Installation of PECL extensions 22: + Introduction to PECL Installations 23: + Downloading PECL extensions 24: + Installing a PHP extension on Windows 25: + Compiling shared PECL extensions with the pecl command 26: + Compiling shared PECL extensions with phpize 27: + Compiling PECL extensions statically into PHP 28: * Problems? 29: + Read the FAQ 30: + Other problems 31: + Bug reports 32: * Runtime Configuration 33: + The configuration file 34: + .user.ini files 35: + Where a configuration setting may be set 36: + How to change configuration settings 37: * Installation 38: __________________________________________________________________ 39: 40: __________________________________________________________________ 41: 42: Preface 43: 44: These installation instructions were generated from the HTML version of 45: the PHP Manual so formatting and linking have been altered. See the 46: online and updated version at: http://php.net/install.unix 47: __________________________________________________________________ 48: 49: General Installation Considerations 50: 51: Before starting the installation, first you need to know what do you 52: want to use PHP for. There are three main fields you can use PHP, as 53: described in the What can PHP do? section: 54: * Websites and web applications (server-side scripting) 55: * Command line scripting 56: * Desktop (GUI) applications 57: 58: For the first and most common form, you need three things: PHP itself, 59: a web server and a web browser. You probably already have a web 60: browser, and depending on your operating system setup, you may also 61: have a web server (e.g. Apache on Linux and MacOS X; IIS on Windows). 62: You may also rent webspace at a company. This way, you don't need to 63: set up anything on your own, only write your PHP scripts, upload it to 64: the server you rent, and see the results in your browser. 65: 66: In case of setting up the server and PHP on your own, you have two 67: choices for the method of connecting PHP to the server. For many 68: servers PHP has a direct module interface (also called SAPI). These 69: servers include Apache, Microsoft Internet Information Server, Netscape 70: and iPlanet servers. Many other servers have support for ISAPI, the 71: Microsoft module interface (OmniHTTPd for example). If PHP has no 72: module support for your web server, you can always use it as a CGI or 73: FastCGI processor. This means you set up your server to use the CGI 74: executable of PHP to process all PHP file requests on the server. 75: 76: If you are also interested to use PHP for command line scripting (e.g. 77: write scripts autogenerating some images for you offline, or processing 78: text files depending on some arguments you pass to them), you always 79: need the command line executable. For more information, read the 80: section about writing command line PHP applications. In this case, you 81: need no server and no browser. 82: 83: With PHP you can also write desktop GUI applications using the PHP-GTK 84: extension. This is a completely different approach than writing web 85: pages, as you do not output any HTML, but manage windows and objects 86: within them. For more information about PHP-GTK, please » visit the 87: site dedicated to this extension. PHP-GTK is not included in the 88: official PHP distribution. 89: 90: From now on, this section deals with setting up PHP for web servers on 91: Unix and Windows with server module interfaces and CGI executables. You 92: will also find information on the command line executable in the 93: following sections. 94: 95: PHP source code and binary distributions for Windows can be found at » 96: http://www.php.net/downloads.php. We recommend you to choose a » mirror 97: nearest to you for downloading the distributions. 98: __________________________________________________________________ 99: __________________________________________________________________ 100: 101: Installation on Unix systems 102: 103: Table of Contents 104: 105: * Apache 1.3.x on Unix systems 106: * Apache 2.x on Unix systems 107: * Lighttpd 1.4 on Unix systems 108: * Sun, iPlanet and Netscape servers on Sun Solaris 109: * CGI and command line setups 110: * HP-UX specific installation notes 111: * OpenBSD installation notes 112: * Solaris specific installation tips 113: * Debian GNU/Linux installation notes 114: 115: This section will guide you through the general configuration and 116: installation of PHP on Unix systems. Be sure to investigate any 117: sections specific to your platform or web server before you begin the 118: process. 119: 120: As our manual outlines in the General Installation Considerations 121: section, we are mainly dealing with web centric setups of PHP in this 122: section, although we will cover setting up PHP for command line usage 123: as well. 124: 125: There are several ways to install PHP for the Unix platform, either 126: with a compile and configure process, or through various pre-packaged 127: methods. This documentation is mainly focused around the process of 128: compiling and configuring PHP. Many Unix like systems have some sort of 129: package installation system. This can assist in setting up a standard 130: configuration, but if you need to have a different set of features 131: (such as a secure server, or a different database driver), you may need 132: to build PHP and/or your web server. If you are unfamiliar with 133: building and compiling your own software, it is worth checking to see 134: whether somebody has already built a packaged version of PHP with the 135: features you need. 136: 137: Prerequisite knowledge and software for compiling: 138: * Basic Unix skills (being able to operate "make" and a C compiler) 139: * An ANSI C compiler 140: * A web server 141: * Any module specific components (such as GD, PDF libs, etc.) 142: 143: When building directly from SVN sources or after custom modifications 144: you might also need: 145: * autoconf: 2.13 146: * automake: 1.4+ 147: * libtool: 1.4.x+ (except 1.4.2) 148: * re2c: Version 0.13.4 or newer 149: * flex: Version 2.5.4 (for PHP <= 5.2) 150: * bison: Version 1.28 (preferred), 1.35, or 1.75 151: 152: The initial PHP setup and configuration process is controlled by the 153: use of the command line options of the configure script. You could get 154: a list of all available options along with short explanations running 155: ./configure --help. Our manual documents the different options 156: separately. You will find the core options in the appendix, while the 157: different extension specific options are descibed on the reference 158: pages. 159: 160: When PHP is configured, you are ready to build the module and/or 161: executables. The command make should take care of this. If it fails and 162: you can't figure out why, see the Problems section. 163: __________________________________________________________________ 164: 165: Apache 1.3.x on Unix systems 166: 167: This section contains notes and hints specific to Apache installs of 168: PHP on Unix platforms. We also have instructions and notes for Apache 2 169: on a separate page. 170: 171: You can select arguments to add to the configure on line 10 below from 172: the list of core configure options and from extension specific options 173: described at the respective places in the manual. The version numbers 174: have been omitted here, to ensure the instructions are not incorrect. 175: You will need to replace the 'xxx' here with the correct values from 176: your files. 177: 178: Example #1 Installation Instructions (Apache Shared Module Version) for 179: PHP 180: 1. gunzip apache_xxx.tar.gz 181: 2. tar -xvf apache_xxx.tar 182: 3. gunzip php-xxx.tar.gz 183: 4. tar -xvf php-xxx.tar 184: 5. cd apache_xxx 185: 6. ./configure --prefix=/www --enable-module=so 186: 7. make 187: 8. make install 188: 9. cd ../php-xxx 189: 190: 10. Now, configure your PHP. This is where you customize your PHP 191: with various options, like which extensions will be enabled. Do a 192: ./configure --help for a list of available options. In our example 193: we'll do a simple configure with Apache 1 and MySQL support. Your 194: path to apxs may differ from our example. 195: 196: ./configure --with-mysql --with-apxs=/www/bin/apxs 197: 198: 11. make 199: 12. make install 200: 201: If you decide to change your configure options after installation, 202: you only need to repeat the last three steps. You only need to 203: restart apache for the new module to take effect. A recompile of 204: Apache is not needed. 205: 206: Note that unless told otherwise, 'make install' will also install PEAR, 207: various PHP tools such as phpize, install the PHP CLI, and more. 208: 209: 13. Setup your php.ini file: 210: 211: cp php.ini-development /usr/local/lib/php.ini 212: 213: You may edit your .ini file to set PHP options. If you prefer your 214: php.ini in another location, use --with-config-file-path=/some/path in 215: step 10. 216: 217: If you instead choose php.ini-production, be certain to read the list 218: of changes within, as they affect how PHP behaves. 219: 220: 14. Edit your httpd.conf to load the PHP module. The path on the right hand 221: side of the LoadModule statement must point to the path of the PHP 222: module on your system. The make install from above may have already 223: added this for you, but be sure to check. 224: 225: LoadModule php5_module libexec/libphp5.so 226: 227: 15. And in the AddModule section of httpd.conf, somewhere under the 228: ClearModuleList, add this: 229: 230: AddModule mod_php5.c 231: 232: 16. Tell Apache to parse certain extensions as PHP. For example, 233: let's have Apache parse the .php extension as PHP. You could 234: have any extension(s) parse as PHP by simply adding more, with 235: each separated by a space. We'll add .phtml to demonstrate. 236: 237: AddType application/x-httpd-php .php .phtml 238: 239: It's also common to setup the .phps extension to show highlighted PHP 240: source, this can be done with: 241: 242: AddType application/x-httpd-php-source .phps 243: 244: 17. Use your normal procedure for starting the Apache server. (You must 245: stop and restart the server, not just cause the server to reload by 246: using a HUP or USR1 signal.) 247: 248: Alternatively, to install PHP as a static object: 249: 250: Example #2 Installation Instructions (Static Module Installation for 251: Apache) for PHP 252: 1. gunzip -c apache_1.3.x.tar.gz | tar xf - 253: 2. cd apache_1.3.x 254: 3. ./configure 255: 4. cd .. 256: 257: 5. gunzip -c php-5.x.y.tar.gz | tar xf - 258: 6. cd php-5.x.y 259: 7. ./configure --with-mysql --with-apache=../apache_1.3.x 260: 8. make 261: 9. make install 262: 263: 10. cd ../apache_1.3.x 264: 265: 11. ./configure --prefix=/www --activate-module=src/modules/php5/libphp5.a 266: (The above line is correct! Yes, we know libphp5.a does not exist at this 267: stage. It isn't supposed to. It will be created.) 268: 269: 12. make 270: (you should now have an httpd binary which you can copy to your Apache bin d 271: ir if 272: it is your first install then you need to "make install" as well) 273: 274: 13. cd ../php-5.x.y 275: 14. cp php.ini-development /usr/local/lib/php.ini 276: 277: 15. You can edit /usr/local/lib/php.ini file to set PHP options. 278: Edit your httpd.conf or srm.conf file and add: 279: AddType application/x-httpd-php .php 280: 281: Depending on your Apache install and Unix variant, there are many 282: possible ways to stop and restart the server. Below are some typical 283: lines used in restarting the server, for different apache/unix 284: installations. You should replace /path/to/ with the path to these 285: applications on your systems. 286: 287: Example #3 Example commands for restarting Apache 288: 1. Several Linux and SysV variants: 289: /etc/rc.d/init.d/httpd restart 290: 291: 2. Using apachectl scripts: 292: /path/to/apachectl stop 293: /path/to/apachectl start 294: 295: 3. httpdctl and httpsdctl (Using OpenSSL), similar to apachectl: 296: /path/to/httpsdctl stop 297: /path/to/httpsdctl start 298: 299: 4. Using mod_ssl, or another SSL server, you may want to manually 300: stop and start: 301: /path/to/apachectl stop 302: /path/to/apachectl startssl 303: 304: The locations of the apachectl and http(s)dctl binaries often vary. If 305: your system has locate or whereis or which commands, these can assist 306: you in finding your server control programs. 307: 308: Different examples of compiling PHP for apache are as follows: 309: ./configure --with-apxs --with-pgsql 310: 311: This will create a libphp5.so shared library that is loaded into Apache 312: using a LoadModule line in Apache's httpd.conf file. The PostgreSQL 313: support is embedded into this library. 314: 315: ./configure --with-apxs --with-pgsql=shared 316: 317: This will create a libphp5.so shared library for Apache, but it will 318: also create a pgsql.so shared library that is loaded into PHP either by 319: using the extension directive in php.ini file or by loading it 320: explicitly in a script using the dl() function. 321: 322: ./configure --with-apache=/path/to/apache_source --with-pgsql 323: 324: This will create a libmodphp5.a library, a mod_php5.c and some 325: accompanying files and copy this into the src/modules/php5 directory in 326: the Apache source tree. Then you compile Apache using 327: --activate-module=src/modules/php5/libphp5.a and the Apache build 328: system will create libphp5.a and link it statically into the httpd 329: binary. The PostgreSQL support is included directly into this httpd 330: binary, so the final result here is a single httpd binary that includes 331: all of Apache and all of PHP. 332: 333: ./configure --with-apache=/path/to/apache_source --with-pgsql=shared 334: 335: Same as before, except instead of including PostgreSQL support directly 336: into the final httpd you will get a pgsql.so shared library that you 337: can load into PHP from either the php.ini file or directly using dl(). 338: 339: When choosing to build PHP in different ways, you should consider the 340: advantages and drawbacks of each method. Building as a shared object 341: will mean that you can compile apache separately, and don't have to 342: recompile everything as you add to, or change, PHP. Building PHP into 343: apache (static method) means that PHP will load and run faster. For 344: more information, see the Apache » web page on DSO support. 345: 346: Note: 347: 348: Apache's default httpd.conf currently ships with a section that 349: looks like this: 350: 351: User nobody 352: Group "#-1" 353: 354: Unless you change that to "Group nogroup" or something like that 355: ("Group daemon" is also very common) PHP will not be able to open 356: files. 357: 358: Note: 359: 360: Make sure you specify the installed version of apxs when using 361: --with-apxs=/path/to/apxs . You must NOT use the apxs version that 362: is in the apache sources but the one that is actually installed on 363: your system. 364: __________________________________________________________________ 365: __________________________________________________________________ 366: 367: Apache 2.x on Unix systems 368: 369: This section contains notes and hints specific to Apache 2.x installs 370: of PHP on Unix systems. 371: Warning 372: 373: We do not recommend using a threaded MPM in production with Apache 2. 374: Use the prefork MPM, which is the default MPM with Apache 2.0 and 2.2. 375: For information on why, read the related FAQ entry on using Apache2 376: with a threaded MPM 377: 378: The » Apache Documentation is the most authoritative source of 379: information on the Apache 2.x server. More information about 380: installation options for Apache may be found there. 381: 382: The most recent version of Apache HTTP Server may be obtained from » 383: Apache download site, and a fitting PHP version from the above 384: mentioned places. This quick guide covers only the basics to get 385: started with Apache 2.x and PHP. For more information read the » Apache 386: Documentation. The version numbers have been omitted here, to ensure 387: the instructions are not incorrect. In the examples below, 'NN' should 388: be replaced with the specific version of Apache being used. 389: 390: There are currently two versions of Apache 2.x - there's 2.0 and 2.2. 391: While there are various reasons for choosing each, 2.2 is the current 392: latest version, and the one that is recommended, if that option is 393: available to you. However, the instructions here will work for either 394: 2.0 or 2.2. 395: 1. Obtain the Apache HTTP server from the location listed above, and 396: unpack it: 397: gzip -d httpd-2_x_NN.tar.gz 398: tar -xf httpd-2_x_NN.tar 399: 400: 2. Likewise, obtain and unpack the PHP source: 401: gunzip php-NN.tar.gz 402: tar -xf php-NN.tar 403: 404: 3. Build and install Apache. Consult the Apache install documentation 405: for more details on building Apache. 406: cd httpd-2_x_NN 407: ./configure --enable-so 408: make 409: make install 410: 411: 4. Now you have Apache 2.x.NN available under /usr/local/apache2, 412: configured with loadable module support and the standard MPM 413: prefork. To test the installation use your normal procedure for 414: starting the Apache server, e.g.: 415: /usr/local/apache2/bin/apachectl start 416: 417: and stop the server to go on with the configuration for PHP: 418: /usr/local/apache2/bin/apachectl stop 419: 420: 5. Now, configure and build PHP. This is where you customize PHP with 421: various options, like which extensions will be enabled. Run 422: ./configure --help for a list of available options. In our example 423: we'll do a simple configure with Apache 2 and MySQL support. 424: If you built Apache from source, as described above, the below 425: example will match your path for apxs, but if you installed Apache 426: some other way, you'll need to adjust the path to apxs accordingly. 427: Note that some distros may rename apxs to apxs2. 428: cd ../php-NN 429: ./configure --with-apxs2=/usr/local/apache2/bin/apxs --with-mysql 430: make 431: make install 432: 433: If you decide to change your configure options after installation, 434: you'll need to re-run the configure, make, and make install steps. 435: You only need to restart apache for the new module to take effect. 436: A recompile of Apache is not needed. 437: Note that unless told otherwise, 'make install' will also install 438: PEAR, various PHP tools such as phpize, install the PHP CLI, and 439: more. 440: 6. Setup your php.ini 441: cp php.ini-development /usr/local/lib/php.ini 442: 443: You may edit your .ini file to set PHP options. If you prefer 444: having php.ini in another location, use 445: --with-config-file-path=/some/path in step 5. 446: If you instead choose php.ini-production, be certain to read the 447: list of changes within, as they affect how PHP behaves. 448: 7. Edit your httpd.conf to load the PHP module. The path on the right 449: hand side of the LoadModule statement must point to the path of the 450: PHP module on your system. The make install from above may have 451: already added this for you, but be sure to check. 452: LoadModule php5_module modules/libphp5.so 453: 8. Tell Apache to parse certain extensions as PHP. For example, let's 454: have Apache parse .php files as PHP. Instead of only using the 455: Apache AddType directive, we want to avoid potentially dangerous 456: uploads and created files such as exploit.php.jpg from being 457: executed as PHP. Using this example, you could have any 458: extension(s) parse as PHP by simply adding them. We'll add .php to 459: demonstrate. 460: <FilesMatch \.php$> 461: SetHandler application/x-httpd-php 462: </FilesMatch> 463: Or, if we wanted to allow .php, .php2, .php3, .php4, .php5, .php6, 464: and .phtml files to be executed as PHP, but nothing else, we'd use 465: this: 466: <FilesMatch "\.ph(p[2-6]?|tml)$"> 467: SetHandler application/x-httpd-php 468: </FilesMatch> 469: And to allow .phps files to be handled by the php source filter, 470: and displayed as syntax-highlighted source code, use this: 471: <FilesMatch "\.phps$"> 472: SetHandler application/x-httpd-php-source 473: </FilesMatch> 474: mod_rewrite may be used To allow any arbitrary .php file to be 475: displayed as syntax-highlighted source code, without having to 476: rename or copy it to a .phps file: 477: RewriteEngine On 478: RewriteRule (.*\.php)s$ $1 [H=application/x-httpd-php-source] 479: The php source filter should not be enabled on production systems, 480: where it may expose confidential or otherwise sensitive information 481: embedded in source code. 482: 9. Use your normal procedure for starting the Apache server, e.g.: 483: /usr/local/apache2/bin/apachectl start 484: 485: OR 486: service httpd restart 487: 488: Following the steps above you will have a running Apache2 web server 489: with support for PHP as a SAPI module. Of course there are many more 490: configuration options available Apache and PHP. For more information 491: type ./configure --help in the corresponding source tree. 492: 493: Apache may be built multithreaded by selecting the worker MPM, rather 494: than the standard prefork MPM, when Apache is built. This is done by 495: adding the following option to the argument passed to ./configure, in 496: step 3 above: 497: --with-mpm=worker 498: 499: This should not be undertaken without being aware of the consequences 500: of this decision, and having at least a fair understanding of the 501: implications. The Apache documentation regarding » MPM-Modules 502: discusses MPMs in a great deal more detail. 503: 504: Note: 505: 506: The Apache MultiViews FAQ discusses using multiviews with PHP. 507: 508: Note: 509: 510: To build a multithreaded version of Apache, the target system must 511: support threads. In this case, PHP should also be built with 512: experimental Zend Thread Safety (ZTS). Under this configuration, not 513: all extensions will be available. The recommended setup is to build 514: Apache with the default prefork MPM-Module. 515: __________________________________________________________________ 516: __________________________________________________________________ 517: 518: Lighttpd 1.4 on Unix systems 519: 520: This section contains notes and hints specific to Lighttpd 1.4 installs 521: of PHP on Unix systems. 522: 523: Please use the » Lighttpd trac to learn how to install Lighttpd 524: properly before continuing. 525: 526: Fastcgi is the preferred SAPI to connect PHP and Lighttpd. Fastcgi is 527: automagically enabled in php-cgi in PHP 5.3, but for older versions 528: configure PHP with --enable-fastcgi. To confirm that PHP has fastcgi 529: enabled, php -v should contain PHP 5.2.5 (cgi-fcgi) Before PHP 5.2.3, 530: fastcgi was enabled on the php binary (there was no php-cgi). 531: 532: Letting Lighttpd spawn php processes 533: 534: To configure Lighttpd to connect to php and spawn fastcgi processes, 535: edit lighttpd.conf. Sockets are preferred to connect to fastcgi 536: processes on the local system. 537: 538: Example #1 Partial lighttpd.conf 539: server.modules += ( "mod_fastcgi" ) 540: 541: fastcgi.server = ( ".php" => 542: (( 543: "socket" => "/tmp/php.socket", 544: "bin-path" => "/usr/local/bin/php-cgi", 545: "bin-environment" => ( 546: "PHP_FCGI_CHILDREN" => "16", 547: "PHP_FCGI_MAX_REQUESTS" => "10000" 548: ), 549: "min-procs" => 1, 550: "max-procs" => 1, 551: "idle-timeout" => 20 552: )) 553: ) 554: 555: The bin-path directive allows lighttpd to spawn fastcgi processes 556: dynamically. PHP will spawn children according to the PHP_FCGI_CHILDREN 557: environment variable. The "bin-environment" directive sets the 558: environment for the spawned processes. PHP will kill a child process 559: after the number of requests specified by PHP_FCGI_MAX_REQUESTS is 560: reached. The directives "min-procs" and "max-procs" should generally be 561: avoided with PHP. PHP manages its own children and opcode caches like 562: APC will only share among children managed by PHP. If "min-procs" is 563: set to something greater than 1, the total number of php responders 564: will be multiplied PHP_FCGI_CHILDREN (2 min-procs * 16 children gives 565: 32 responders). 566: 567: Spawning with spawn-fcgi 568: 569: Lighttpd provides a program called spawn-fcgi to ease the process of 570: spawning fastcgi processes easier. 571: 572: Spawning php-cgi 573: 574: It is possible to spawn processes without spawn-fcgi, though a bit of 575: heavy-lifting is required. Setting the PHP_FCGI_CHILDREN environment 576: var controls how many children PHP will spawn to handle incoming 577: requests. Setting PHP_FCGI_MAX_REQUESTS will determine how long (in 578: requests) each child will live. Here's a simple bash script to help 579: spawn php responders. 580: 581: Example #2 Spawning FastCGI Responders 582: #!/bin/sh 583: 584: # Location of the php-cgi binary 585: PHP=/usr/local/bin/php-cgi 586: 587: # PID File location 588: PHP_PID=/tmp/php.pid 589: 590: # Binding to an address 591: #FCGI_BIND_ADDRESS=10.0.1.1:10000 592: # Binding to a domain socket 593: FCGI_BIND_ADDRESS=/tmp/php.sock 594: 595: PHP_FCGI_CHILDREN=16 596: PHP_FCGI_MAX_REQUESTS=10000 597: 598: env -i PHP_FCGI_CHILDREN=$PHP_FCGI_CHILDREN \ 599: PHP_FCGI_MAX_REQUESTS=$PHP_FCGI_MAX_REQUESTS \ 600: $PHP -b $FCGI_BIND_ADDRESS & 601: 602: echo $! > "$PHP_PID" 603: 604: 605: Connecting to remote FCGI instances 606: 607: Fastcgi instances can be spawned on multiple remote machines in order 608: to scale applications. 609: 610: Example #3 Connecting to remote php-fastcgi instances 611: fastcgi.server = ( ".php" => 612: (( "host" => "10.0.0.2", "port" => 1030 ), 613: ( "host" => "10.0.0.3", "port" => 1030 )) 614: ) 615: __________________________________________________________________ 616: __________________________________________________________________ 617: 618: Sun, iPlanet and Netscape servers on Sun Solaris 619: 620: This section contains notes and hints specific to Sun Java System Web 621: Server, Sun ONE Web Server, iPlanet and Netscape server installs of PHP 622: on Sun Solaris. 623: 624: From PHP 4.3.3 on you can use PHP scripts with the NSAPI module to 625: generate custom directory listings and error pages. Additional 626: functions for Apache compatibility are also available. For support in 627: current web servers read the note about subrequests. 628: 629: You can find more information about setting up PHP for the Netscape 630: Enterprise Server (NES) here: » 631: http://benoit.noss.free.fr/php/install-php4.html 632: 633: To build PHP with Sun JSWS/Sun ONE WS/iPlanet/Netscape web servers, 634: enter the proper install directory for the --with-nsapi=[DIR] option. 635: The default directory is usually /opt/netscape/suitespot/. Please also 636: read /php-xxx-version/sapi/nsapi/nsapi-readme.txt. 637: 638: 1. Install the following packages from » http://www.sunfreeware.com/ 639: or another download site: 640: + autoconf-2.13 641: + automake-1.4 642: + bison-1_25-sol26-sparc-local 643: + flex-2_5_4a-sol26-sparc-local 644: + gcc-2_95_2-sol26-sparc-local 645: + gzip-1.2.4-sol26-sparc-local 646: + m4-1_4-sol26-sparc-local 647: + make-3_76_1-sol26-sparc-local 648: + mysql-3.23.24-beta (if you want mysql support) 649: + perl-5_005_03-sol26-sparc-local 650: + tar-1.13 (GNU tar) 651: 2. Make sure your path includes the proper directories 652: PATH=.:/usr/local/bin:/usr/sbin:/usr/bin:/usr/ccs/bin and make it 653: available to your system export PATH. 654: 3. gunzip php-x.x.x.tar.gz (if you have a .gz dist, otherwise go to 655: 4). 656: 4. tar xvf php-x.x.x.tar 657: 5. Change to your extracted PHP directory: cd ../php-x.x.x 658: 6. For the following step, make sure /opt/netscape/suitespot/ is where 659: your netscape server is installed. Otherwise, change to the correct 660: path and run: 661: ./configure --with-mysql=/usr/local/mysql \ 662: --with-nsapi=/opt/netscape/suitespot/ \ 663: --enable-libgcc 664: 7. Run make followed by make install. 665: 666: After performing the base install and reading the appropriate readme 667: file, you may need to perform some additional configuration steps. 668: 669: Configuration Instructions for Sun/iPlanet/Netscape 670: 671: Firstly you may need to add some paths to the LD_LIBRARY_PATH 672: environment for the server to find all the shared libs. This can best 673: done in the start script for your web server. The start script is often 674: located in: /path/to/server/https-servername/start. You may also need 675: to edit the configuration files that are located in: 676: /path/to/server/https-servername/config/. 677: 1. Add the following line to mime.types (you can do that by the 678: administration server): 679: type=magnus-internal/x-httpd-php exts=php 680: 681: 2. Edit magnus.conf (for servers >= 6) or obj.conf (for servers < 6) 682: and add the following, shlib will vary depending on your system, it 683: will be something like /opt/netscape/suitespot/bin/libphp4.so. You 684: should place the following lines after mime types init. 685: Init fn="load-modules" funcs="php4_init,php4_execute,php4_auth_trans" shlib="/op 686: t/netscape/suitespot/bin/libphp4.so" 687: Init fn="php4_init" LateInit="yes" errorString="Failed to initialize PHP!" [php_ 688: ini="/path/to/php.ini"] 689: 690: (PHP >= 4.3.3) The php_ini parameter is optional but with it you 691: can place your php.ini in your web server config directory. 692: 3. Configure the default object in obj.conf (for virtual server 693: classes [version 6.0+] in their vserver.obj.conf): 694: <Object name="default"> 695: . 696: . 697: . 698: .#NOTE this next line should happen after all 'ObjectType' and before all 'AddLo 699: g' lines 700: Service fn="php4_execute" type="magnus-internal/x-httpd-php" [inikey=value inike 701: y=value ...] 702: . 703: . 704: </Object> 705: 706: (PHP >= 4.3.3) As additional parameters you can add some special 707: php.ini-values, for example you can set a 708: docroot="/path/to/docroot" specific to the context php4_execute is 709: called. For boolean ini-keys please use 0/1 as value, not 710: "On","Off",... (this will not work correctly), e.g. 711: zlib.output_compression=1 instead of zlib.output_compression="On" 712: 4. This is only needed if you want to configure a directory that only 713: consists of PHP scripts (same like a cgi-bin directory): 714: <Object name="x-httpd-php"> 715: ObjectType fn="force-type" type="magnus-internal/x-httpd-php" 716: Service fn=php4_execute [inikey=value inikey=value ...] 717: </Object> 718: 719: After that you can configure a directory in the Administration 720: server and assign it the style x-httpd-php. All files in it will 721: get executed as PHP. This is nice to hide PHP usage by renaming 722: files to .html. 723: 5. Setup of authentication: PHP authentication cannot be used with any 724: other authentication. ALL AUTHENTICATION IS PASSED TO YOUR PHP 725: SCRIPT. To configure PHP Authentication for the entire server, add 726: the following line to your default object: 727: <Object name="default"> 728: AuthTrans fn=php4_auth_trans 729: . 730: . 731: . 732: </Object> 733: 734: 6. To use PHP Authentication on a single directory, add the following: 735: <Object ppath="d:\path\to\authenticated\dir\*"> 736: AuthTrans fn=php4_auth_trans 737: </Object> 738: 739: Note: 740: 741: The stacksize that PHP uses depends on the configuration of the web 742: server. If you get crashes with very large PHP scripts, it is 743: recommended to raise it with the Admin Server (in the section 744: "MAGNUS EDITOR"). 745: 746: CGI environment and recommended modifications in php.ini 747: 748: Important when writing PHP scripts is the fact that Sun JSWS/Sun ONE 749: WS/iPlanet/Netscape is a multithreaded web server. Because of that all 750: requests are running in the same process space (the space of the web 751: server itself) and this space has only one environment. If you want to 752: get CGI variables like PATH_INFO, HTTP_HOST etc. it is not the correct 753: way to try this in the old PHP way with getenv() or a similar way 754: (register globals to environment, $_ENV). You would only get the 755: environment of the running web server without any valid CGI variables! 756: 757: Note: 758: 759: Why are there (invalid) CGI variables in the environment? 760: 761: Answer: This is because you started the web server process from the 762: admin server which runs the startup script of the web server, you 763: wanted to start, as a CGI script (a CGI script inside of the admin 764: server!). This is why the environment of the started web server has 765: some CGI environment variables in it. You can test this by starting 766: the web server not from the administration server. Use the command 767: line as root user and start it manually - you will see there are no 768: CGI-like environment variables. 769: 770: Simply change your scripts to get CGI variables in the correct way for 771: PHP 4.x by using the superglobal $_SERVER. If you have older scripts 772: which use $HTTP_HOST, etc., you should turn on register_globals in 773: php.ini and change the variable order too (important: remove "E" from 774: it, because you do not need the environment here): 775: variables_order = "GPCS" 776: register_globals = On 777: 778: Special use for error pages or self-made directory listings (PHP >= 4.3.3) 779: 780: You can use PHP to generate the error pages for "404 Not Found" or 781: similar. Add the following line to the object in obj.conf for every 782: error page you want to overwrite: 783: Error fn="php4_execute" code=XXX script="/path/to/script.php" [inikey=value inik 784: ey=value...] 785: 786: where XXX is the HTTP error code. Please delete any other Error 787: directives which could interfere with yours. If you want to place a 788: page for all errors that could exist, leave the code parameter out. 789: Your script can get the HTTP status code with $_SERVER['ERROR_TYPE']. 790: 791: Another possibility is to generate self-made directory listings. Just 792: create a PHP script which displays a directory listing and replace the 793: corresponding default Service line for type="magnus-internal/directory" 794: in obj.conf with the following: 795: Service fn="php4_execute" type="magnus-internal/directory" script="/path/to/scri 796: pt.php" [inikey=value inikey=value...] 797: 798: For both error and directory listing pages the original URI and 799: translated URI are in the variables $_SERVER['PATH_INFO'] and 800: $_SERVER['PATH_TRANSLATED']. 801: 802: Note about nsapi_virtual() and subrequests (PHP >= 4.3.3) 803: 804: The NSAPI module now supports the nsapi_virtual() function (alias: 805: virtual()) to make subrequests on the web server and insert the result 806: in the web page. This function uses some undocumented features from the 807: NSAPI library. On Unix the module automatically looks for the needed 808: functions and uses them if available. If not, nsapi_virtual() is 809: disabled. 810: 811: Note: 812: 813: But be warned: Support for nsapi_virtual() is EXPERIMENTAL!!! 814: __________________________________________________________________ 815: __________________________________________________________________ 816: 817: CGI and command line setups 818: 819: By default, PHP is built as both a CLI and CGI program, which can be 820: used for CGI processing. If you are running a web server that PHP has 821: module support for, you should generally go for that solution for 822: performance reasons. However, the CGI version enables users to run 823: different PHP-enabled pages under different user-ids. 824: Warning 825: 826: A server deployed in CGI mode is open to several possible 827: vulnerabilities. Please read our CGI security section to learn how to 828: defend yourself from such attacks. 829: 830: Testing 831: 832: If you have built PHP as a CGI program, you may test your build by 833: typing make test. It is always a good idea to test your build. This way 834: you may catch a problem with PHP on your platform early instead of 835: having to struggle with it later. 836: 837: Using Variables 838: 839: Some server supplied environment variables are not defined in the 840: current » CGI/1.1 specification. Only the following variables are 841: defined there: AUTH_TYPE, CONTENT_LENGTH, CONTENT_TYPE, 842: GATEWAY_INTERFACE, PATH_INFO, PATH_TRANSLATED, QUERY_STRING, 843: REMOTE_ADDR, REMOTE_HOST, REMOTE_IDENT, REMOTE_USER, REQUEST_METHOD, 844: SCRIPT_NAME, SERVER_NAME, SERVER_PORT, SERVER_PROTOCOL, and 845: SERVER_SOFTWARE. Everything else should be treated as 'vendor 846: extensions'. 847: __________________________________________________________________ 848: __________________________________________________________________ 849: 850: HP-UX specific installation notes 851: 852: This section contains notes and hints specific to installing PHP on 853: HP-UX systems. 854: 855: There are two main options for installing PHP on HP-UX systems. Either 856: compile it, or install a pre-compiled binary. 857: 858: Official pre-compiled packages are located here: » 859: http://software.hp.com/ 860: 861: Until this manual section is rewritten, the documentation about 862: compiling PHP (and related extensions) on HP-UX systems has been 863: removed. For now, consider reading the following external resource: » 864: Building Apache and PHP on HP-UX 11.11 865: __________________________________________________________________ 866: __________________________________________________________________ 867: 868: OpenBSD installation notes 869: 870: This section contains notes and hints specific to installing PHP on » 871: OpenBSD 3.6. 872: 873: Using Binary Packages 874: 875: Using binary packages to install PHP on OpenBSD is the recommended and 876: simplest method. The core package has been separated from the various 877: modules, and each can be installed and removed independently from the 878: others. The files you need can be found on your OpenBSD CD or on the 879: FTP site. 880: 881: The main package you need to install is php4-core-4.3.8.tgz, which 882: contains the basic engine (plus gettext and iconv). Next, take a look 883: at the module packages, such as php4-mysql-4.3.8.tgz or 884: php4-imap-4.3.8.tgz. You need to use the phpxs command to activate and 885: deactivate these modules in your php.ini. 886: 887: Example #1 OpenBSD Package Install Example 888: # pkg_add php4-core-4.3.8.tgz 889: # /usr/local/sbin/phpxs -s 890: # cp /usr/local/share/doc/php4/php.ini-recommended /var/www/conf/php.ini 891: (add in mysql) 892: # pkg_add php4-mysql-4.3.8.tgz 893: # /usr/local/sbin/phpxs -a mysql 894: (add in imap) 895: # pkg_add php4-imap-4.3.8.tgz 896: # /usr/local/sbin/phpxs -a imap 897: (remove mysql as a test) 898: # pkg_delete php4-mysql-4.3.8 899: # /usr/local/sbin/phpxs -r mysql 900: (install the PEAR libraries) 901: # pkg_add php4-pear-4.3.8.tgz 902: 903: Read the » packages(7) manual page for more information about binary 904: packages on OpenBSD. 905: 906: Using Ports 907: 908: You can also compile up PHP from source using the » ports tree. 909: However, this is only recommended for users familiar with OpenBSD. The 910: PHP 4 port is split into two sub-directories: core and extensions. The 911: extensions directory generates sub-packages for all of the supported 912: PHP modules. If you find you do not want to create some of these 913: modules, use the no_* FLAVOR. For example, to skip building the imap 914: module, set the FLAVOR to no_imap. 915: 916: Common Problems 917: 918: * The default install of Apache runs inside a » chroot(2) jail, which 919: will restrict PHP scripts to accessing files under /var/www. You 920: will therefore need to create a /var/www/tmp directory for PHP 921: session files to be stored, or use an alternative session backend. 922: In addition, database sockets need to be placed inside the jail or 923: listen on the localhost interface. If you use network functions, 924: some files from /etc such as /etc/resolv.conf and /etc/services 925: will need to be moved into /var/www/etc. The OpenBSD PEAR package 926: automatically installs into the correct chroot directories, so no 927: special modification is needed there. More information on the 928: OpenBSD Apache is available in the » OpenBSD FAQ. 929: * The OpenBSD 3.6 package for the » gd extension requires XFree86 to 930: be installed. If you do not wish to use some of the font features 931: that require X11, install the php4-gd-4.3.8-no_x11.tgz package 932: instead. 933: 934: Older Releases 935: 936: Older releases of OpenBSD used the FLAVORS system to compile up a 937: statically linked PHP. Since it is hard to generate binary packages 938: using this method, it is now deprecated. You can still use the old 939: stable ports trees if you wish, but they are unsupported by the OpenBSD 940: team. If you have any comments about this, the current maintainer for 941: the port is Anil Madhavapeddy (avsm at openbsd dot org). 942: __________________________________________________________________ 943: __________________________________________________________________ 944: 945: Solaris specific installation tips 946: 947: This section contains notes and hints specific to installing PHP on 948: Solaris systems. 949: 950: Required software 951: 952: Solaris installs often lack C compilers and their related tools. Read 953: this FAQ for information on why using GNU versions for some of these 954: tools is necessary. The required software is as follows: 955: * gcc (recommended, other C compilers may work) 956: * make 957: * flex 958: * bison 959: * m4 960: * autoconf 961: * automake 962: * perl 963: * gzip 964: * tar 965: * GNU sed 966: 967: In addition, you will need to install (and possibly compile) any 968: additional software specific to your configuration, such as Oracle or 969: MySQL. 970: 971: Using Packages 972: 973: You can simplify the Solaris install process by using pkgadd to install 974: most of your needed components. 975: __________________________________________________________________ 976: __________________________________________________________________ 977: 978: Debian GNU/Linux installation notes 979: 980: This section contains notes and hints specific to installing PHP on » 981: Debian GNU/Linux. 982: Warning 983: 984: Unofficial builds from third-parties are not supported here. Any bugs 985: should be reported to the Debian team unless they can be reproduced 986: using the latest builds from our » download area. 987: 988: While the instructions for building PHP on Unix apply to Debian as 989: well, this manual page contains specific information for other options, 990: such as using either the apt-get or aptitude commands. This manual page 991: uses these two commands interchangeably. 992: 993: Using APT 994: 995: First, note that other related packages may be desired like 996: libapache2-mod-php5 to integrate with Apache 2, and php-pear for PEAR. 997: 998: Second, before installing a package, it's wise to ensure the package 999: list is up to date. Typically, this is done by running the command 1000: apt-get update. 1001: 1002: Example #1 Debian Install Example with Apache 2 1003: # apt-get install php5-common libapache2-mod-php5 php5-cli 1004: 1005: APT will automatically install the PHP 5 module for Apache 2 and all of 1006: its dependencies, and then activate it. Apache should be restarted in 1007: order for the changes take place. For example: 1008: 1009: Example #2 Stopping and starting Apache once PHP is installed 1010: # /etc/init.d/apache2 stop 1011: # /etc/init.d/apache2 start 1012: 1013: Better control of configuration 1014: 1015: In the last section, PHP was installed with only core modules. It's 1016: very likely that additional modules will be desired, such as MySQL, 1017: cURL, GD, etc. These may also be installed via the apt-get command. 1018: 1019: Example #3 Methods for listing additional PHP 5 packages 1020: # apt-cache search php5 1021: # aptitude search php5 1022: # aptitude search php5 |grep -i mysql 1023: 1024: The examples will show a lot of packages including several PHP specific 1025: ones like php5-cgi, php5-cli and php5-dev. Determine which are needed 1026: and install them like any other with either apt-get or aptitude. And 1027: because Debian performs dependency checks, it'll prompt for those so 1028: for example to install MySQL and cURL: 1029: 1030: Example #4 Install PHP with MySQL, cURL 1031: # apt-get install php5-mysql php5-curl 1032: 1033: APT will automatically add the appropriate lines to the different 1034: php.ini related files like /etc/php5/apache2/php.ini, 1035: /etc/php5/conf.d/pdo.ini, etc. and depending on the extension will add 1036: entries similar to extension=foo.so. However, restarting the web server 1037: (like Apache) is required before these changes take affect. 1038: 1039: Common Problems 1040: 1041: * If the PHP scripts are not parsing via the web server, then it's 1042: likely that PHP was not added to the web server's configuration 1043: file, which on Debian may be /etc/apache2/apache2.conf or similar. 1044: See the Debian manual for further details. 1045: * If an extension was seemingly installed yet the functions are 1046: undefined, be sure that the appropriate ini file is being loaded 1047: and/or the web server was restarted after installation. 1048: * There are two basic commands for installing packages on Debian (and 1049: other linux variants): apt-get and aptitude. However, explaining 1050: the subtle differences between these commands goes beyond the scope 1051: of this manual. 1052: __________________________________________________________________ 1053: __________________________________________________________________ 1054: __________________________________________________________________ 1055: 1056: Installation on Mac OS X 1057: 1058: Table of Contents 1059: 1060: * Using Packages 1061: * Using the bundled PHP 1062: * Compiling PHP on Mac OS X 1063: 1064: This section contains notes and hints specific to installing PHP on Mac 1065: OS X. PHP is bundled with Macs, and compiling is similar to the Unix 1066: installation guide. 1067: __________________________________________________________________ 1068: 1069: Using Packages 1070: 1071: There are a few pre-packaged and pre-compiled versions of PHP for Mac 1072: OS X. This can help in setting up a standard configuration, but if you 1073: need to have a different set of features (such as a secure server, or a 1074: different database driver), you may need to build PHP and/or your web 1075: server yourself. If you are unfamiliar with building and compiling your 1076: own software, it's worth checking whether somebody has already built a 1077: packaged version of PHP with the features you need. 1078: 1079: The following resources offer easy to install packages and precompiled 1080: binaries for PHP on Mac OS: 1081: 1082: * MacPorts: » http://www.macports.org/ 1083: * Entropy: » http://www.entropy.ch/software/macosx/php/ 1084: * Fink: » http://www.finkproject.org/ 1085: * Homebrew: » http://github.com/mxcl/homebrew 1086: __________________________________________________________________ 1087: __________________________________________________________________ 1088: 1089: Using the bundled PHP 1090: 1091: PHP has come standard with Macs since OS X version 10.0.0. Enabling PHP 1092: with the default web server requires uncommenting a few lines in the 1093: Apache configuration file httpd.conf whereas the CGI and/or CLI are 1094: enabled by default (easily accessible via the Terminal program). 1095: 1096: Enabling PHP using the instructions below is meant for quickly setting 1097: up a local development environment. It's highly recommended to always 1098: upgrade PHP to the newest version. Like most live software, newer 1099: versions are created to fix bugs and add features and PHP being is no 1100: different. See the appropriate MAC OS X installation documentation for 1101: further details. The following instructions are geared towards a 1102: beginner with details provided for getting a default setup to work. All 1103: users are encouraged to compile, or install a new packaged version. 1104: 1105: The standard installation type is using mod_php, and enabling the 1106: bundled mod_php on Mac OS X for the Apache web server (the default web 1107: server, that is accessible via System Preferences) involves the 1108: following steps: 1109: 1110: 1. Locate and open the Apache configuration file. By default, the 1111: location is as follows: /private/etc/apache2/httpd.conf Using 1112: Finder or Spotlight to find this file may prove difficult as by 1113: default it's private and owned by the root user. 1114: 1115: Note: One way to open this is by using a Unix based text editor in 1116: the Terminal, for example nano, and because the file is owned by 1117: root we'll use the sudo command to open it (as root) so for example 1118: type the following into the Terminal Application (after, it will 1119: prompt for a password): sudo nano /private/etc/apache2/httpd.conf 1120: Noteworthy nano commands: ^w (search), ^o (save), and ^x (exit) 1121: where ^ represents the Ctrl key. 1122: 1123: Note: Versions of Mac OS X prior to 10.5 were bundled with older 1124: versions of PHP and Apache. As such, the Apache configuration file 1125: on legacy machines may be /etc/httpd/httpd.conf. 1126: 2. With a text editor, uncomment the lines (by removing the #) that 1127: look similar to the following (these two lines are often not 1128: together, locate them both in the file): 1129: # LoadModule php5_module libexec/httpd/libphp5.so 1130: 1131: # AddModule mod_php5.c 1132: 1133: Notice the location/path. When building PHP in the future, the 1134: above files should be replaced or commented out. 1135: 3. Be sure the desired extensions will parse as PHP (examples: .php 1136: .html and .inc) 1137: Due to the following statement already existing in httpd.conf (as 1138: of Mac Panther), once PHP is enabled the .php files will 1139: automatically parse as PHP. 1140: <IfModule mod_php5.c> 1141: # If php is turned on, we respect .php and .phps files. 1142: AddType application/x-httpd-php .php 1143: AddType application/x-httpd-php-source .phps 1144: 1145: # Since most users will want index.php to work we 1146: # also automatically enable index.php 1147: <IfModule mod_dir.c> 1148: DirectoryIndex index.html index.php 1149: </IfModule> 1150: </IfModule> 1151: 1152: Note: 1153: Before OS X 10.5 (Leopard), PHP 4 was bundled instead of PHP 5 in 1154: which case the above instructions will differ slightly by changing 1155: 5's to 4's. 1156: 4. Be sure the DirectoryIndex loads the desired default index file 1157: This is also set in httpd.conf. Typically index.php and index.html 1158: are used. By default index.php is enabled because it's also in the 1159: PHP check shown above. Adjust accordingly. 1160: 5. Set the php.ini location or use the default A typical default 1161: location on Mac OS X is /usr/local/php/php.ini and a call to 1162: phpinfo() will reveal this information. If a php.ini is not used, 1163: PHP will use all default values. See also the related FAQ on 1164: finding php.ini. 1165: 6. Locate or set the DocumentRoot This is the root directory for all 1166: the web files. Files in this directory are served from the web 1167: server so the PHP files will parse as PHP before outputting them to 1168: the browser. A typical default path is /Library/WebServer/Documents 1169: but this can be set to anything in httpd.conf. Alternatively, the 1170: default DocumentRoot for individual users is 1171: /Users/yourusername/Sites 1172: 7. Create a phpinfo() file 1173: The phpinfo() function will display information about PHP. Consider 1174: creating a file in the DocumentRoot with the following PHP code: 1175: <?php phpinfo(); ?> 1176: 8. Restart Apache, and load the PHP file created above To restart, 1177: either execute sudo apachectl graceful in the shell or stop/start 1178: the "Personal Web Server" option in the OS X System Preferences. By 1179: default, loading local files in the browser will have an URL like 1180: so: http://localhost/info.php Or using the DocumentRoot in the user 1181: directory is another option and would end up looking like: 1182: http://localhost/~yourusername/info.php 1183: 1184: The CLI (or CGI in older versions) is appropriately named php and 1185: likely exists as /usr/bin/php. Open up the terminal, read the command 1186: line section of the PHP manual, and execute php -v to check the PHP 1187: version of this PHP binary. A call to phpinfo() will also reveal this 1188: information. 1189: __________________________________________________________________ 1190: __________________________________________________________________ 1191: 1192: Compiling PHP on Mac OS X 1193: 1194: Use the Unix installation guide to compile PHP on Mac OS X. 1195: __________________________________________________________________ 1196: __________________________________________________________________ 1197: __________________________________________________________________ 1198: 1199: Installation of PECL extensions 1200: 1201: Table of Contents 1202: 1203: * Introduction to PECL Installations 1204: * Downloading PECL extensions 1205: * Installing a PHP extension on Windows 1206: * Compiling shared PECL extensions with the pecl command 1207: * Compiling shared PECL extensions with phpize 1208: * Compiling PECL extensions statically into PHP 1209: __________________________________________________________________ 1210: 1211: Introduction to PECL Installations 1212: 1213: » PECL is a repository of PHP extensions that are made available to you 1214: via the » PEAR packaging system. This section of the manual is intended 1215: to demonstrate how to obtain and install PECL extensions. 1216: 1217: These instructions assume /your/phpsrcdir/ is the path to the PHP 1218: source distribution, and that extname is the name of the PECL 1219: extension. Adjust accordingly. These instructions also assume a 1220: familiarity with the » pear command. The information in the PEAR manual 1221: for the pear command also applies to the pecl command. 1222: 1223: To be useful, a shared extension must be built, installed, and loaded. 1224: The methods described below provide you with various instructions on 1225: how to build and install the extensions, but they do not automatically 1226: load them. Extensions can be loaded by adding an extension directive. 1227: To this php.ini file, or through the use of the dl() function. 1228: 1229: When building PHP modules, it's important to have known-good versions 1230: of the required tools (autoconf, automake, libtool, etc.) See the » 1231: Anonymous SVN Instructions for details on the required tools, and 1232: required versions. 1233: __________________________________________________________________ 1234: __________________________________________________________________ 1235: 1236: Downloading PECL extensions 1237: 1238: There are several options for downloading PECL extensions, such as: 1239: * The pecl install extname command downloads the extensions code 1240: automatically, so in this case there is no need for a separate 1241: download. 1242: * » http://pecl.php.net/ The PECL web site contains information about 1243: the different extensions that are offered by the PHP Development 1244: Team. The information available here includes: ChangeLog, release 1245: notes, requirements and other similar details. 1246: * pecl download extname PECL extensions that have releases listed on 1247: the PECL web site are available for download and installation using 1248: the » pecl command. Specific revisions may also be specified. 1249: * SVN Most PECL extensions also reside in SVN. A web-based view may 1250: be seen at » http://svn.php.net/viewvc/pecl/. To download straight 1251: from SVN, the following sequence of commands may be used: 1252: $ svn checkout http://svn.php.net/repository/pecl/extname/trunk 1253: extname 1254: * Windows downloads At this time the PHP project does not compile 1255: Windows binaries for PECL extensions. However, to compile PHP under 1256: Windows see the chapter titled building PHP for Windows. 1257: __________________________________________________________________ 1258: __________________________________________________________________ 1259: 1260: Installing a PHP extension on Windows 1261: 1262: On Windows, you have two ways to load a PHP extension: either compile 1263: it into PHP, or load the DLL. Loading a pre-compiled extension is the 1264: easiest and preferred way. 1265: 1266: To load an extension, you need to have it available as a ".dll" file on 1267: your system. All the extensions are automatically and periodically 1268: compiled by the PHP Group (see next section for the download). 1269: 1270: To compile an extension into PHP, please refer to building from source 1271: documentation. 1272: 1273: To compile a standalone extension (aka a DLL file), please refer to 1274: building from source documentation. If the DLL file is available 1275: neither with your PHP distribution nor in PECL, you may have to compile 1276: it before you can start using the extension. 1277: 1278: Where to find an extension? 1279: 1280: PHP extensions are usually called "php_*.dll" (where the star 1281: represents the name of the extension) and they are located under the 1282: "PHP\ext" ("PHP\extensions" in PHP4) folder. 1283: 1284: PHP ships with the extensions most useful to the majority of 1285: developers. They are called "core" extensions. 1286: 1287: However, if you need functionality not provided by any core extension, 1288: you may still be able to find one in PECL. The PHP Extension Community 1289: Library (PECL) is a repository for PHP Extensions, providing a 1290: directory of all known extensions and hosting facilities for 1291: downloading and development of PHP extensions. 1292: 1293: If you have developed an extension for your own uses, you might want to 1294: think about hosting it on PECL so that others with the same needs can 1295: benefit from your time. A nice side effect is that you give them a good 1296: chance to give you feedback, (hopefully) thanks, bug reports and even 1297: fixes/patches. Before you submit your extension for hosting on PECL, 1298: please read http://pecl.php.net/package-new.php. 1299: 1300: Which extension to download? 1301: 1302: Many times, you will find several versions of each DLL: 1303: * Different version numbers (at least the first two numbers should 1304: match) 1305: * Different thread safety settings 1306: * Different processor architecture (x86, x64, ...) 1307: * Different debugging settings 1308: * etc. 1309: 1310: You should keep in mind that your extension settings should match all 1311: the settings of the PHP executable you are using. The following PHP 1312: script will tell you all about your PHP settings: 1313: 1314: Example #1 phpinfo() call 1315: <?php 1316: phpinfo(); 1317: ?> 1318: 1319: Or from the command line, run: 1320: drive:\\path\to\php\executable\php.exe -i 1321: 1322: Loading an extension 1323: 1324: The most common way to load a PHP extension is to include it in your 1325: php.ini configuration file. Please note that many extensions are 1326: already present in your php.ini and that you only need to remove the 1327: semicolon to activate them. 1328: ;extension=php_extname.dll 1329: 1330: extension=php_extname.dll 1331: 1332: However, some web servers are confusing because they do not use the 1333: php.ini located alongside your PHP executable. To find out where your 1334: actual php.ini resides, look for its path in phpinfo(): 1335: Configuration File (php.ini) Path C:\WINDOWS 1336: 1337: Loaded Configuration File C:\Program Files\PHP\5.2\php.ini 1338: 1339: After activating an extension, save php.ini, restart the web server and 1340: check phpinfo() again. The new extension should now have its own 1341: section. 1342: 1343: Resolving problems 1344: 1345: If the extension does not appear in phpinfo(), you should check your 1346: logs to learn where the problem comes from. 1347: 1348: If you are using PHP from the command line (CLI), the extension loading 1349: error can be read directly on screen. 1350: 1351: If you are using PHP with a web server, the location and format of the 1352: logs vary depending on your software. Please read your web server 1353: documentation to locate the logs, as it does not have anything to do 1354: with PHP itself. 1355: 1356: Common problems are the location of the DLL, the value of the " 1357: extension_dir" setting inside php.ini and compile-time setting 1358: mismatches. 1359: 1360: If the problem lies in a compile-time setting mismatch, you probably 1361: didn't download the right DLL. Try downloading again the extension with 1362: the right settings. Again, phpinfo() can be of great help. 1363: __________________________________________________________________ 1364: __________________________________________________________________ 1365: 1366: Compiling shared PECL extensions with the pecl command 1367: 1368: PECL makes it easy to create shared PHP extensions. Using the » pecl 1369: command, do the following: 1370: 1371: $ pecl install extname 1372: 1373: This will download the source for extname, compile, and install 1374: extname.so into your extension_dir. extname.so may then be loaded via 1375: php.ini 1376: 1377: By default, the pecl command will not install packages that are marked 1378: with the alpha or beta state. If no stable packages are available, you 1379: may install a beta package using the following command: 1380: 1381: $ pecl install extname-beta 1382: 1383: You may also install a specific version using this variant: 1384: 1385: $ pecl install extname-0.1 1386: 1387: Note: 1388: 1389: After enabling the extension in php.ini, restarting the web service 1390: is required for the changes to be picked up. 1391: __________________________________________________________________ 1392: __________________________________________________________________ 1393: 1394: Compiling shared PECL extensions with phpize 1395: 1396: Sometimes, using the pecl installer is not an option. This could be 1397: because you're behind a firewall, or it could be because the extension 1398: you want to install is not available as a PECL compatible package, such 1399: as unreleased extensions from SVN. If you need to build such an 1400: extension, you can use the lower-level build tools to perform the build 1401: manually. 1402: 1403: The phpize command is used to prepare the build environment for a PHP 1404: extension. In the following sample, the sources for an extension are in 1405: a directory named extname: 1406: 1407: $ cd extname 1408: $ phpize 1409: $ ./configure 1410: $ make 1411: # make install 1412: 1413: A successful install will have created extname.so and put it into the 1414: PHP extensions directory. You'll need to and adjust php.ini and add an 1415: extension=extname.so line before you can use the extension. 1416: 1417: If the system is missing the phpize command, and precompiled packages 1418: (like RPM's) are used, be sure to also install the appropriate devel 1419: version of the PHP package as they often include the phpize command 1420: along with the appropriate header files to build PHP and its 1421: extensions. 1422: 1423: Execute phpize --help to display additional usage information. 1424: __________________________________________________________________ 1425: __________________________________________________________________ 1426: 1427: Compiling PECL extensions statically into PHP 1428: 1429: You might find that you need to build a PECL extension statically into 1430: your PHP binary. To do this, you'll need to place the extension source 1431: under the php-src/ext/ directory and tell the PHP build system to 1432: regenerate its configure script. 1433: 1434: $ cd /your/phpsrcdir/ext 1435: $ pecl download extname 1436: $ gzip -d < extname.tgz | tar -xvf - 1437: $ mv extname-x.x.x extname 1438: 1439: This will result in the following directory: 1440: 1441: /your/phpsrcdir/ext/extname 1442: 1443: From here, force PHP to rebuild the configure script, and then build 1444: PHP as normal: 1445: 1446: $ cd /your/phpsrcdir 1447: $ rm configure 1448: $ ./buildconf --force 1449: $ ./configure --help 1450: $ ./configure --with-extname --enable-someotherext --with-foobar 1451: $ make 1452: $ make install 1453: 1454: Note: To run the 'buildconf' script you need autoconf 2.13 and 1455: automake 1.4+ (newer versions of autoconf may work, but are not 1456: supported). 1457: 1458: Whether --enable-extname or --with-extname is used depends on the 1459: extension. Typically an extension that does not require external 1460: libraries uses --enable. To be sure, run the following after buildconf: 1461: 1462: $ ./configure --help | grep extname 1463: __________________________________________________________________ 1464: __________________________________________________________________ 1465: __________________________________________________________________ 1466: 1467: Problems? 1468: 1469: Table of Contents 1470: 1471: * Read the FAQ 1472: * Other problems 1473: * Bug reports 1474: __________________________________________________________________ 1475: 1476: Read the FAQ 1477: 1478: Some problems are more common than others. The most common ones are 1479: listed in the PHP FAQ, part of this manual. 1480: __________________________________________________________________ 1481: __________________________________________________________________ 1482: 1483: Other problems 1484: 1485: If you are still stuck, someone on the PHP installation mailing list 1486: may be able to help you. You should check out the archive first, in 1487: case someone already answered someone else who had the same problem as 1488: you. The archives are available from the support page on » 1489: http://www.php.net/support.php. To subscribe to the PHP installation 1490: mailing list, send an empty mail to » 1491: php-install-subscribe@lists.php.net. The mailing list address is » 1492: php-install@lists.php.net. 1493: 1494: If you want to get help on the mailing list, please try to be precise 1495: and give the necessary details about your environment (which operating 1496: system, what PHP version, what web server, if you are running PHP as 1497: CGI or a server module, safe mode, etc.), and preferably enough code to 1498: make others able to reproduce and test your problem. 1499: __________________________________________________________________ 1500: __________________________________________________________________ 1501: 1502: Bug reports 1503: 1504: If you think you have found a bug in PHP, please report it. The PHP 1505: developers probably don't know about it, and unless you report it, 1506: chances are it won't be fixed. You can report bugs using the 1507: bug-tracking system at » http://bugs.php.net/. Please do not send bug 1508: reports in mailing list or personal letters. The bug system is also 1509: suitable to submit feature requests. 1510: 1511: Read the » How to report a bug document before submitting any bug 1512: reports! 1513: __________________________________________________________________ 1514: __________________________________________________________________ 1515: __________________________________________________________________ 1516: 1517: Runtime Configuration 1518: 1519: Table of Contents 1520: 1521: * The configuration file 1522: * .user.ini files 1523: * Where a configuration setting may be set 1524: * How to change configuration settings 1525: __________________________________________________________________ 1526: 1527: The configuration file 1528: 1529: The configuration file (php.ini) is read when PHP starts up. For the 1530: server module versions of PHP, this happens only once when the web 1531: server is started. For the CGI and CLI version, it happens on every 1532: invocation. 1533: 1534: php.ini is searched in these locations (in order): 1535: * SAPI module specific location (PHPIniDir directive in Apache 2, -c 1536: command line option in CGI and CLI, php_ini parameter in NSAPI, 1537: PHP_INI_PATH environment variable in THTTPD) 1538: * The PHPRC environment variable. Before PHP 5.2.0 this was checked 1539: after the registry key mentioned below. 1540: * As of PHP 5.2.0, the location of the php.ini file can be set for 1541: different versions of PHP. The following registry keys are examined 1542: in order: [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y.z], 1543: [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x.y] and 1544: [HKEY_LOCAL_MACHINE\SOFTWARE\PHP\x], where x, y and z mean the PHP 1545: major, minor and release versions. If there is a value for 1546: IniFilePath in these keys, then the first one found will be used as 1547: the location of the php.ini (Windows only). 1548: * [HKEY_LOCAL_MACHINE\SOFTWARE\PHP], value of IniFilePath (Windows 1549: only). 1550: * Current working directory (except CLI) 1551: * The web server's directory (for SAPI modules), or directory of PHP 1552: (otherwise in Windows) 1553: * Windows directory (C:\windows or C:\winnt) (for Windows), or 1554: --with-config-file-path compile time option 1555: 1556: If php-SAPI.ini exists (where SAPI is used SAPI, so the filename is 1557: e.g. php-cli.ini or php-apache.ini), it's used instead of php.ini. SAPI 1558: name can be determined by php_sapi_name(). 1559: 1560: Note: 1561: 1562: The Apache web server changes the directory to root at startup 1563: causing PHP to attempt to read php.ini from the root filesystem if 1564: it exists. 1565: 1566: The php.ini directives handled by extensions are documented 1567: respectively on the pages of the extensions themselves. The list of the 1568: core directives is available in the appendix. Probably not all PHP 1569: directives are documented in the manual though. For a complete list of 1570: directives available in your PHP version, please read your well 1571: commented php.ini file. Alternatively, you may find the » the latest 1572: php.ini from SVN helpful too. 1573: 1574: Example #1 php.ini example 1575: ; any text on a line after an unquoted semicolon (;) is ignored 1576: [php] ; section markers (text within square brackets) are also ignored 1577: ; Boolean values can be set to either: 1578: ; true, on, yes 1579: ; or false, off, no, none 1580: register_globals = off 1581: track_errors = yes 1582: 1583: ; you can enclose strings in double-quotes 1584: include_path = ".:/usr/local/lib/php" 1585: 1586: ; backslashes are treated the same as any other character 1587: include_path = ".;c:\php\lib" 1588: 1589: Since PHP 5.1.0, it is possible to refer to existing .ini variables 1590: from within .ini files. Example: open_basedir = ${open_basedir} 1591: ":/new/dir". 1592: __________________________________________________________________ 1593: __________________________________________________________________ 1594: 1595: .user.ini files 1596: 1597: Since PHP 5.3.0, PHP includes support for .htaccess-style INI files on 1598: a per-directory basis. These files are processed only by the 1599: CGI/FastCGI SAPI. This functionality obsoletes the PECL htscanner 1600: extension. If you are using Apache, use .htaccess files for the same 1601: effect. 1602: 1603: In addition to the main php.ini file, PHP scans for INI files in each 1604: directory, starting with the directory of the requested PHP file, and 1605: working its way up to the current document root (as set in 1606: $_SERVER['DOCUMENT_ROOT']). In case the PHP file is outside the 1607: document root, only its directory is scanned. 1608: 1609: Only INI settings with the modes PHP_INI_PERDIR and PHP_INI_USER will 1610: be recognized in .user.ini-style INI files. 1611: 1612: Two new INI directives, user_ini.filename and user_ini.cache_ttl 1613: control the use of user INI files. 1614: 1615: user_ini.filename sets the name of the file PHP looks for in each 1616: directory; if set to an empty string, PHP doesn't scan at all. The 1617: default is .user.ini. 1618: 1619: user_ini.cache_ttl controls how often user INI files are re-read. The 1620: default is 300 seconds (5 minutes). 1621: __________________________________________________________________ 1622: __________________________________________________________________ 1623: 1624: Where a configuration setting may be set 1625: 1626: These modes determine when and where a PHP directive may or may not be 1627: set, and each directive within the manual refers to one of these modes. 1628: For example, some settings may be set within a PHP script using 1629: ini_set(), whereas others may require php.ini or httpd.conf. 1630: 1631: For example, the output_buffering setting is PHP_INI_PERDIR therefore 1632: it may not be set using ini_set(). However, the display_errors 1633: directive is PHP_INI_ALL therefore it may be set anywhere, including 1634: with ini_set(). 1635: 1636: CAPTION: Definition of PHP_INI_* modes 1637: 1638: Mode Value Meaning 1639: PHP_INI_USER 1 Entry can be set in user scripts (like with ini_set()) 1640: or in the Windows registry 1641: PHP_INI_PERDIR 6 Entry can be set in php.ini, .htaccess or httpd.conf 1642: PHP_INI_SYSTEM 4 Entry can be set in php.ini or httpd.conf 1643: PHP_INI_ALL 7 Entry can be set anywhere 1644: __________________________________________________________________ 1645: __________________________________________________________________ 1646: 1647: How to change configuration settings 1648: 1649: Running PHP as an Apache module 1650: 1651: When using PHP as an Apache module, you can also change the 1652: configuration settings using directives in Apache configuration files 1653: (e.g. httpd.conf) and .htaccess files. You will need "AllowOverride 1654: Options" or "AllowOverride All" privileges to do so. 1655: 1656: There are several Apache directives that allow you to change the PHP 1657: configuration from within the Apache configuration files. For a listing 1658: of which directives are PHP_INI_ALL, PHP_INI_PERDIR, or PHP_INI_SYSTEM, 1659: have a look at the List of php.ini directives appendix. 1660: 1661: php_value name value 1662: Sets the value of the specified directive. Can be used only with 1663: PHP_INI_ALL and PHP_INI_PERDIR type directives. To clear a 1664: previously set value use none as the value. 1665: 1666: Note: Don't use php_value to set boolean values. php_flag (see 1667: below) should be used instead. 1668: 1669: php_flag name on|off 1670: Used to set a boolean configuration directive. Can be used only 1671: with PHP_INI_ALL and PHP_INI_PERDIR type directives. 1672: 1673: php_admin_value name value 1674: Sets the value of the specified directive. This can not be used 1675: in .htaccess files. Any directive type set with php_admin_value 1676: can not be overridden by .htaccess or ini_set(). To clear a 1677: previously set value use none as the value. 1678: 1679: php_admin_flag name on|off 1680: Used to set a boolean configuration directive. This can not be 1681: used in .htaccess files. Any directive type set with 1682: php_admin_flag can not be overridden by .htaccess or ini_set(). 1683: 1684: Example #1 Apache configuration example 1685: <IfModule mod_php5.c> 1686: php_value include_path ".:/usr/local/lib/php" 1687: php_admin_flag engine on 1688: </IfModule> 1689: <IfModule mod_php4.c> 1690: php_value include_path ".:/usr/local/lib/php" 1691: php_admin_flag engine on 1692: </IfModule> 1693: 1694: Caution 1695: 1696: PHP constants do not exist outside of PHP. For example, in httpd.conf 1697: you can not use PHP constants such as E_ALL or E_NOTICE to set the 1698: error_reporting directive as they will have no meaning and will 1699: evaluate to 0. Use the associated bitmask values instead. These 1700: constants can be used in php.ini 1701: 1702: Changing PHP configuration via the Windows registry 1703: 1704: When running PHP on Windows, the configuration values can be modified 1705: on a per-directory basis using the Windows registry. The configuration 1706: values are stored in the registry key HKLM\SOFTWARE\PHP\Per Directory 1707: Values, in the sub-keys corresponding to the path names. For example, 1708: configuration values for the directory c:\inetpub\wwwroot would be 1709: stored in the key HKLM\SOFTWARE\PHP\Per Directory 1710: Values\c\inetpub\wwwroot. The settings for the directory would be 1711: active for any script running from this directory or any subdirectory 1712: of it. The values under the key should have the name of the PHP 1713: configuration directive and the string value. PHP constants in the 1714: values are not parsed. However, only configuration values changeable in 1715: PHP_INI_USER can be set this way, PHP_INI_PERDIR values can not. 1716: 1717: Other interfaces to PHP 1718: 1719: Regardless of how you run PHP, you can change certain values at runtime 1720: of your scripts through ini_set(). See the documentation on the 1721: ini_set() page for more information. 1722: 1723: If you are interested in a complete list of configuration settings on 1724: your system with their current values, you can execute the phpinfo() 1725: function, and review the resulting page. You can also access the values 1726: of individual configuration directives at runtime using ini_get() or 1727: get_cfg_var(). 1728: __________________________________________________________________ 1729: __________________________________________________________________ 1730: __________________________________________________________________ 1731: 1732: Installation 1733: 1734: This section holds common questions about the way to install PHP. PHP 1735: is available for almost any OS (except maybe for MacOS before OSX), and 1736: almost any web server. 1737: 1738: To install PHP, follow the instructions in Installing PHP. 1739: 1. Why shouldn't I use Apache2 with a threaded MPM in a production 1740: environment? 1741: 2. Unix/Windows: Where should my php.ini file be located? 1742: 3. Unix: I installed PHP, but every time I load a document, I get the 1743: message 'Document Contains No Data'! What's going on here? 1744: 4. Unix: I installed PHP using RPMS, but Apache isn't processing the 1745: PHP pages! What's going on here? 1746: 5. Unix: I patched Apache with the FrontPage extensions patch, and 1747: suddenly PHP stopped working. Is PHP incompatible with the Apache 1748: FrontPage extensions? 1749: 6. Unix/Windows: I have installed PHP, but when I try to access a PHP 1750: script file via my browser, I get a blank screen. 1751: 7. Unix/Windows: I have installed PHP, but when try to access a PHP 1752: script file via my browser, I get a server 500 error. 1753: 8. Some operating systems: I have installed PHP without errors, but 1754: when I try to start Apache I get undefined symbol errors: 1755: [mybox:user /src/php5] root# apachectl configtest apachectl: 1756: /usr/local/apache/bin/httpd Undefined symbols: _compress 1757: _uncompress 1758: 9. Windows: I have installed PHP, but when I try to access a PHP 1759: script file via my browser, I get the error: cgi error: The 1760: specified CGI application misbehaved by not returning a complete 1761: set of HTTP headers. The headers it did return are: 1762: 10. Windows: I've followed all the instructions, but still can't get 1763: PHP and IIS to work together! 1764: 11. When running PHP as CGI with IIS, PWS, OmniHTTPD or Xitami, I get 1765: the following error: Security Alert! PHP CGI cannot be accessed 1766: directly.. 1767: 12. How do I know if my php.ini is being found and read? It seems like 1768: it isn't as my changes aren't being implemented. 1769: 13. How do I add my PHP directory to the PATH on Windows? 1770: 14. How do I make the php.ini file available to PHP on windows? 1771: 15. Is it possible to use Apache content negotiation (MultiViews 1772: option) with PHP? 1773: 16. Is PHP limited to process GET and POST request methods only? 1774: 1775: Why shouldn't I use Apache2 with a threaded MPM in a production 1776: environment? 1777: PHP is glue. It is the glue used to build cool web applications 1778: by sticking dozens of 3rd-party libraries together and making it 1779: all appear as one coherent entity through an intuitive and easy 1780: to learn language interface. The flexibility and power of PHP 1781: relies on the stability and robustness of the underlying 1782: platform. It needs a working OS, a working web server and 1783: working 3rd-party libraries to glue together. When any of these 1784: stop working PHP needs ways to identify the problems and fix 1785: them quickly. When you make the underlying framework more 1786: complex by not having completely separate execution threads, 1787: completely separate memory segments and a strong sandbox for 1788: each request to play in, further weaknesses are introduced into 1789: PHP's system. 1790: 1791: If you feel you have to use a threaded MPM, look at a FastCGI 1792: configuration where PHP is running in its own memory space. 1793: 1794: And finally, this warning against using a threaded MPM is not as 1795: strong for Windows systems because most libraries on that 1796: platform tend to be threadsafe. 1797: 1798: Unix/Windows: Where should my php.ini file be located? 1799: By default on Unix it should be in /usr/local/lib which is 1800: <install-path>/lib. Most people will want to change this at 1801: compile-time with the --with-config-file-path flag. You would, 1802: for example, set it with something like: 1803: 1804: --with-config-file-path=/etc 1805: 1806: And then you would copy php.ini-development from the 1807: distribution to /etc/php.ini and edit it to make any local 1808: changes you want. 1809: 1810: --with-config-file-scan-dir=PATH 1811: 1812: On Windows the default path for the php.ini file is the Windows 1813: directory. If you're using the Apache webserver, php.ini is 1814: first searched in the Apaches install directory, e.g. c:\program 1815: files\apache group\apache. This way you can have different 1816: php.ini files for different versions of Apache on the same 1817: machine. 1818: 1819: See also the chapter about the configuration file. 1820: 1821: Unix: I installed PHP, but every time I load a document, I get the 1822: message 'Document Contains No Data'! What's going on here? 1823: This probably means that PHP is having some sort of problem and 1824: is core-dumping. Look in your server error log to see if this is 1825: the case, and then try to reproduce the problem with a small 1826: test case. If you know how to use 'gdb', it is very helpful when 1827: you can provide a backtrace with your bug report to help the 1828: developers pinpoint the problem. If you are using PHP as an 1829: Apache module try something like: 1830: 1831: + Stop your httpd processes 1832: + gdb httpd 1833: + Stop your httpd processes 1834: + > run -X -f /path/to/httpd.conf 1835: + Then fetch the URL causing the problem with your browser 1836: + > run -X -f /path/to/httpd.conf 1837: + If you are getting a core dump, gdb should inform you of this 1838: now 1839: + type: bt 1840: + You should include your backtrace in your bug report. This 1841: should be submitted to » http://bugs.php.net/ 1842: 1843: If your script uses the regular expression functions 1844: (preg_match() and friends), you should make sure that you 1845: compiled PHP and Apache with the same regular expression 1846: package. This should happen automatically with PHP and Apache 1847: 1.3.x 1848: 1849: Unix: I installed PHP using RPMS, but Apache isn't processing the PHP 1850: pages! What's going on here? 1851: Assuming you installed both Apache and PHP from RPM packages, 1852: you need to uncomment or add some or all of the following lines 1853: in your httpd.conf file: 1854: 1855: # Extra Modules 1856: AddModule mod_php.c 1857: AddModule mod_perl.c 1858: 1859: # Extra Modules 1860: LoadModule php_module modules/mod_php.so 1861: LoadModule php5_module modules/libphp5.so 1862: LoadModule perl_module modules/libperl.so 1863: 1864: And add: 1865: 1866: AddType application/x-httpd-php .php 1867: 1868: ... to the global properties, or to the properties of the 1869: VirtualDomain you want to have PHP support added to. 1870: 1871: Unix: I patched Apache with the FrontPage extensions patch, and 1872: suddenly PHP stopped working. Is PHP incompatible with the 1873: Apache FrontPage extensions? 1874: No, PHP works fine with the FrontPage extensions. The problem is 1875: that the FrontPage patch modifies several Apache structures, 1876: that PHP relies on. Recompiling PHP (using 'make clean ; make') 1877: after the FP patch is applied would solve the problem. 1878: 1879: Unix/Windows: I have installed PHP, but when I try to access a PHP 1880: script file via my browser, I get a blank screen. 1881: Do a 'view source' in the web browser and you will probably find 1882: that you can see the source code of your PHP script. This means 1883: that the web server did not send the script to PHP for 1884: interpretation. Something is wrong with the server configuration 1885: - double check the server configuration against the PHP 1886: installation instructions. 1887: 1888: Unix/Windows: I have installed PHP, but when try to access a PHP script 1889: file via my browser, I get a server 500 error. 1890: Something went wrong when the server tried to run PHP. To get to 1891: see a sensible error message, from the command line, change to 1892: the directory containing the PHP executable (php.exe on Windows) 1893: and run php -i. If PHP has any problems running, then a suitable 1894: error message will be displayed which will give you a clue as to 1895: what needs to be done next. If you get a screen full of HTML 1896: codes (the output of the phpinfo() function) then PHP is 1897: working, and your problem may be related to your server 1898: configuration which you should double check. 1899: 1900: Some operating systems: I have installed PHP without errors, but when I 1901: try to start Apache I get undefined symbol errors: 1902: 1903: [mybox:user /src/php5] root# apachectl configtest 1904: apachectl: /usr/local/apache/bin/httpd Undefined symbols: 1905: _compress 1906: _uncompress 1907: 1908: This has actually nothing to do with PHP, but with the MySQL 1909: client libraries. Some need --with-zlib , others do not. This is 1910: also covered in the MySQL FAQ. 1911: 1912: Windows: I have installed PHP, but when I try to access a PHP script 1913: file via my browser, I get the error: 1914: 1915: cgi error: 1916: The specified CGI application misbehaved by not 1917: returning a complete set of HTTP headers. 1918: The headers it did return are: 1919: 1920: This error message means that PHP failed to output anything at 1921: all. To get to see a sensible error message, from the command 1922: line, change to the directory containing the PHP executable 1923: (php.exe on Windows) and run php -i. If PHP has any problems 1924: running, then a suitable error message will be displayed which 1925: will give you a clue as to what needs to be done next. If you 1926: get a screen full of HTML codes (the output of the phpinfo() 1927: function) then PHP is working. 1928: 1929: Once PHP is working at the command line, try accessing the 1930: script via the browser again. If it still fails then it could be 1931: one of the following: 1932: 1933: + File permissions on your PHP script, php.exe, php5ts.dll, 1934: php.ini or any PHP extensions you are trying to load are such 1935: that the anonymous internet user ISUR_<machinename> cannot 1936: access them. 1937: + The script file does not exist (or possibly isn't where you 1938: think it is relative to your web root directory). Note that 1939: for IIS you can trap this error by ticking the 'check file 1940: exists' box when setting up the script mappings in the 1941: Internet Services Manager. If a script file does not exist 1942: then the server will return a 404 error instead. There is also 1943: the additional benefit that IIS will do any authentication 1944: required for you based on the NTLanMan permissions on your 1945: script file. 1946: 1947: Windows: I've followed all the instructions, but still can't get PHP 1948: and IIS to work together! 1949: Make sure any user who needs to run a PHP script has the rights 1950: to run php.exe! IIS uses an anonymous user which is added at the 1951: time IIS is installed. This user needs rights to php.exe. Also, 1952: any authenticated user will also need rights to execute php.exe. 1953: And for IIS4 you need to tell it that PHP is a script engine. 1954: Also, you will want to read this faq. 1955: 1956: When running PHP as CGI with IIS, PWS, OmniHTTPD or Xitami, I get the 1957: following error: Security Alert! PHP CGI cannot be accessed 1958: directly.. 1959: You must set the cgi.force_redirect directive to 0. It defaults 1960: to 1 so be sure the directive isn't commented out (with a ;). 1961: Like all directives, this is set in php.ini 1962: 1963: Because the default is 1, it's critical that you're 100% sure 1964: that the correct php.ini file is being read. Read this faq for 1965: details. 1966: 1967: How do I know if my php.ini is being found and read? It seems like it 1968: isn't as my changes aren't being implemented. 1969: To be sure your php.ini is being read by PHP, make a call to 1970: phpinfo(). Near the top, there will be a listing called 1971: Configuration File (php.ini). This will tell you where PHP is 1972: looking for php.ini and whether or not it's being read. If just 1973: a directory PATH exists, then it's not being read, and you 1974: should put your php.ini in that directory. If php.ini is 1975: included within the PATH, it is being read. 1976: 1977: If php.ini is being read and you're running PHP as a module, 1978: then be sure to restart your web server after making changes to 1979: php.ini 1980: 1981: See also php_ini_loaded_file(). 1982: 1983: How do I add my PHP directory to the PATH on Windows? 1984: On Windows NT+ and Windows Server 2000+: 1985: 1986: + Go to Control Panel and open the System icon (Start -> 1987: Settings -> Control Panel -> System, or just Start -> Control 1988: Panel -> System for Windows XP/2003+) 1989: + Go to the Advanced tab 1990: + Click on the 'Environment Variables' button 1991: + Look into the 'System Variables' pane 1992: + Find the Path entry (you may need to scroll to find it) 1993: + Double click on the Path entry 1994: + Enter your PHP directory at the end, including ';' before 1995: (e.g. ;C:\php) 1996: + Press OK 1997: 1998: On Windows 98/Me you need to edit the autoexec.bat file: 1999: 2000: + Open the Notepad (Start -> Run and enter notepad) 2001: + Open the C:\autoexec.bat file 2002: + Locate the line with PATH=C:\WINDOWS;C:\WINDOWS\COMMAND;..... 2003: and add: ;C:\php to the end of the line 2004: + Save the file and restart your computer 2005: 2006: Note: Be sure to reboot after following the steps above to ensure 2007: that the PATH changes are applied. 2008: 2009: The PHP manual used to promote the copying of files into the 2010: Windows system directory, this is because this directory 2011: (C:\Windows, C:\WINNT, etc.) is by default in the systems PATH. 2012: Copying files into the Windows system directory has long since 2013: been deprecated and may cause problems. 2014: 2015: How do I make the php.ini file available to PHP on windows? 2016: There are several ways of doing this. If you are using Apache, 2017: read their installation specific instructions (Apache 1, Apache 2018: 2), otherwise you must set the PHPRC environment variable: 2019: 2020: On Windows NT, 2000, XP and 2003: 2021: 2022: + Go to Control Panel and open the System icon (Start -> 2023: Settings -> Control Panel -> System, or just Start -> Control 2024: Panel -> System for Windows XP/2003) 2025: + Go to the Advanced tab 2026: + Click on the 'Environment Variables' button 2027: + Look into the 'System variables' pane 2028: + Click on 'New' and enter 'PHPRC' as the variable name and the 2029: directory where php.ini is located as the variable value (e.g. 2030: C:\php) 2031: + Press OK and restart your computer 2032: 2033: On Windows 98/Me you need to edit the autoexec.bat file: 2034: 2035: + Open the Notepad (Start -> Run and enter notepad) 2036: + Open the C:\autoexec.bat file 2037: + Add a new line to the end of the file: set PHPRC=C:\php 2038: (replace C:\php with the directory where php.ini is located). 2039: Please note that the path cannot contain spaces. For instance, 2040: if you have installed PHP in C:\Program Files\PHP, you would 2041: enter C:\PROGRA~1\PHP instead. 2042: + Save the file and restart your computer 2043: 2044: Is it possible to use Apache content negotiation (MultiViews option) 2045: with PHP? 2046: If links to PHP files include extension, everything works 2047: perfect. This FAQ is only for the case when links to PHP files 2048: don't include extension and you want to use content negotiation 2049: to choose PHP files from URL with no extension. In this case, 2050: replace the line AddType application/x-httpd-php .php with: 2051: 2052: AddHandler php5-script php 2053: AddType text/html php 2054: 2055: This solution doesn't work for Apache 1 as PHP module doesn't 2056: catch php-script. 2057: 2058: Is PHP limited to process GET and POST request methods only? 2059: No, it is possible to handle any request method, e.g. CONNECT. 2060: Proper response status can be sent with header(). If only GET 2061: and POST methods should be handled, it can be achieved with this 2062: Apache configuration: 2063: 2064: <LimitExcept GET POST> 2065: Deny from all 2066: </LimitExcept>