Installing PHP

=20 1.0 -2006-01-24 +2011-01-23 =20 -Introduction -

- - -

-This guide describes, how to install the new style PHP packages -(dev-lang/php) and it's extensions. You should not intstall old s= tyle -PHP packages (dev-php/php, dev-php/php-cgi or=20 -dev-php/mod_php), since those packages are not supported by the -PHP herd anymore. The old ebuilds have been merged into one new ebuild: -dev-lang/php, which contains all SAPIs now. -

- - -If you still have old PHP packages installed, you should upgrade as soon= as -possible using our Upgrading Guide= , because -the old packages will be -removed from portage soon! - - - -The new PHP packages require the new Apache layout, so have a look at Upgrading Apa= che=20 -if you haven't upgraded yet. - +Installing PHP FastCGI =20 + +Discouraged for PHP 5.3.3 and newer -

- =20 - -The new PHP Packages

-Decide which SAPI to install - +Emerging PHP =20 +

-To choose the SAPI (Server API) you want, use these USE flags: +PHP has a huge number of USE flags available. Luckily, the USE flags tha= t the +PHP ebuilds set by default are fairly sane so the only one we need to ad= d is=20 +the cgi USE flag, which gives us the FastCGI server API. I find that ena= bling +cgi as a global USE flag in /etc/make.conf is a bad idea as= I do not +care about enabling cgi support for every single package in the tree tha= t +support such a thing. If you are like me, adding it to +/etc/portage/package.use is what you want. Just drop the fo= llowing line +in there:

=20 -

cgi - builds & installs /usr/bin/php-cgi -
cli - builds & installs /usr/bin/php
apache - builds & installs mod_php for Apache 1.= 3 (new -layout)
apache2 - builds & installs mod_php for Apache 2= .0 =20 -(new layout)

- -

-You can mix and match any of these USE flags; except you can't have both= =20 -apache and apache2 switched on. -

+dev-lang/php cgi
+

=20

-The whole point of these ebuilds is that you can have both PHP4 and PHP5= =20 -installed at the same time: -

+That is about all the configuration you need for PHP. Now, emerge!

=20 -

-(install latest version of PHP with CLI and Apache2 module)
-USE=3D"cli apache2" emerge 'dev-lang/php'
-
-(install PHP4 only)
-USE=3D"cli apache2" emerge '=3Ddev-lang/php-4*'
-
-(install both, PHP4 and PHP5)
-USE=3D"cli apache2" emerge '=3Ddev-lang/php-4*' '=3Ddev-lang/php-5*'<=
/i>
++emerge -av php
 
=20
-
-USE flags shouldn't be set this way, please use=20
-/etc/portage/package.use as described later (this way you c=
an also
-select different USE flags for PHP4 and PHP5).
-
- =20

