SIGs/PHP/PackagingTips

PHP Packaging Tips

Dependencies

PEAR/PECL

package.xml provided in pear/pecl channel archive describe the dependencies of the package, e.g.

 <dependencies>
  <required>
   <php>
    <min>5.3.0</min>
   </php>
   <package>
    <name>Foo</name>
    <channel>pear.php.net</channel>
    <min>2.0.0</min>
   </package>
  </required>
  <optional>
   <extension>
    <name>curl</name>
   </extension>
  </optional>
 </dependencies>

In your spec

# From package.xml - required
Requires: php(language) >= 5.3.0
Requires: php-pear(Foo) >= 2.0.0
# From package.xml - optional
Requires: php-curl

composer

composer.json provided in lot of libraries/applications describes the dependencies.

See The composer.json schema

• "require" becomes "Requires", using the virtual php-composer(foo)
• "require-dev" usually becomes "BuildRequires"
• "suggest" are optional dependencies, which can becomes (packager choice) "Requires"
• "conflict" becomes "Conflicts"
• "replace" becomes "Provides" (and "Obsoletes" if needed)

Autoloader

Explanation

Composer: most library and lot of applications are now "composer" aware. Which means composer is used to install dependencies and create a suitable autoloader. Composer is mostly a "Bundled every library in every project", not something we want in Fedora.

Consumer Autoloader: in some case, we can add an autoloader for an application and all its dependencies. It seems this is not the best solution, if the dependency tree change, the autoloader need to be fixed.

Provider Autoloader: if each library provides an autoloader for its classes and its dependencies, a consumer just have to include this autoloader. This seems the best solution, so recommended here.

Providing an autoloader is not mandatory (so not in the Guidelines), but seems a good practice.

Implementation

There are various way to create an autoloader

upstream: when upstream provides an autoloader, no need to use another one ;)

classmap: when "composer.json" describe a library to autoload a classmap, e.g.

"autoload": {
      "classmap": ["src/"]
}

the simple solution is to generate an simple classmap autoloader, using the phpab command, e.g.

BuildRequires: %{_bindir}/phpab

%build
%{_bindir}/phpab --output src/autoload.php src

Symfony Framework: recommended when your package already pull some symfony components and is PSR-0/PSR-4 compliant, e.g.

"require": {
   "php": ">=5.3.2",
   "symfony/console": "~2.5",
   "foo/baz": "~1.0"
},
"autoload": {
    "psr-0": { "Foo\\Bar\\": "src/" }
},

In your spec (autoload.php can also be a separate source file):

BuildRequires: php-composer(symfony/class-loader)
Requires:      php-composer(symfony/class-loader)

cat <<'AUTOLOAD' | tee src/autoload.php
<?php

if (!isset($fedoraClassLoader) || !($fedoraClassLoader instanceof \Symfony\Component\ClassLoader\ClassLoader)) {
    if (!class_exists('Symfony\\Component\\ClassLoader\\ClassLoader', false)) {
        require_once '%{_datadir}/php/Symfony/Component/ClassLoader/ClassLoader.php';
    }

    $fedoraClassLoader = new \Symfony\Component\ClassLoader\ClassLoader();
    $fedoraClassLoader->register();
}

// This library
$fedoraClassLoader->addPrefix('Foo\\Bar\\', dirname(dirname(__DIR__)));

// Another library (dependency)
require_once '%{_datadir}/php/Foo/Baz/autoload.php';
AUTOLOAD

Notice: in this implementation proposal, $fedoraClassLoader can be shared between libraries when various autoloader are stacked.

Zend Framework: recommended when your package already pull some ZF components.

In your spec (autoload.php can also be a separate source file):

BuildRequires: php-composer(zendframework/zend-loader) 
Requires:      php-composer(zendframework/zend-loader) 

