Skip to content

SKILL.md

Latest commit

 

History

History
171 lines (122 loc) · 5.07 KB

SKILL.md

File metadata and controls

171 lines (122 loc) · 5.07 KB
name description
php-pecl-package
Automated PHP PECL package creation workflow for building standard tgz packages from source code. Use when Claude needs to package PHP extensions for PECL distribution. Handles updating package.xml with version/date/changelog, validating file completeness, running pear package command, and verifying package integrity with configure/make. Requires pear command-line tool and a ChangeLog file.

PHP PECL Package Builder

Automated workflow for creating PHP PECL-standard tgz packages from source code.

Quick Start

To package a PHP extension:

python3 scripts/package_pecl.py --version 1.0.0 --changelog ChangeLog

This will:

  1. Parse the ChangeLog file for release notes
  2. Update version numbers in source code files (.c, .h, .php)
  3. Update package.xml with version, date, and changelog
  4. Validate that all files listed in package.xml exist
  5. Run pear package to create the tgz
  6. Extract and validate the package with ./configure && make

Requirements

  • pear command-line tool: Must be installed and available in PATH
  • package.xml: Must exist in the source directory
  • ChangeLog file: Contains release notes for the new version
  • PHP development tools: phpize (for validation)

Workflow

Step 1: Prepare Your Source Directory

Ensure your extension directory contains:

  • package.xml with complete file list
  • Source files (.c, .h, config.m4)
  • ChangeLog file with release notes

Step 2: Run the Package Script

# Basic usage (current directory)
python3 scripts/package_pecl.py --version 1.0.0 --changelog ChangeLog

# Specify source directory
python3 scripts/package_pecl.py --version 2.1.3 --changelog RELEASE_NOTES.md --source /path/to/extension

# Skip validation (faster, less thorough)
python3 scripts/package_pecl.py --version 1.5.0 --changelog ChangeLog --no-validate

Step 2.5: Source Code Version Update

The script automatically updates version numbers in source code files before updating package.xml. It searches for common version patterns in:

  • C/C++ files (.c, .h):

    • #define EXTNAME_VERSION "1.0.0"
    • const char *version = "1.0.0";
    • static const char version[] = "1.0.0";

  • PHP files (.php):

    • const VERSION = '1.0.0';
    • define('VERSION', '1.0.0');
    • $version = "1.0.0";
    • private const VERSION = '1.0.0';

If no version patterns are found, the script continues with a warning message.

Step 3: Review Output

The script will:

  • ✅ Show parsed changelog content
  • ✅ Update version numbers in source code files
  • ✅ Update package.xml with new version and date
  • ✅ Validate all files exist
  • ✅ Build .tgz package
  • ✅ Extract and test compilation (unless --no-validate)

Success message: 🎉 Success! Package created: extension-1.0.0.tgz

Source Code Updates

Before updating package.xml, the script automatically updates version numbers in source code files:

  1. Search: Scans all .c, .h, and .php files in the source directory
  2. Pattern Matching: Looks for common version definition patterns
  3. Update: Replaces old version numbers with the new version
  4. Report: Lists all files that were updated

The script supports multiple version definition patterns commonly used in PHP extensions.

package.xml Updates

The script automatically updates these fields:

  1. Version: <version><release> and <version><api>
  2. Date: <date> (current date in YYYY-MM-DD format)
  3. Time: <time> (current time)
  4. Release Notes: <notes> (parsed from ChangeLog)
  5. Changelog: Adds new <release> entry to <changelog> section

ChangeLog Parsing

The script looks for release notes in your ChangeLog file using these patterns:

Version 1.0.0 - 2024-01-15
- Feature X added
- Bug Y fixed

## 2.1.0
- New feature

It extracts the first version entry found and uses it for release notes.

Validation

File Completeness Check

Verifies all files listed in package.xml exist in the source directory.

Package Verification

Extracts the .tgz to a temporary directory and runs:

phpize
./configure
make

This ensures the package compiles correctly.

Common Issues

Missing pear command

Error: pear package failed

Install PEAR: sudo apt-get install php-pear (Debian/Ubuntu) or equivalent for your system.

Missing files in package.xml

Warning: 5 files listed in package.xml are missing

Update package.xml to include all source files, or remove non-existent entries.

phpize not found

phpize failed (may be expected in some environments)

Install PHP development package: sudo apt-get install php-dev (Debian/Ubuntu).

configure/make failures

./configure failed
make failed

Check your config.m4 and source files for errors. The package is still created but may have issues.

Reference

For detailed information about PECL package structure and standards, see references/pecl_standards.md.

Script Location

The main packaging script is located at:

  • scripts/package_pecl.py

This is a Python 3 script that performs all packaging steps automatically.