-
+configuring Apache2 =20 -New Portage Categories for PHP4 and PHP5 - -
-The new PHP ebuilds have been moved from dev-php to dev-lang/p= hp. -To make it possible to install packages independently for PHP4 and PHP5,= two=20 -new portage categories have been introduced: dev-php4 and=20 -dev-php5. These categories are mainly used by PECL packages like -pecl-pdo, pecl-apc, php-java-bridge or xdebug.=20 -Packages, working with both, PHP4 and PHP5, will stay in dev-php. -
-
-E.g., to install pecl-apc: +Apache is a trusted member of the LAMP stack and probably the webserver = that +the most people are familiar with. In addition to www-servers/apache, we= need +to install another package to get fastcgi working: www-apache/mod_fas= tcgi.
=20 -
-(install APC for PHP4 only) -emerge dev-php4/pecl-apc +
+emerge -av apache mod_fastcgi +
=20 -(install APC for PHP5 only) -emerge dev-php5/pecl-apc =20 -(install APC for both, PHP4 and PHP5) -emerge dev-php4/pecl-apc dev-php5/pecl-apc +
After all has been installed, simply enable it in:
+
+APACHE2_OPTS=3D"-D DEFAULT_VHOST -D INFO -D LANGUAGE -D USERDIR -D = FASTCGI"
=20 - -
+
Once that is done, drop the following into /etc/apache2/vhosts.= d/00_default_vhost.conf
=20 -
-PHP Directories - +
=20 -
-
These new ebuilds install their contents into /usr/lib/php4<= /path>=20 -and/or /usr/lib/php5 (the Apache modules go into the right = place=20 -for Apache).
-
The PEAR packages and other PHP libraries go into=20 -/usr/share/php.
-
PHP extensions (e.g. PECL packages) add a [PACKAGE].ini file -to the /etc/php/[SAPI]/ext directory.
-
+Listen 80 =20 - -
+NameVirtualHost *:80 =20 -
-Installing multiple PHP versions - =20 -
-If you install more than one version of PHP, e.g.: -
+<VirtualHost *:80> + ServerName localhost +=20 + DocumentRoot /var/www/localhost/htdocs/ +=20 + <IfModule mpm_peruser_module> + ServerEnvironment apache apache + </IfModule> + AddHandler php5-fastcgi .php + FastCgiServer /usr/lib/php5.2/bin/php-cgi +=20 + <Directory /var/www/localhost/htdocs/> + Order deny,allow + Allow from all +=20 + </Directory> +=20 +</VirtualHost> =20 -
-USE=3D"cgi cli apache2" emerge '=3Ddev-lang/php-4*' '=3Ddev-lang/php-= 5*'
=20 -
-The ebuilds will create symlinks in /usr/bin for the last v= ersion=20 -of PHP you installed, in this case PHP5 since it was installed after PHP= 4. If=20 -you want /usr/bin/php or /usr/bin/php-cgi to p= oint=20 -to PHP4 or one to PHP4, the other to PHP5 etc., you can use the php-select tool from -app-admin/php-toolkit. php-select makes it very easy to sy= mlink -the appropriate binaries. -
- - -
- - - -Installation Instructions -
-Set the USE flags - +
That is it. Now start apache
=20 -
-The new PHP ebuild provides USE flags for nearly every PHP extension, so= you -can customize your PHP installation almost as good as building PHP by yo= urself, -simply by adding appropriate USE flags to -/etc/portage/package.use (has to be created if it doesn't e= xists). -This way you can easily combine the flexibility with the advantages of a= =20 -mature package management (Portage). The new ebuild even allows a parall= el -installation of PHP4 and PHP5. -
- - -/etc/portage/package.use will set the USE flags for your PH= P=20 -installation and remember them without mass editing through=20 -make.conf. - - -
-Please set the USE flags accordingly to what you want your PHP installat= ion to=20 -support (it is recommended to at least set the cli USE flag): -
- -
-dev-lang/php -* cli apache2 ctype gd jpeg mysql pcre png session truetyp= e xml xsl zlib +
+/etc/init.d/apache2 start
=20 - --* will disable all USE flags (this will disable even basic PHP -features like Session-, PCRE-, gd- and MySQL-support!), so you have to s= pecify -every USE flag for any extension/feature you would like to use. See -Managing Extensions for details. You have to set USE flags for=20 -upstream's defaults such as pcre if you want to use preg_*=20 -Functions or session if you want to use Session=20 -Handling Functions.=20 - - -
-If you want to install PHP4 and PHP5 in parallel, you can put in differe= nt USE=20 -flags for each version:=20 -
+
Put something like the following into /var/www/localhost/htdocs= /index.php
=20 -
-=3Ddev-lang/php-4* -* cgi cli ctype gd jpeg mysql pcre pear png session = truetype xml xsl zlib -=3Ddev-lang/php-5* -* cli apache2 ctype gd jpeg mysql pcre pdo-external = pear png session simplexml soap sqlite truetype xml xsl zlib +
+<?php +phpinfo();
=20 - -For a list of recommended USE flags look at -Recommend USE flags. For a list of USE flags=20 -available for PHP have a look at the USE=20 -flags table from overlay wiki. - + +
That is it. Now you should be able to enter http://localhost/index.php to test your setup.
=20
-
-Emerge PHP - - -
-Now you have the choice to install PHP4 only, PHP5 only or both in paral= lel. To -install PHP4 only you have to emerge =3Ddev-lang/php-4*, to insta= ll PHP5 -(latest) you can use dev-lang/php, and to install both in paralle= l you -have to emerge =3Ddev-lang/php-4* and =3Ddev-lang/php-5*. - -
- -
-Check available USE flags and current USE flag settings: -
+Configuring lighttpd =20 -
-(check PHP4 package) -emerge --pretend --verbose '=3Ddev-lang/php-4*' - -(check PHP5 package) -emerge --pretend --verbose '=3Ddev-lang/php-5*' - -(check PHP extensions for PHP4) -emerge --pretend --verbose dev-php4/pecl-apc dev-php4/pecl-imagick de= v-php4/xdebug - -(check PHP extensions for PHP5) -emerge --pretend --verbose dev-php5/pecl-apc dev-php5/pecl-imagick + =20 -(check PHP libraries/applications) -emerge --pretend --verbose PEAR-PEAR PEAR-Mail PEAR-MDB smarty +
First, make sure that you have the php USE flag enabled in your syste= m. Revisit your /etc/portage/package.use is what and append the following= :
+
+www-server/lighttpd php
=20 -
-Emerge PHP if everything is fine: -
- -
-(emerge PHP4 package) -emerge '=3Ddev-lang/php-4*' - -(emerge PHP5 package) -emerge '=3Ddev-lang/php-5*' - -(emerge PHP extensions for PHP4) -emerge dev-php4/pecl-apc dev-php4/pecl-imagick dev-php4/xdebug - -(emerge PHP extensions for PHP5) -emerge dev-php5/pecl-apc dev-php5/pecl-imagick - -(emerge PHP libraries/applications) -emerge PEAR-PEAR PEAR-Mail PEAR-MDB smarty +Then emerge lighttpd +
+emerge -av lighttpd
=20 + +
That is basically it. The configuration files that comes with lighttp= d should work out of the box, and you should be able to see your site at +http://localhost/index.php

+ =20 + +Installing PHP FPM + +This is only available for PHP 5.3.3 and newer. The PHP herds cons= ider FPM as the recommended setup for PHP +In PHP 5.3.3, PHP is shipped with support for the FPM SAPI. The FPM SAPI= is an=20 +improved fcgi SAPI that allows for more advanced configuration than the +original fcgi SAPI. One of the most useful features is process managemen= t, which=20 +makes it very useful for lightweight webservers, such as www-servers/= nginx,=20 +that does not handle process management of fcgi themselves.=20 +
-PHP4 and PHP5 parallel: select which cli/cgi binary to use</title= > +<title>Installing PHP =20 -
-After emerging you will have binaries for cli and/or cgi i= n=20 -/usr/lib/php4/bin and/or /usr/lib/php5/bin. If= you -have installed both, PHP4 and PHP5, portage cannot decide for you which = one -should be used by default and always symlinks the last PHP version you -installed in /usr/bin. So if you installed PHP5 as last, yo= u'll -see /usr/bin/php symlinked to /usr/lib/php5/bin/php. -So one cli and/or cgi binary as well as php-devel -(responsable for building PHP extensions using phpize and -php-config) has to be symlinked (in /usr/bin), which= could -easily be done using php-select, which is part of -app-admin/php-toolkit. -
- - -The dev-lang/php packages depend on app-admin/php-toolkit = so -php-select should be available automatically after emerging the n= ew -style php packages. - +
Make sure the fpm USE flag is enabled
=20 -
-Assuming you have emerged =3Ddev-lang/php-4* as well as=20 -=3Ddev-lang/php-5*, enter the following php-select command= s to show -the currently selected PHP versions: -
- -
-(for cli) -php-select php - -(for cgi) -php-select php-cgi - -(for phpize, php-config) -php-select php-devel -
+
+dev-lang/php fpm +
=20 =20 -
-You should see something like that: -
- -
-# php-select php -/usr/bin/php is set to /usr/lib/php5/bin/php -
=20 -
-Which means that the default path to the PHP cli binary -/usr/bin/php is symlinked to the PHP5 binary -/usr/lib/php5/bin/php. So PHP scripts using -/usr/bin/php will be executed by PHP5. -
=20
=20
-Use php-select to change default PHP versions - +Setting up FPM with lighttpd =20 -
-If you are not happy with the default version settings you found out in = the -last chapter, you can use php-select again to select the desired -version: -
+ +Interestingly enough, you do NOT want the php USE flag +for www-servers/lighttpd. It could actually break the build. =20 -
-(for cli) -php-select php php4 +
Make sure that lighttpd is build with support for fastcgi and that th= e php USE flag is disabled
=20 -(for cgi) -php-select php-cgi php5 =20 -(for phpize, php-config) -php-select php-devel php5 +
+www-servers/lighttpd fastcgi -php
=20 - -Please type php-select -h to get more details on what php-sele= ct -can do. - -
-Check linking: -
+Lighttpd ships with a default FastCGI config file, but unfortunately, it= is +written to work with the old PHP FCGI SAPI only, instead of a general +FCGI setup. Since we disabled the php USE flag, it won=E2=80=99t be incl= uded, and rightly so.=20 +However it does provide a good foundation for a configuration file that = can be used with FPM.
=20 -
+
Edit /etc/lighttpd/mod_fastcgi.conf so that it looks som= ething like this: +
=20 - # stat /usr/bin/php /usr/bin/php-cgi /usr/bin/phpize /usr/bin/php-co= nfig | grep File - File: `/usr/bin/php' -> `/usr/lib/php4/bin/php' - File: `/usr/bin/php-cgi' -> `/usr/lib/php5/bin/php-cgi' - File: `/usr/bin/phpize' -> `/usr/lib/php5/bin/phpize' - File: `/usr/bin/php-config' -> `/usr/lib/php5/bin/php-config' +
+server.modules +=3D ("mod_fastcgi") +fastcgi.server =3D ( ".php" =3D> + ( "localhost" =3D> + ( + "host" =3D> "127.0.0.1", + "port" =3D> "9000" + ) + ) +)
=20 - -Please note that php-select only changes the default versions. If= you -have installed both, PHP4 and PHP5 cgi/cli you can allways use the direc= t paths -like /usr/lib/php4/bin/php and /usr/lib/php5/bin/php<= /path> -to run a PHP script with a specific version. You can use PHP4 and PHP5 c= gi -in the same Apache instance, but you cannot use two different PHP Apache -modules in one Apache instance, see -PHP4 and PHP5 Configuration Guide for details. - - - -
- - - -PHP Configuration -
- +
Note the host and port parts.
=20 -
-The Gentoo PHP Package stores configuration in /etc/php, wh= ich -contains one subdirectory for each SAPI for each PHP version: -
+
Since Gentoo ships with a perfectly working copy of a php-fpm.ini<= /c> file,=20 +located in /etc/php/fpm-php5/php-fpm.ini, and init-script,=20 +all you need to do now is to start the services:
=20 -
-$ ls -1 /etc/php -apache2-php4 -apache2-php5 -cli-php4 -cli-php5 +
+/etc/init.d/php-fpm start +/etc/init.d/lighttpd start
=20 -
-Every subdirectory contains an own php.ini, one php.ini for= each -SAPI. -
+ =20
=20
-Configuration of PHP Extensions +Nginx +
+<snip> + server { + listen 127.0.0.1; + server_name localhost; +=20 + access_log /var/log/nginx/localhost.access_log main; + error_log /var/log/nginx/localhost.error_log info; +=20 + root /var/www/localhost/htdocs; +=20 + location ~ .php$ { + fastcgi_pass 127.0.0.1:9000; + include fastcgi.conf; + } + } +<snip> +
=20 -
-The new PHP package does not store configuration directives from externa= l -(shared) PHP extensions in php.ini. These directives will -be stored in own extension-specific configuration files in the -/etc/php/[SAPI]/ext directories. To enable/disable shared -extensions, symlinks from /etc/php/[SAPI]/ext-active are us= ed. If -you want to enable an extension, create a symlink in -/etc/php/[SAPI]/ext-active to the corresponding=20 -[EXTENSION].ini file in /etc/php/[SAPI]/ext/. = If you -want to disable an extension, remove the symlink. -
- -
-E.g., if you emerge the dev-php5/pecl-apc package, the default -configuration of APC will be written to -/etc/php/[SAPI]5/ext/apc.ini. A symlink from -/etc/php/[SAPI]5/ext-active/apc.ini to -/etc/php/[SAPI]5/ext/apc.ini will be created, so the extens= ion is -enabled by default. To disable APC, you have to remove the -/etc/php/[SAPI]5/ext-active/apc.ini symlink for every SAPI.= To -enable APC again, create new symlinks in=20 -/etc/php/[SAPI]5/ext-active/ to ../ext/apc.ini= . -
- - -If you install PHP as an Apache module, make sure to restart Apache afte= r=20 -installation and configuration. - +
Now just start the related services and you should have a working sit= e
=20 +
+/etc/init.d/nginx start +/etc/init.d/php-fpm start +
+
+ =20 -Configure Apache to work with PHP4 and/or PHP5 +Nice to know
+Development vs Production php.ini files - -
-To configure Apache to load the PHP4 or PHP5 module (mod_php), you have = to add --D PHP4 respectively -D PHP5 to APACHE2_OPTS variab= le in -/etc/conf.d/apache2. -
- -
-(settings for PHP4) -APACHE2_OPTS=3D"-D PHP4" - -(or settings for PHP5) -APACHE2_OPTS=3D"-D PHP5" +
PHP distributes two versions of their php.ini,=20 +one for production environments and one for development.=20 +In Gentoo, you can now chose which of these two files you want +installed on your system by default. This is particularly handy +when you update PHP and do not want your chosen environment settings +in php.ini to appear when you merge your coniguration files= .
+ +
To tell portage which version of php.ini you want, add o= ne=20 +of the following lines to /etc/make.conf:
+ +
+# Set default php.ini version to the development version +PHP_INI_VERSION=3D"development" +# Set default php.ini version to the production version +PHP_INI_VERSION=3D"production"
=20 -
-There are many ways to make Apache work with two PHP versions in paralle= l. The -easiest way is to use PHP4 and PHP5 as a cgi binary, or a PHP4 cgi and P= HP5 -module (or the other way around). It's not possible to use the PHP4 modu= le and -PHP5 module in one Apache instance. -
+Note that the PHP herd also does additional patching of the php.in= i file +regardless of the version you set above. =20 -
-We have created a PHP4 and PHP= 5 -Configuration Guide which explains some of the possible solutions. -
+Always check and double-check your php.ini file after upgrade =20 +
If you want to change your php.ini after installation, y= ou=20 +can find both versions located in /usr/share/doc/php-<version>/= php.ini-development.bz2 +
+ +
+FPMm user/group + +
However, you might want to change the user and group parameters to so= mething else +than nobody. Personally, I changed it to nginx, but you might want to co= nsider +creating a new user for your web application.

- -Support / Getting Help -
+Further reading - -
-If you run into problems with the new Gentoo PHP packages, here's where = you can=20 -get help: -
-
-
-Common Questions about PHP on Gentoo
-
Development-Pag= e of the=20 -PHP Overlay
-
#gentoo-php on irc.freenode.net; this is the chatroom where the ov= erlay's -regular authors hang out. We'd love to see you there!
-
Gentoo Forums are a = popular -place to ask for help. There are plenty of other Gentoo users reading th= e -Forums round the clock, making it a great place to get help in a hurry.<= /li> +
PHP Up= grade guide - Offers more information about how to deal with multip= le instals of PHP and how to install extensions.
+
Concurrently running multiple versions of PHP= - A guide describing how to set up webservers to work with parallel inst= alls of PHP

- -
-For details about implementation of the new packages have a look at Stuarts= Posting=20 -on gentoo-dev and Stuarts Blog entries starting from -'Radical Changes for PHP5 Support'.=20 -
- -
-On the Development-Pag= e -you'll find a lot of documentation and more recent ebuilds, which will b= e -moved to the official portage tree later. -
- -
-