Skip to content

pecl_standards.md

Latest commit

 

History

History
153 lines (115 loc) · 3.26 KB

pecl_standards.md

File metadata and controls

153 lines (115 loc) · 3.26 KB

PECL Package Standards

package.xml Structure

Required Elements

<?xml version="1.0" encoding="UTF-8"?>
<package version="2.0" xmlns="http://pear.php.net/dtd/package-2.0"
         xmlns:tasks="http://pear.php.net/dtd/tasks-1.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://pear.php.net/dtd/package-2.0
         http://pear.php.net/dtd/package-2.0.xsd">

  <name>extension_name</name>
  <summary>Brief description</summary>
  <description>Detailed description</description>

  <lead>
    <name>Author Name</name>
    <user>username</user>
    <email>email@example.com</email>
    <active>yes</active>
  </lead>

  <date>YYYY-MM-DD</date>
  <time>HH:MM:SS</time>

  <version>
    <release>1.0.0</release>
    <api>1.0.0</api>
  </version>

  <stability>
    <release>stable</release>
    <api>stable</api>
  </stability>

  <license uri="http://www.php.net/license">PHP License</license>

  <notes>
    Release notes for this version
  </notes>

  <contents>
    <dir name="/">
      <file name="config.m4" role="src" />
      <file name="php_extension.h" role="src" />
      <file name="extension.c" role="src" />
      <!-- More files -->
    </dir>
  </contents>

  <dependencies>
    <required>
      <php>
        <min>7.0.0</min>
      </php>
      <pearinstaller>
        <min>1.4.0</min>
      </pearinstaller>
    </required>
  </dependencies>

  <providesextension>extension_name</providesextension>

  <changelog>
    <!-- Release history -->
  </changelog>
</package>

File Roles

  • src: Source code files (.c, .h, .php)
  • doc: Documentation files (README, INSTALL, etc.)
  • test: Test files
  • script: Executable scripts
  • data: Data files

Stability Levels

  • stable: Production-ready, no breaking changes
  • beta: Feature-complete, may have bugs
  • alpha: Early development, incomplete features
  • devel: Development snapshot

Version Numbering

Use semantic versioning: MAJOR.MINOR.PATCH

  • MAJOR: Incompatible API changes
  • MINOR: Backwards-compatible functionality additions
  • PATCH: Backwards-compatible bug fixes

Required Files for PHP Extensions

Build System

  • config.m4 - Autoconf configuration for Unix/Linux
  • config.w32 - Windows build configuration (optional)
  • php_extname.h - Extension header file
  • extname.c - Main source file

Documentation

  • README - Basic documentation
  • CREDITS - Credits file
  • LICENSE or COPYING - License file
  • EXPERIMENTAL - If extension is experimental

Tests

  • tests/*.phpt - PHP test files

Common Issues

Missing Files

Ensure all source files are listed in package.xml under <contents>.

Version Mismatch

version/release and version/api should match for new releases.

Date Format

Use YYYY-MM-DD format for date element.

Dependencies

Specify minimum PHP version and other required packages.

Building and Validation

# Build package
pear package

# Validate package
pear package-validate package.xml

# Install package (for testing)
pear install package.tgz

# Run tests
pear run-tests -p /path/to/php tests/

ChangeLog Format

Version 1.0.0 - 2024-01-15
- Initial release
- Feature X implementation
- Bug fix for Y

Version 0.9.0 - 2024-01-01
- Beta release