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.

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.

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:

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).

Apache requirement

A PHP library must not have an explicit Requires on php or httpd, since these libraries could be used with any webserver or any SAPI (php-cli, php-cgi, php-fpm, ...).

Only a PHP web application, which provides a specific Apache httpd configuration, should have a Requires on httpd and mod_php.

Extensions Requires

PHP extensions must have a Requires on all of the dependent extensions (php-date, php-gd, php-mbstring, ...). These extensions are virtual Provides of the php sub-packages.

Requiring a Minimum PHP version

If you need to specify a minimum PHP version, the recommended method is to add a Requires: php(language) >= $VERSION (where $VERSION is the minimum PHP version). This works for all released versions of Fedora, but does NOT work for RHEL/EPEL. For RHEL/EPEL packages, you will need to use Requires: php-common >= $VERSION.

Macros and scriptlets

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:

Red Hat, Red Hat Enterprise Linux, the Shadowman logo, and JBoss are trademarks or registered trademarks of
Red Hat, Inc. or its subsidiaries in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.
The Fedora Project is maintained and driven by the community and sponsored by Red Hat. This is a community
maintained site. Red Hat is not responsible for content.