cat <<'AUTOLOAD' | tee src/autoload.php
<?php
require_once '%{_datadir}/php/Zend/Loader/AutoloaderFactory.php';
Zend\Loader\AutoloaderFactory::factory(array(
    'Zend\Loader\StandardAutoloader' => array(
        'fallback_autoloader' => true, // for other dep, if needed
        'autoregister_zf' => true,     // for ZF, if needed
        'namespaces' => array(
           'Foo\\Bar' => __DIR__       // Your namespace
))));
AUTOLOAD

Using AutoloaderFactory ensure a single instance of StandardAutoloader is used.

More autoloader tips

Test your autoloader: usually by using it to run the test suite, and better to run the installed copy, e.g.

%check
phpunit --bootstrap=%{buildroot}/%{_datadir}/php/Foo/Bar/autoload.php

Use full path to dependencies autoloader, to ensure you use the expected one (don't rely on include_path to avoid /usr/share/pear which can provide an old version, or SCL which doesn't includes /usr/share/php, or any user altered env.)

Use relative path for the library itself, so the autoloader can be included from /usr/share/php or %{buildroot}

Package versions that introduced autoloaders

Notes

• Packages that provided an autoloader since their first release will not be listed here
• This is not an exhaustive list of packages

Package	Autoloader Type	Autoloader Since Version
php-Assetic
php-aws-sdk	Symfony ClassLoader	2.8.13
php-cloudfiles
php-deepend-Mockery
php-digitalsandwich-Phake
php-doctrine-annotations	Symfony ClassLoader	1.2.6
php-doctrine-cache	Symfony ClassLoader	1.4.1
php-doctrine-collections	Symfony ClassLoader	1.3.0
php-doctrine-common	Symfony ClassLoader	2.5.0
php-doctrine-datafixtures	Symfony ClassLoader	1.0.2
php-doctrine-dbal
php-doctrine-Doctrine
php-doctrine-inflector	Symfony ClassLoader	1.0.1-4
php-doctrine-lexer	Symfony ClassLoader	1.0.1-4
php-doctrine-orm
php-dropbox-php-Dropbox
php-drush-drush
php-EasyRdf	Symfony ClassLoader	0.9.0
php-egulias-email-validator	Symfony ClassLoader	1.2.9
php-Faker
php-gitter	Symfony ClassLoader	0.3.0-5
php-gliph	Symfony ClassLoader	0.1.8-4
php-google-apiclient	Upstream custom	1.1.4
php-goutte
php-guzzle-Guzzle	Symfony ClassLoader	3.9.3
php-guzzlehttp-guzzle	Symfony ClassLoader	5.3.0
php-guzzlehttp-ringphp	Symfony ClassLoader	1.1.0-3
php-guzzlehttp-streams	Symfony ClassLoader	3.0.0-3
php-JMSParser	Symfony ClassLoader	1.0.0-7
php-jsonlint
php-JsonSchema
php-lessphp
php-Metadata	Symfony ClassLoader	1.5.1-3
php-Monolog	Symfony ClassLoader	1.15.0
php-ocramius-code-generator-utils
php-ocramius-generated-hydrator
php-opencloud
php-pclzip
php-pear-PhpDocumentor
php-phpass
php-PhpCollection	Symfony ClassLoader	0.4.0-4
php-PhpOption	Symfony ClassLoader	1.4.0-4
php-PHPParser
php-pirum-Pirum
php-psr-http-message	phpab	1.0.0
php-PsrLog
php-Raven	Raven_Autoloader	0.12.0
php-react-promise	Symfony ClassLoader	2.2.0-4
php-sabredav-Sabre
php-sabredav-Sabre_CalDAV
php-sabredav-Sabre_CardDAV
php-sabredav-Sabre_DAV
php-sabredav-Sabre_DAVACL
php-sabredav-Sabre_HTTP
php-sabredav-Sabre_VObject
php-scssphp	Symfony ClassLoader	0.1.6
php-swift-Swift
php-symfony	Symfony ClassLoader	2.3.31 / 2.7.1
php-SymfonyCmfRouting
php-twig	Twig_Autoloader	1.18.2
php-twig-extensions
php-when
php-xmlseclibs
php-ZendFramework2