embedaddon/php/INSTALL - view

File: [ELWIX - Embedded LightWeight unIX -] / embedaddon / php / INSTALL
Revision 1.1.1.2 (vendor branch): download - view: text, annotated - select for diffs - revision graph
Mon Jul 22 01:31:37 2013 UTC (10 years, 10 months ago) by misho
Branches: php, MAIN
CVS tags: v5_4_29p0, v5_4_29, v5_4_20p0, v5_4_20, v5_4_17, HEAD

5.4.17

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