From c6941673221a6cd94dae44262c931a83444ddbdd Mon Sep 17 00:00:00 2001
From: Remi Collet <remi@fedoraproject.org>
Date: Dec 06 2024 06:43:45 +0000
Subject: Revising PHP packaging for PIE


---

diff --git a/guidelines/modules/ROOT/pages/PHP.adoc b/guidelines/modules/ROOT/pages/PHP.adoc
index 899cc04..8842f70 100644
--- a/guidelines/modules/ROOT/pages/PHP.adoc
+++ b/guidelines/modules/ROOT/pages/PHP.adoc
@@ -10,11 +10,13 @@ There are basically 4 different kinds of PHP modules, which are packaged for Fed
 * https://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.
+This will be deprecated in favor of PIE.
 
 * https://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.
+This is deprecated in favor of composer and discouraged.
 
 * Composer registered libraries,
 which are reusable components written in PHP,
@@ -24,6 +26,13 @@ most often on https://packagist.org/[Packagist].
 
 * CHANNEL : packages which register a channel.
 A channel is a repository which provides PHP extensions.
+This is deprecated and discouraged.
+
+* https://github.com/php/pie[PIE] registered extensions,
+which are PHP modules usually written in C and are dynamically loaded by
+the PHP interpreter on startup, registered on a package registry,
+most often on https://packagist.org/extensions[Packagist].
+
 
 * Other packages providing a PHP extension not handled by PEAR/PECL mechanisms.
 
@@ -68,6 +77,15 @@ should be named
 When `+vendor+` equals `+library+`, one can be dropped
 (ex `+symfony/symfony+` can be named `+php-symfony+`).
 
+* PIE enabled packages (referenced in packagist.org or another registry)
+should be named
+`+php-vendor-extension-%{version}-%{release}.%{arch}.rpm+`
+(where `+vendor/extension+` is the known packagist name,
+`+name+` attribute in `+composer.json+`).
+When `+vendor+` equals `+extension+`, one can be dropped
+(ex `+xdebug/xdebug+` can be named `+php-xdebug+`).
+
+
 * Other packages should be named
 `+php-PackageName-%{version}-%{release}.%{arch}.rpm+`;
 `+%{arch}+` can be `+noarch+` where appropriate.
@@ -248,6 +266,16 @@ Requires:      php(zend-abi) = %{php_zend_api}
 Requires:      php(api) = %{php_core_api}
 ....
 
+Each extension *MUST* also have (to track the move out/in of php-src),
+using the `+module+` name as reported by "php --modules"
+or the .so file name in lowercase.
+
+....
+Provides:     php-module = %{version}
+Provides:     php-module%{_isa} = %{version}
+....
+
+
 [#requires-provides-pecl]
 === PECL Packages
 
@@ -273,6 +301,20 @@ Provides: php-pecl(channelname/foo) = %{version}
 Provides: php-pecl(channelname/foo)%{?_isa} = %{version}
 ....
 
+[#requires-provides-pie]
+=== PIE Packages
+
+PIE extension *MUST* have ABI check
+(see xref:requires-provides-c[C extensions] above).
+
+Each package registered on Packagist
+(which is the most widely used registry, so defined as the implicit one)
+*MUST* have:
+
+....
+Provides:     php-pie(vendor/extension) = %{version}
+....
+
 [#requires-provides-other]
 === Other Packages
 
@@ -295,9 +337,13 @@ 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-json+`, `+php-gd+`, `+php-mbstring+`, ...).
 These extensions are virtual Provides of the php sub-packages.
 
+Can be ignored as always present:
+`+core+`, `+date+`, `+filter+`, `+hash+`, `+pcre+`, `+random+`,
+`+reflection+`, `+session+`, `+spl+`, `+standard+`.
+
 [#requires-provides-min-php]
 === Requiring a Minimum PHP version