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