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