How to PECL

PECL is a repository for PHP extensions.

PECL shares its packaging and installation tools with PEAR.

PEAR, for those younger readers, is a hosting site for PHP libraries, similar to Packagist except that they had a strict coding standards policy and made you request access to a Subversion repository shared with all sorts of important things in it (like the PHP core source) if you wanted to contribute. The coding standards were such that it was more like a framework than a dependency manager.

PEAR is now essentially defunct, so the only time you really need to know about it is when you submit things to PECL.

How to create an account on PECLEdit

Adding new maintainersEdit

Once your PECL account has been created, any of the current maintainers or "lead" in PECL terminology can add you as a "lead" as well. Even though you might not actually be the project's lead developer, you need to have the "lead" permission to upload new releases.

You also need to add yourself as a <lead> in package.xml. PECL will automatically update the list of maintainers upon every new upload, so if you aren't in package.xml, you will be removed.

How to create a packageEdit

svn cat http://svn.php.net/repository/pear/peardoc/trunk/en/guide/users/package.xml

package.xml is heavily validated. The tags need to be in the exact right order.

Modify the package.xml as follows:

  • name: enter name
  • delete uri, insert <channel>pecl.php.net</channel>
  • summary: as in the web form
  • description: as in the web form
  • lead
    • name: Human-readable name
    • user: The PECL username
    • email: The developer email address
  • date: Today's date
  • time: delete
  • version
    • release: The version
    • api: ignored, can be whatever
  • stability: release and api are normally "stable". The documentation indicates that if it works and you have tests and documentation, then it's stable.
  • license: you can put the license filename, e.g. "LICENSE", in the "filesource" attribute.
  • notes: The multi-line release notes for this specific version.
  • contents: This defines the files the installer will install.
    • You can try Tim's generator script.
    • The main tricky thing is to figure out what role to use for a file. The roles are listed at https://pear.php.net/manual/en/guide.developers.package2.file.php#guide.developers.package2.file.roles
    • C/C++ source files, build scripts, etc. can have role "src", which means packaged for build but not installed
    • Tests can have the role "test"
    • Most other installable files would have the role "doc". Example PHP files have role "doc". Only runtime executable PHP files need to be marked "php", which triggers their installation in the include_path. That's probably not going to be relevant for a PECL package.
  • dependencies: <os><name>linux</name></os> can be used to make the installer fail for non-Linux
  • Here add <providesextension>$NAME</providesextension> where $NAME is the extension name. This tag must be in this exact location before extsrcrelease.
  • Delete <phprelease/>. Add <extsrcrelease/>.
  • changelog: delete contents

Validate the package.xml with:

pear package-validate

How to update package.xml for a new releaseEdit

  • Move date, version and notes to a new <release> tag under <changelog>.
  • Update date, version and notes.
  • Update the <contents> section, ensuring all files are listed. See the notes above about what it should contain.
  • If you haven't uploaded this package before, make sure you are listed as a <lead>.

How to upload a new or updated package releaseEdit

After updating the package.xml, use

pear package

This will create a *.tgz file. You then go to https://pecl.php.net/release-upload.php to upload it.

A release announcement will be automatically sent to the pecl-dev mailing list.