From 84de144a43c1232a55a311a74d095b68df293839 Mon Sep 17 00:00:00 2001 From: Otto Urpelainen Date: Sep 23 2021 20:52:53 +0000 Subject: [PATCH 1/5] Use sematic linebreaks in PHP guidelines The repository README recommends using semantic linebreaks and they are a good idea in any case, so the PHP Guidelines are converted to use them here so that further, immediately following, commits will get easy-to-read diffs. --- diff --git a/guidelines/modules/ROOT/pages/PHP.adoc b/guidelines/modules/ROOT/pages/PHP.adoc index 4c032cd..113de9e 100644 --- a/guidelines/modules/ROOT/pages/PHP.adoc +++ b/guidelines/modules/ROOT/pages/PHP.adoc @@ -7,54 +7,114 @@ Fedora Packaging Guidelines for PHP addon modules There are basically 4 different kinds of PHP modules, which are packaged for Fedora: -* http://pecl.php.net[PECL] (PHP Extention Community Library), which are PHP modules usually written in C, which are dynamically loaded by the PHP interpreter on startup. -* http://pear.php.net[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. -* Composer registered libraries, which are reusable components written in PHP, usually PSR-O compliant classes, registered on a package registry, most often on https://packagist.org/[Packagist]. -* CHANNEL : a package which register a channel. A channel is a repository which provides PHP extensions +* http://pecl.php.net[PECL] (PHP Extention Community Library), +which are PHP modules usually written in C, +which are dynamically loaded by the PHP interpreter on startup. + +* http://pear.php.net[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. + +* Composer registered libraries, +which are reusable components written in PHP, +usually PSR-O compliant classes, +registered on a package registry, +most often on https://packagist.org/[Packagist]. + +* 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. +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 -* `+pear.php.net+` (alias pear) : the default channel for PHP Extension and Application Repository -* `+pecl.php.net+` (alias pecl) : the default channel for PHP Extension Community Library -* `+__uri+` : Pseudo-channel for static packages +* `+pear.php.net+` (alias pear) : +the default channel for PHP Extension and Application Repository -Other channels must be configured at RPM build time and at at RPM installation time. +* `+pecl.php.net+` (alias pecl) : +the default channel for PHP Extension Community Library + +* `+__uri+` : +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. -* Composer enabled packages (referenced in packagist.org or another registry) should be named _php-vendor-library-%\{version}-%\{release}.noarch.rpm_ (where "vendor/library" is the known packagist name, "name" attribute in composer.json). When vendor = library, one can be droped (ex symfony/symfony can be named php-symfony). -* Other packages should be named _php-PackageName-%\{version}-%\{release}.%\{arch}.rpm_; %\{arch} can be "noarch" where appropriate. +* 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. -Please make sure that a pure PHP package (PEAR, packagist...) is correctly being built for noarch. +* CHANNEL packages should be named +php-channel-ChannelAlias-%\{version}-%\{release}.noarch.rpm -As for other packages, name should only use lowercase, underscore and slash replaced by dash. +* Packages from another channel should be named +php-ChannelAlias-PackageName-%\{version}-%\{release}.noarch.rpm. -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_. +* Composer enabled packages +(referenced in packagist.org or another registry) +should be named +_php-vendor-library-%\{version}-%\{release}.noarch.rpm_ +(where "vendor/library" is the known packagist name, +"name" attribute in composer.json). +When vendor = library, one can be droped +(ex symfony/symfony can be named php-symfony). -Note that applications that happen to be written in PHP do not belong under the php-* namespace. +* Other packages should be named +_php-PackageName-%\{version}-%\{release}.%\{arch}.rpm_; +%\{arch} can be "noarch" where appropriate. + +Please make sure that a pure PHP package (PEAR, packagist...) +is correctly being built for noarch. + +As for other packages, +name should only use lowercase, underscore and slash replaced by dash. + +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 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. +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. -A PSR-0 footnote:[https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md[PSR-0]] -compliant library would put its PHP files in /usr/share/php/ +A PSR-0 footnote:[https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md[PSR-0]] compliant library +would put its PHP files in /usr/share/php/ -A PSR-4 footnote:[https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md[PSR-4]] compliant library would put its PHP files -in /usr/share/php/ in a PSR-0 compliant tree. -PEAR documentation provided by upstream are installed in %\{pear_docdir}, should stay there, and must be marked as %doc. +A PSR-4 footnote:[https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md[PSR-4]] compliant library +would put its PHP files in /usr/share/php/ +in a PSR-0 compliant tree. -PECL documentation provided by upstream are installed in %\{pecl_docdir}, should stay there, and must be marked as %doc. +PEAR documentation provided by upstream are installed in %\{pear_docdir}, +should stay there, +and must be marked as %doc. -The composer.json file is not used, and should be installed as %doc as it provides useful information about the package and its dependencies. +PECL documentation provided by upstream are installed in %\{pecl_docdir}, +should stay there, +and must be marked as %doc. + +The composer.json file is not used, +and should be installed as %doc +as it provides useful information about the package and its dependencies. == Requires and Provides @@ -70,9 +130,13 @@ Requires(postun): %{__pear} Provides: php-pear(foo) = %{version} .... -The virtual provide should match exactly upstream name, including case and underscore, ex: php-pear(Text_Wiki) +The virtual provide should match exactly upstream name, +including case and underscore, ex: php-pear(Text_Wiki) -A PEAR package must have all its dependencies available as PEAR packages, so should only requires those using the php-pear(foo) virtual provides. Known exception for unbundled libraries (which are often bundled because not available in any pear channel). +A PEAR package must have all its dependencies available as PEAR packages, +so should only requires those using the php-pear(foo) virtual provides. +Known exception for unbundled libraries +(which are often bundled because not available in any pear channel). === Packages for CHANNEL (repository) configuration @@ -101,7 +165,10 @@ Provides: php-pear(channelname/foo) = %{version} === Composer registered Packages -Each package registered on https://packagist.org/[Packagist] (which is the most widely used registry, so defined as the implicit one) *MUST* have +Each package registered on https://packagist.org/[Packagist] +(which is the most widely used registry, +so defined as the implicit one) +*MUST* have .... Provides: php-composer(vendor/library) = %{version} @@ -113,28 +180,59 @@ Package registered on another registry *MUST* have Provides: php-composer(registry_url/vendor/library) = %{version} .... -The virtual provide should match exactly upstream name, including underscore, ex: php-composer(pear/console_table) +The virtual provide should match exactly upstream name, +including underscore, +ex: php-composer(pear/console_table) -Packages moved from PEAR to Composer/Packagist should also provides php-pear(foo) when needed (used by other pear packages). +Packages moved from PEAR to Composer/Packagist +should also provides php-pear(foo) +when needed (used by other pear packages). -Packages must not require any php-pear(foo), but should use php-composer(pear/foo). +Packages must not require any php-pear(foo), +but should use php-composer(pear/foo). -Composer.json useful attributes (see https://getcomposer.org/doc/04-schema.md[Composer schema documentation]) +Composer.json useful attributes +(see https://getcomposer.org/doc/04-schema.md[Composer schema documentation]) * name + * description : 1 line, could be used as RPM summary attribute + * homepage : could be used as RPM URL attribute + * license -* require : describes mandatory dependencies: PHP version, PHP extensions or other composer libraries, those must be required by the RPM package as php-composer(foo) -* require-dev : describes development dependencies, usually useful a build time (ex: to run unit test), so could appears as BuidRequires -* suggest : describes optional dependencies, so could appears as Requires (packager choice) + +* require : +describes mandatory dependencies +PHP version, +PHP extensions +or other composer libraries, +those must be required by the RPM package as php-composer(foo) + +* require-dev : +describes development dependencies, +usually useful a build time (ex: to run unit test), +so could appears as BuidRequires + +* suggest : +describes optional dependencies, +so could appears as Requires (packager choice) + * conflict : as RPM Conflicts + * replace : as RPM Obsoletes -* provide : for additional virtual provides, must also be in RPM Provides as php-composer(foo) + +* provide : +for additional virtual provides, +must also be in RPM Provides as php-composer(foo) === 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: +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): @@ -157,7 +255,8 @@ Provides: php-pecl(foo)%{?_isa} = %{version} === PECL Packages from a non standard channel/repository -A PECL package from a non standard channel MUST have (instead of previous provides) +A PECL package from a non standard channel MUST have +(instead of previous provides) .... Requires: php-channel(channelname) @@ -167,42 +266,69 @@ Provides: php-pecl(channelname/foo)%{?_isa} = %{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 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, ...). +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. +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. +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 and RHEL/EPEL-6, but does NOT work for RHEL/EPEL-5. For RHEL/EPEL-5 packages, you will need to use Requires: php-common >= $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 and RHEL/EPEL-6, +but does NOT work for RHEL/EPEL-5. +For RHEL/EPEL-5 packages, +you will need to use Requires: php-common >= $VERSION. == C extensions and PECL packages configuration file -Each extension should drop a configuration file in %\{php_inidir} and/or %\{php_ztsinidir} to enable the extension. This file must contains the name of the loaded extension. The file must use a numeric prefix to ensure correct load order: +Each extension should drop a configuration file +in %\{php_inidir} and/or %\{php_ztsinidir} +to enable the extension. +This file must contains the name of the loaded extension. +The file must use a numeric prefix to ensure correct load order: -* range 00-19 is reserved for zend_extensions (ex: 10-opcache.ini, 15-xdebug.ini...) -* range 20-39 is reserved for extensions from php sources (ex: 20-pdo.ini, 30-pdo_pgsql.ini...) -* range 40-99 is available for other extensions (ex: 40-zip.ini...) +* range 00-19 is reserved for zend_extensions +(ex: 10-opcache.ini, 15-xdebug.ini...) + +* range 20-39 is reserved for extensions from php sources +(ex: 20-pdo.ini, 30-pdo_pgsql.ini...) + +* range 40-99 is available for other extensions +(ex: 40-zip.ini...) == 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. +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: +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: +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 @@ -222,7 +348,8 @@ For ZTS extensions %{php_ztsincldir %{_includedir}/php-zts/php .... -php-devel provides the executables needed during the build of a ZTS extension, which are: +php-devel provides the executables needed during the build of a ZTS extension, +which are: * zts-phpize * zts-php-config @@ -230,7 +357,8 @@ php-devel provides the executables needed during the build of a ZTS extension, w === Packages for CHANNEL (repository) configuration -Here are some recommended scriptlets for properly registering and unregistering the channel: +Here are some recommended scriptlets +for properly registering and unregistering the channel: .... %post @@ -251,11 +379,18 @@ fi The php-pear package provides several useful macros: * %\{pear_phpdir} + * %\{pear_docdir} (This evaluates to %\{_docdir}/pear.) + * %\{pear_testdir} + * %\{pear_datadir} + * %\{pear_xmldir} -* %\{pear_metadir} (This evaluates to %\{pear_phpdir}, except in Fedora 19+, where it evaluates to /var/lib/pear.) + +* %\{pear_metadir} +(This evaluates to %\{pear_phpdir}, +except in Fedora 19+, where it evaluates to /var/lib/pear.) These definitions for the .spec should be of interest: @@ -280,7 +415,8 @@ Here are some recommended scriptlets for properly registering the module: %{_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: +And here are some recommended scriptlets for properly unregistering the module, +from the standard channel: .... %postun @@ -300,7 +436,8 @@ fi === PECL Modules -The php-pear package in Fedora Core 5 and above (version 1:1.4.9-1.2) provides several useful macros: +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} @@ -308,7 +445,9 @@ The php-pear package in Fedora Core 5 and above (version 1:1.4.9-1.2) provides s * %\{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: +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) @@ -316,9 +455,12 @@ You may need to define a few additional macros to extract some information from %{!?php_extdir: %{expand: %%global php_extdir %(php-config --extension-dir)}} .... -Module (un)registration is handled automatically by file triggers in the php-pear package. +Module (un)registration is handled automatically +by file triggers in the php-pear package. -For older releases, here are some recommended scriptlets for properly registering and unregistering a module: +For older releases, +here are some recommended scriptlets +for properly registering and unregistering a module: .... BuildRequires: php-pear @@ -337,7 +479,10 @@ 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: +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) @@ -349,7 +494,8 @@ If your module includes compiled code, you may need to define some macros to ext === PEAR & PECL Packages -The source archive contains a package.xml outside any directory, so you have to use use +The source archive contains a package.xml outside any directory, +so you have to use use .... %setup -q -c @@ -359,13 +505,15 @@ 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: +To create your initial specfile, +you can use the default template provided by the rpmdevtools package: .... rpmdev-newspec -t php-pear php-pear-Foo .... -Or you can generate one; make sure you have the php-pear-PEAR-Command-Packaging package installed: +Or you can generate one; +make sure you have the php-pear-PEAR-Command-Packaging package installed: .... pear make-rpm-spec Foo.tgz From 32af34650810a9e0582cef851d876f87210587ac Mon Sep 17 00:00:00 2001 From: Otto Urpelainen Date: Sep 23 2021 20:52:53 +0000 Subject: [PATCH 2/5] Fix formatting, grammar and typos in PHP guidelines --- diff --git a/guidelines/modules/ROOT/pages/PHP.adoc b/guidelines/modules/ROOT/pages/PHP.adoc index 113de9e..62a4b5c 100644 --- a/guidelines/modules/ROOT/pages/PHP.adoc +++ b/guidelines/modules/ROOT/pages/PHP.adoc @@ -7,35 +7,35 @@ Fedora Packaging Guidelines for PHP addon modules There are basically 4 different kinds of PHP modules, which are packaged for Fedora: -* http://pecl.php.net[PECL] (PHP Extention Community Library), -which are PHP modules usually written in C, -which are dynamically loaded by the PHP interpreter on startup. +* http://pecl.php.net[PECL] (PHP Extension Community Library) modules, +which are PHP modules usually written in C +and are dynamically loaded by the PHP interpreter on startup. -* http://pear.php.net[PEAR] (PHP Extension and Application Repository), +* http://pear.php.net[PEAR] (PHP Extension and Application Repository) modules, 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. +by using e.g. the `+include()+` directive. * Composer registered libraries, which are reusable components written in PHP, -usually PSR-O compliant classes, +usually PSR-0 compliant classes, registered on a package registry, most often on https://packagist.org/[Packagist]. -* CHANNEL : a package which register a channel. -A channel is a repository which provides PHP extensions +* CHANNEL : packages which register a channel. +A channel is a repository which provides PHP extensions. -* Other package providing PHP extension not handled by PEAR/PECL mechanisms +* Other packages providing a PHP extension not handled by PEAR/PECL mechanisms. -While upstream used the same package and distribution format for PECL and PEAR, +While upstream uses 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 +3 channels are defined on installation of `+php-pear+`: -* `+pear.php.net+` (alias pear) : +* `+pear.php.net+` (alias `+pear+`) : the default channel for PHP Extension and Application Repository -* `+pecl.php.net+` (alias pecl) : +* `+pecl.php.net+` (alias `+pecl+`) : the default channel for PHP Extension Community Library * `+__uri+` : @@ -47,73 +47,73 @@ and at at RPM installation time. == Naming scheme * PECL packages from standard pecl channel should be named -php-pecl-PECLPackageName-%\{version}-%\{release}.%\{arch}.rpm. +`+php-pecl-PECLPackageName-%{version}-%{release}.%{arch}.rpm+`. * PEAR packages from standard pear channel should be named -php-pear-PEARPackageName-%\{version}-%\{release}.noarch.rpm. +`+php-pear-PEARPackageName-%{version}-%{release}.noarch.rpm+`. * CHANNEL packages should be named -php-channel-ChannelAlias-%\{version}-%\{release}.noarch.rpm +`+php-channel-ChannelAlias-%{version}-%{release}.noarch.rpm+` * Packages from another channel should be named -php-ChannelAlias-PackageName-%\{version}-%\{release}.noarch.rpm. +`+php-ChannelAlias-PackageName-%{version}-%{release}.noarch.rpm+` * Composer enabled packages (referenced in packagist.org or another registry) should be named -_php-vendor-library-%\{version}-%\{release}.noarch.rpm_ -(where "vendor/library" is the known packagist name, -"name" attribute in composer.json). -When vendor = library, one can be droped -(ex symfony/symfony can be named php-symfony). +`+php-vendor-library-%{version}-%{release}.noarch.rpm+` +(where `+vendor/library+` is the known packagist name, +`+name+` attribute in `+composer.json+`). +When `+vendor+` equals `+library+`, one can be dropped +(ex `+symfony/symfony+` can be named `+php-symfony+`). * Other packages should be named -_php-PackageName-%\{version}-%\{release}.%\{arch}.rpm_; -%\{arch} can be "noarch" where appropriate. +`+php-PackageName-%{version}-%{release}.%{arch}.rpm+`; +`+%{arch}+` can be `+noarch+` where appropriate. Please make sure that a pure PHP package (PEAR, packagist...) -is correctly being built for noarch. +is correctly being built for `+noarch+`. As for other packages, name should only use lowercase, underscore and slash replaced by dash. -The PECLPackageName and the PEARPackageName should be consistent +The `+PECLPackageName+` and the `+PEARPackageName+` should be consistent with the upstream naming scheme. -The Crack PHP Extension would thus be named _php-pecl-crack_ +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_. +`+php-pecl-crack-0.4-1.i386.rpm+` and `+php-pecl-crack-0.4-1.src.rpm+`. Note that applications that happen to be written in PHP -do not belong under the php-* namespace. +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, +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) +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. +in `+/usr/share/php/Whizz_Bang+`. A PSR-0 footnote:[https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md[PSR-0]] compliant library -would put its PHP files in /usr/share/php/ +would put its PHP files in `+/usr/share/php/+` A PSR-4 footnote:[https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md[PSR-4]] compliant library -would put its PHP files in /usr/share/php/ +would put its PHP files in `+/usr/share/php/+` in a PSR-0 compliant tree. -PEAR documentation provided by upstream are installed in %\{pear_docdir}, +PEAR documentation provided by upstream are installed in `+%{pear_docdir}+`, should stay there, -and must be marked as %doc. +and must be marked as `+%doc+`. -PECL documentation provided by upstream are installed in %\{pecl_docdir}, +PECL documentation provided by upstream is installed in `+%{pecl_docdir}+`, should stay there, -and must be marked as %doc. +and must be marked as `+%doc+`. -The composer.json file is not used, -and should be installed as %doc +The `+composer.json+` file is not used, +and should be installed as `+%doc+` as it provides useful information about the package and its dependencies. == Requires and Provides @@ -123,30 +123,30 @@ as it provides useful information about the package and its dependencies. A PEAR package *MUST* have: .... -BuildRequires: php-pear(PEAR) -Requires: php-pear(PEAR) -Requires(post): %{__pear} +BuildRequires: php-pear(PEAR) +Requires: php-pear(PEAR) +Requires(post): %{__pear} Requires(postun): %{__pear} -Provides: php-pear(foo) = %{version} +Provides: php-pear(foo) = %{version} .... The virtual provide should match exactly upstream name, -including case and underscore, ex: php-pear(Text_Wiki) +including case and underscore, ex: `+php-pear(Text_Wiki)+` A PEAR package must have all its dependencies available as PEAR packages, -so should only requires those using the php-pear(foo) virtual provides. +so should only requires those using the `+php-pear(foo)+` virtual provides. Known exception for unbundled libraries -(which are often bundled because not available in any pear channel). +(which are often bundled because not available in any PEAR channel). === Packages for CHANNEL (repository) configuration -A CHANNEL package *'MUST* have : +A CHANNEL package *MUST* have : .... -Requires: php-pear(PEAR) -Requires(post): %{__pear} +Requires: php-pear(PEAR) +Requires(post): %{__pear} Requires(postun): %{__pear} -Provides: php-channel(channelname) +Provides: php-channel(channelname) .... === PEAR Packages from a non standard channel/repository @@ -154,13 +154,13 @@ Provides: php-channel(channelname) A PEAR package *MUST* have: .... -BuildRequires: php-channel(channelname) -BuildRequires: php-pear(PEAR) -Requires: php-pear(PEAR) -Requires(post): %{__pear} +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} +Requires: php-channel(channelname) +Provides: php-pear(channelname/foo) = %{version} .... === Composer registered Packages @@ -182,49 +182,49 @@ Provides: php-composer(registry_url/vendor/library) = %{version} The virtual provide should match exactly upstream name, including underscore, -ex: php-composer(pear/console_table) +ex: `+php-composer(pear/console_table)+` Packages moved from PEAR to Composer/Packagist -should also provides php-pear(foo) -when needed (used by other pear packages). +should also Provide `+php-pear(foo)+` +when needed (used by other PEAR packages). -Packages must not require any php-pear(foo), -but should use php-composer(pear/foo). +Packages must not Require any `+php-pear(foo)+`, +but should use `+php-composer(pear/foo)+`. -Composer.json useful attributes +`+composer.json+` useful attributes (see https://getcomposer.org/doc/04-schema.md[Composer schema documentation]) -* name +* `+name+` -* description : 1 line, could be used as RPM summary attribute +* `+description+` : 1 line, could be used as RPM summary attribute -* homepage : could be used as RPM URL attribute +* `+homepage+` : could be used as RPM URL attribute -* license +* `+license+` -* require : +* `+require+` : describes mandatory dependencies PHP version, PHP extensions or other composer libraries, -those must be required by the RPM package as php-composer(foo) +those must be required by the RPM package as `+php-composer(foo)+` -* require-dev : +* `+require-dev+` : describes development dependencies, usually useful a build time (ex: to run unit test), -so could appears as BuidRequires +so could appear as BuidRequires -* suggest : +* `+suggest+` : describes optional dependencies, -so could appears as Requires (packager choice) +so could appear as Requires (packager choice) -* conflict : as RPM Conflicts +* `+conflict+` : as RPM Conflicts -* replace : as RPM Obsoletes +* `+replace+` : as RPM Obsoletes -* provide : +* `+provide+` : for additional virtual provides, -must also be in RPM Provides as php-composer(foo) +must also be in RPM Provides as `+php-composer(foo)+` === C extensions (PECL and others) @@ -268,50 +268,50 @@ Provides: php-pecl(channelname/foo)%{?_isa} = %{version} 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). +(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, +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, ...). +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. +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, ...). +(`+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). +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 and RHEL/EPEL-6, but does NOT work for RHEL/EPEL-5. For RHEL/EPEL-5 packages, -you will need to use Requires: php-common >= $VERSION. +you will need to use `+Requires: php-common >= $VERSION+`. == C extensions and PECL packages configuration file Each extension should drop a configuration file -in %\{php_inidir} and/or %\{php_ztsinidir} +in `+%{php_inidir}+` and/or `+%{php_ztsinidir}+` to enable the extension. This file must contains the name of the loaded extension. The file must use a numeric prefix to ensure correct load order: * range 00-19 is reserved for zend_extensions -(ex: 10-opcache.ini, 15-xdebug.ini...) +(ex: `+10-opcache.ini+`, `+15-xdebug.ini+`, ...) * range 20-39 is reserved for extensions from php sources -(ex: 20-pdo.ini, 30-pdo_pgsql.ini...) +(ex: `+20-pdo.ini+`, `+30-pdo_pgsql.ini+`, ...) * range 40-99 is available for other extensions -(ex: 40-zip.ini...) +(ex: `+40-zip.ini+`, ...) == Macros and scriptlets @@ -326,7 +326,7 @@ 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) +The `+php-devel+` package in fedora >= 17 (5.4.0) provides the necessary files to build ZTS modules and provides several new helper macros: @@ -348,12 +348,12 @@ For ZTS extensions %{php_ztsincldir %{_includedir}/php-zts/php .... -php-devel provides the executables needed during the build of a ZTS extension, +`+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) +* `+zts-phpize+` +* `+zts-php-config+` +* `+zts-php+` (which is only useful to run the test suite during build) === Packages for CHANNEL (repository) configuration @@ -376,21 +376,21 @@ fi === PEAR Modules -The php-pear package provides several useful macros: +The `+php-pear+` package provides several useful macros: -* %\{pear_phpdir} +* `+%{pear_phpdir}+` -* %\{pear_docdir} (This evaluates to %\{_docdir}/pear.) +* `+%{pear_docdir}+` (This evaluates to `+%{_docdir}/pear+`.) -* %\{pear_testdir} +* `+%{pear_testdir}+` -* %\{pear_datadir} +* `+%{pear_datadir}+` -* %\{pear_xmldir} +* `+%{pear_xmldir}+` -* %\{pear_metadir} -(This evaluates to %\{pear_phpdir}, -except in Fedora 19+, where it evaluates to /var/lib/pear.) +* `+%{pear_metadir}+` +(This evaluates to `+%{pear_phpdir}+`, +except in Fedora 19+, where it evaluates to `+/var/lib/pear+`.) These definitions for the .spec should be of interest: @@ -402,7 +402,7 @@ Requires(post): %{_bindir}/pear Requires(postun): %{_bindir}/pear .... -Be sure you delete any PEAR metadata files at the end of %install: +Be sure you delete any PEAR metadata files at the end of `+%install+`: .... rm -rf %{buildroot}/%{pear_metadir}/.??* @@ -425,7 +425,7 @@ if [ "$1" -eq "0" ] ; then fi .... -From a non standard channel (pear command requires the channel): +From a non standard channel (`+pear+` command requires the channel): .... %postun @@ -436,14 +436,14 @@ fi === PECL Modules -The php-pear package in Fedora Core 5 and above (version 1:1.4.9-1.2) +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} +* `+%{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. @@ -456,7 +456,7 @@ It is recommended that you use the following: .... Module (un)registration is handled automatically -by file triggers in the php-pear package. +by file triggers in the `+php-pear+` package. For older releases, here are some recommended scriptlets @@ -494,26 +494,26 @@ It is recommended that you user the following: === PEAR & PECL Packages -The source archive contains a package.xml outside any directory, +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. +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: +you can use the default template provided by the `+rpmdevtools+` package: .... rpmdev-newspec -t php-pear php-pear-Foo .... Or you can generate one; -make sure you have the php-pear-PEAR-Command-Packaging package installed: +make sure you have the `+php-pear-PEAR-Command-Packaging+` package installed: .... pear make-rpm-spec Foo.tgz From c17722645e7c433075772769fdb96ffa5e95a625 Mon Sep 17 00:00:00 2001 From: Otto Urpelainen Date: Sep 23 2021 20:52:53 +0000 Subject: [PATCH 3/5] Use macros for system paths in PHP guidelines Specfiles are expected to be written using macros for system paths like %{_datadir}. Use them in the guidelines too, so that just copying values to specfiles gives the desired result. --- diff --git a/guidelines/modules/ROOT/pages/PHP.adoc b/guidelines/modules/ROOT/pages/PHP.adoc index 62a4b5c..5ce92d0 100644 --- a/guidelines/modules/ROOT/pages/PHP.adoc +++ b/guidelines/modules/ROOT/pages/PHP.adoc @@ -90,18 +90,18 @@ do not belong under the `+php-*+` namespace. 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+`, +in a subfolder of `+%{_datadir}/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+`. +in `+%{_datadir}/php/Whizz_Bang+`. A PSR-0 footnote:[https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-0.md[PSR-0]] compliant library -would put its PHP files in `+/usr/share/php/+` +would put its PHP files in `+%{_datadir}/php/+` A PSR-4 footnote:[https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md[PSR-4]] compliant library -would put its PHP files in `+/usr/share/php/+` +would put its PHP files in `+%{_datadir}/php/+` in a PSR-0 compliant tree. PEAR documentation provided by upstream are installed in `+%{pear_docdir}+`, From 431c8acfb5fa6081d9de791df92f2c6ab434829d Mon Sep 17 00:00:00 2001 From: Otto Urpelainen Date: Sep 23 2021 20:52:53 +0000 Subject: [PATCH 4/5] Remove references to end-of-life releases from PHP guidelines --- diff --git a/guidelines/modules/ROOT/pages/PHP.adoc b/guidelines/modules/ROOT/pages/PHP.adoc index 5ce92d0..b942c07 100644 --- a/guidelines/modules/ROOT/pages/PHP.adoc +++ b/guidelines/modules/ROOT/pages/PHP.adoc @@ -232,9 +232,7 @@ 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): +The mechanism for doing this is as follows: .... BuildRequires: php-devel @@ -291,10 +289,6 @@ These extensions are virtual Provides of the php sub-packages. 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 and RHEL/EPEL-6, -but does NOT work for RHEL/EPEL-5. -For RHEL/EPEL-5 packages, -you will need to use `+Requires: php-common >= $VERSION+`. == C extensions and PECL packages configuration file @@ -326,9 +320,9 @@ 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: +The `+php-devel+` package provides the necessary files +to build ZTS modules +and provides several helper macros: For standard (NTS) extensions @@ -379,18 +373,11 @@ fi The `+php-pear+` package provides several useful macros: * `+%{pear_phpdir}+` - * `+%{pear_docdir}+` (This evaluates to `+%{_docdir}/pear+`.) - * `+%{pear_testdir}+` - * `+%{pear_datadir}+` - * `+%{pear_xmldir}+` - -* `+%{pear_metadir}+` -(This evaluates to `+%{pear_phpdir}+`, -except in Fedora 19+, where it evaluates to `+/var/lib/pear+`.) +* `+%{pear_metadir}+` (This evaluates to `+/var/lib/pear+`.) These definitions for the .spec should be of interest: @@ -436,8 +423,7 @@ fi === PECL Modules -The `+php-pear+` package in Fedora Core 5 and above (version 1:1.4.9-1.2) -provides several useful macros: +The `+php-pear+` package provides several useful macros: * `+%{pecl_phpdir}+` * `+%{pecl_docdir}+` From 961dbc62c627d8f92c88a74bbbf172d618184e28 Mon Sep 17 00:00:00 2001 From: Otto Urpelainen Date: Sep 23 2021 20:52:53 +0000 Subject: [PATCH 5/5] Add anchors and an xref to PHP guidelines --- diff --git a/guidelines/modules/ROOT/pages/PHP.adoc b/guidelines/modules/ROOT/pages/PHP.adoc index b942c07..7fd219a 100644 --- a/guidelines/modules/ROOT/pages/PHP.adoc +++ b/guidelines/modules/ROOT/pages/PHP.adoc @@ -3,6 +3,7 @@ Fedora Packaging Guidelines for PHP addon modules +[#types] == Different types of PHP packages There are basically 4 different kinds of PHP modules, which are packaged for Fedora: @@ -44,6 +45,7 @@ Pseudo-channel for static packages Other channels must be configured at RPM build time and at at RPM installation time. +[#naming-scheme] == Naming scheme * PECL packages from standard pecl channel should be named @@ -86,6 +88,7 @@ with the resulting packages being Note that applications that happen to be written in PHP do not belong under the `+php-*+` namespace. +[#file-placement] == File Placement Non-PEAR PHP software which provides shared libraries @@ -116,8 +119,10 @@ The `+composer.json+` file is not used, and should be installed as `+%doc+` as it provides useful information about the package and its dependencies. +[#requires-provides] == Requires and Provides +[#requires-provides-pear] === PEAR Packages from the standard channel/repository A PEAR package *MUST* have: @@ -138,6 +143,7 @@ so should only requires those using the `+php-pear(foo)+` virtual provides. Known exception for unbundled libraries (which are often bundled because not available in any PEAR channel). +[#requires-provides-channel] === Packages for CHANNEL (repository) configuration A CHANNEL package *MUST* have : @@ -149,6 +155,7 @@ Requires(postun): %{__pear} Provides: php-channel(channelname) .... +[#requires-provides-pear-nonstandard] === PEAR Packages from a non standard channel/repository A PEAR package *MUST* have: @@ -163,6 +170,7 @@ Requires: php-channel(channelname) Provides: php-pear(channelname/foo) = %{version} .... +[#requires-provides-composer] === Composer registered Packages Each package registered on https://packagist.org/[Packagist] @@ -226,6 +234,7 @@ so could appear as Requires (packager choice) for additional virtual provides, must also be in RPM Provides as `+php-composer(foo)+` +[#requires-provides-c] === C extensions (PECL and others) To be certain that a binary extension will run correctly @@ -240,9 +249,11 @@ Requires: php(zend-abi) = %{php_zend_api} Requires: php(api) = %{php_core_api} .... +[#requires-provides-pecl] === PECL Packages -PECL extension *MUST* have ABI check (see previous) +PECL extension *MUST* have ABI check +(see xref:requires-provides-c[C extensions] above). A PECL package *MUST* also have: @@ -251,6 +262,7 @@ Provides: php-pecl(foo) = %{version} Provides: php-pecl(foo)%{?_isa} = %{version} .... +[#requires-provides-pecl-nonstandard] === PECL Packages from a non standard channel/repository A PECL package from a non standard channel MUST have @@ -262,12 +274,14 @@ Provides: php-pecl(channelname/foo) = %{version} Provides: php-pecl(channelname/foo)%{?_isa} = %{version} .... +[#requires-provides-other] === 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). +[#requires-provides-httpd] === Apache requirement A PHP library must not have an explicit Requires on `+php+` or `+httpd+`, @@ -278,24 +292,27 @@ Only a PHP web application, which provides a specific Apache httpd configuration, should have a Requires on `+httpd+` and `+mod_php+`. +[#requires-provides-extensions] === 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. +[#requires-provides-min-php] === 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). -== C extensions and PECL packages configuration file +[#c-pecl-config-file] +== C extension and PECL package configuration files Each extension should drop a configuration file in `+%{php_inidir}+` and/or `+%{php_ztsinidir}+` to enable the extension. -This file must contains the name of the loaded extension. +This file must contain the name of the loaded extension. The file must use a numeric prefix to ensure correct load order: * range 00-19 is reserved for zend_extensions @@ -307,8 +324,10 @@ The file must use a numeric prefix to ensure correct load order: * range 40-99 is available for other extensions (ex: `+40-zip.ini+`, ...) +[#macros-scriptlets] == Macros and scriptlets +[#macros-scriptlets-zts] === PHP ZTS extension When the Apache HTTPD is run in worker mode (instead of prefork mode), @@ -349,6 +368,7 @@ which are: * `+zts-php-config+` * `+zts-php+` (which is only useful to run the test suite during build) +[#macros-scriptlets-channel] === Packages for CHANNEL (repository) configuration Here are some recommended scriptlets @@ -368,6 +388,7 @@ if [ $1 -eq 0 ] ; then fi .... +[#macros-scriptlets-pear] === PEAR Modules The `+php-pear+` package provides several useful macros: @@ -421,6 +442,7 @@ if [ "$1" -eq "0" ] ; then fi .... +[#macros-scriptlets-pecl] === PECL Modules The `+php-pear+` package provides several useful macros: @@ -463,6 +485,7 @@ if [ $1 -eq 0 ] ; then fi .... +[#macros-scriptlets-other] === Other Modules If your module includes compiled code, @@ -476,8 +499,10 @@ It is recommended that you user the following: %global php_version %(php-config --version 2>/dev/null || echo 0) .... +[#hints] == Additional Hints for Packagers +[#hints-pear-pecl] === PEAR & PECL Packages The source archive contains a `+package.xml+` outside any directory, @@ -489,6 +514,7 @@ so you have to use use in your `+%prep+` section to avoid writing files to the build root. +[#hints-pear] === PEAR Packages To create your initial specfile,