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 PECL

• Subscribe to the pecl-dev mailing list.
• Fill in the form at https://pecl.php.net/account-request.php
  • Do not check "need a php.net account".
• Find the resulting email in pecl-dev.
• Post a polite followup confirming that you really want the account
• Wait a few days
• If your account is still not approved, pester cmb.

Adding new maintainers

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 package

• Fill in the form at https://pecl.php.net/package-new.php . This should make a package immediately, with no releases.
• Get the sample package.xml with

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 release an update

Update the source so that it reports the new version. There is conventionally a version macro which is registered in the zend_module_entry.

Update package.xml for a new release:

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

Validate the package.xml with:

pear package-validate

Submit the commit for review, and once it passes CI and is merged, upload the package. Run the following:

pear package

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

Finally, tag the release commit in Git as git tag -s X.Y.Z and push it to Gerrit with git push --tags.

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