Packaging:PHP

= Guidelines for packaging PHP addon modules =

Different kinds of packages
There are basically 4 different kinds of php modules, which are packaged for Fedora:


 * PECL (PHP Extention Community Library), which are PHP modules usually written in C, which are dynamically loaded by the PHP interpreter on startup.
 * PEAR (PHP Extension and Application Repository), which are reusable components written in PHP, usually classes, which can be used in your own PHP applications and scripts by using e.g. the include directive.
 * CHANNEL : a package which register a channel. A channel is a repository which provides php extensions
 * Other package providing php extension not handled by pear/pecl mechanisms

While upstream used the same package and distribution format for PECL and PEAR, creating RPMs has to take some differences into account.

3 channels are defined on installation of php-pear
 * (alias pear) : the default channel for PHP Extension and Application Repository
 * (alias pecl) : the default channel for PHP Extension Community Library
 * : Pseudo-channel for static packages

Other channels must be configured at RPM build time and at at RPM installation time.

Naming scheme

 * PECL packages from standard pecl channel should be named php-pecl-PECLPackageName-%{version}-%{release}.%{arch}.rpm.
 * PEAR packages from standard pear channel should be named php-pear-PEARPackageName-%{version}-%{release}.noarch.rpm.
 * CHANNEL packages should be named php-channel-ChannelAlias-%{version}-%{release}.noarch.rpm
 * Packages from another channel should be named php-ChannelAlias-PackageName-%{version}-%{release}.noarch.rpm.
 * Other packages should be named php-PackageName-%{version}-%{release}.%{arch}.rpm; %{arch} can be "noarch" where appropriate.

Please make sure that the PEAR package is correctly being built for noarch.

The PECLPackageName and the PEARPackageName should be consistent with the upstream naming scheme. The Crack PHP Extension would thus be named php-pecl-crack with the resulting packages being php-pecl-crack-0.4-1.i386.rpm and php-pecl-crack-0.4-1.src.rpm.

Note that web applications that happen to be written in PHP do not belong under the php-* namespace.

File Placement
Non-PEAR PHP software which provides shared libraries should put its PHP source files for such shared libraries in a subfolder of /usr/share/php, named according to the name of the software. For example, a library called "Whizz_Bang" (with a RPM called php-something-Whizz-Bang) would put the PHP source files for its shared libraries in /usr/share/php/Whizz_Bang.

PEAR documentation provided by upstream are installed in %{pear_docdir}, should stay there, and must be marked as %doc.

PEAR Packages from the standard channel/repository
A PEAR package MUST have:

BuildRequires: php-pear(PEAR) Requires: php-pear(PEAR) Requires(post): %{__pear} Requires(postun): %{__pear} Provides:    php-pear(foo) = %{version}

Packages for CHANNEL (repository) configuration
A CHANNEL package 'MUST have : Requires: php-pear(PEAR) Requires(post): %{__pear} Requires(postun): %{__pear} Provides: php-channel(channelname)

PEAR Packages from a non standard channel/repository
A PEAR package MUST have:

BuildRequires: php-channel(channelname) BuildRequires: php-pear(PEAR) Requires: php-pear(PEAR) Requires(post): %{__pear} Requires(postun): %{__pear} Requires: php-channel(channelname) Provides:    php-pear(channelname/foo) = %{version}

C extensions (PECL and others)
To be certain that a binary extension will run correctly with a particular version of PHP, it is necessary to check that a particular package has both API and ABIs matching the installed version of PHP. The mechanism for doing this has evolved over time and is as follows:

For Fedora (all current versions): BuildRequires: php-devel Requires:     php(zend-abi) = %{php_zend_api} Requires:     php(api) = %{php_core_api}

PECL Packages
PECL extension MUST have ABI check (see previous)

A PECL package MUST also have:

BuildRequires: php-pear Requires(post): %{__pecl} Requires(postun): %{__pecl}

Provides:    php-pecl(foo) = %{version}

Other Packages
PHP addons which are neither PEAR nor PECL should require what makes sense (either a base PHP version or a php-api, php(zend-abi) as necessary).

PHP ZTS extension
When the Apache HTTPD is run in worker mode (instead of prefork mode), the ZTS (Zend Thread Safe) version of PHP is used.

If an extension maintainer wants to provide a ZTS version of this extension, the maintainer must ensure that:
 * the extension is thread safe
 * the libraries used by the extension are thread safe

The php-devel package in fedora >= 17 (5.4.0) provides the necessary files to build ZTS modules and provides several new helper macros:

For standard (NTS) extensions %{__php}         %{_bindir}/php %{php_extdir}    %{_libdir}/php/modules %{php_inidir}    %{_sysconfdir}/php.d %{php_incldir     %{_includedir}/php

For ZTS extensions %{__ztsphp}      %{_bindir}/zts-php %{php_ztsextdir} %{_libdir}/php-zts/modules %{php_ztsinidir} %{_sysconfdir}/php-zts.d %{php_ztsincldir  %{_includedir}/php-zts/php

php-devel provides the executables needed during the build of a ZTS extension, which are:
 * zts-phpize
 * zts-php-config
 * zts-php (which is only useful to run the test suite during build)

Packages for CHANNEL (repository) configuration
Here are some recommended scriptlets for properly registering and unregistering the channel:

%post if [ $1 -eq 1 ] ; then %{__pear} channel-add %{pear_xmldir}/%{name}.xml > /dev/null || : else %{__pear} channel-update %{pear_xmldir}/%{name}.xml > /dev/null ||: fi

%postun if [ $1 -eq 0 ] ; then %{__pear} channel-delete %{channelname} > /dev/null || : fi

PEAR Modules
The php-pear package in Fedora Core 5 and above (version 1:1.4.9-1.2) provides several useful macros:
 * %{pear_phpdir}
 * %{pear_docdir} (This evaluates to %{_docdir}/pear.)
 * %{pear_testdir}
 * %{pear_datadir}
 * %{pear_xmldir}

These definitions for the .spec should be of interest: BuildRequires:   php-pear >= 1:1.4.9-1.2 Provides:        php-pear(PackageName) = %{version} Requires:        php-common >= 4.3, php-pear(PEAR) Requires(post):  %{_bindir}/pear Requires(postun): %{_bindir}/pear

Here are some recommended scriptlets for properly registering the module: %post %{_bindir}/pear install --nodeps --soft --force --register-only %{pear_xmldir}/%{name}.xml >/dev/null ||:

And here are some recommended scriptlets for properly unregistering the module, from the standard channel: %postun if [ "$1" -eq "0" ] ; then %{_bindir}/pear uninstall --nodeps --ignore-errors --register-only Foo_Bar >/dev/null ||: fi

From a non standard channel (pear command requires the channel): %postun if [ "$1" -eq "0" ] ; then %{_bindir}/pear uninstall --nodeps --ignore-errors --register-only Foo_channel/Foo_Bar >/dev/null ||: fi

PECL Modules
The php-pear package in Fedora Core 5 and above (version 1:1.4.9-1.2) provides several useful macros:
 * %{pecl_phpdir}
 * %{pecl_docdir}
 * %{pecl_testdir}
 * %{pecl_datadir}
 * %{pecl_xmldir}

You may need to define a few additional macros to extract some information from PHP. It is recommended that you use the following: %global php_apiver %((echo 0; php -i 2>/dev/null | sed -n 's/^PHP API => //p') | tail -1) %{!?__pecl:    %{expand: %%global __pecl     %{_bindir}/pecl}} %{!?php_extdir: %{expand: %%global php_extdir %(php-config --extension-dir)}}

And here are some recommended scriptlets for properly registering and unregistering the module: %post %{pecl_install} %{pecl_xmldir}/%{name}.xml >/dev/null || :

%postun if [ $1 -eq 0 ] ; then %{pecl_uninstall} %{pecl_name} >/dev/null || : fi

Other Modules
If your module includes compiled code, you may need to define some macros to extract some information from PHP. It is recommended that you user the following: %global php_apiver %((echo 0; php -i 2>/dev/null | sed -n 's/^PHP API => //p') | tail -1) %global php_extdir %(php-config --extension-dir 2>/dev/null || echo "undefined") %global php_version %(php-config --version 2>/dev/null || echo 0)

PEAR & PECL Packages
The source archive contains a package.xml outside any directory, so you have to use use %setup -q -c in your %prep section to avoid writing files to the build root.

PEAR Packages
To create your initial specfile, you can use the default template provided by the rpmdevtools package:

fedora-newrpmspec -t php-pear php-pear-Foo

Or you can generate one; make sure you have the php-pear-PEAR-Command-Packaging package installed:

pear make-rpm-spec Foo.tgz