Pskel

日本語

A simple, fast, and convenient PHP Extension skeleton project

Overview

Pskel is a skeleton project designed to streamline the development of PHP extensions.

It provides a comprehensive toolkit that covers everything from setting up the development environment to continuous integration.

Key Features

🚀 Rapid Environment Setup

• Utilizes Development Containers and Visual Studio Code
• Automatic installation of necessary extensions
• Simplified configuration for C/C++ development environment

🛠 Advanced Debugging and Analysis Tools

• Support for Valgrind and LLVM Sanitizer
• Integration of external services via docker compose

🧪 Comprehensive Testing Environment

• Testing across various PHP builds (NTS, ZTS, DEBUG, etc.)
• Easy task execution with the pskel command

🔄 Continuous Integration with GitHub Actions

• Standard tests (NTS, ZTS)
• Memory leak checks
• LLVM Sanitizer inspections
• Code coverage analysis
• Support for testing on various OS platforms:
  • Linux
  • macOS
  • Windows

📦 Distribution with PIE

• pskel init generates a composer.json containing the php-ext metadata required by PIE
• Pushing a tag automatically creates a GitHub Release with a pre-packaged source archive and Windows binaries

☁️ Cloud Development Environment

• Support for GitHub Codespaces
• Development possible with just a browser

Setup Instructions

Preparing for Local Development

1. Install Visual Studio Code
2. Install Docker / Docker Compose compatible runtime
3. Create a repository using colopl/pskel as a template
4. Clone locally, open in VSCode, and reopen it in the Dev Container

Preparing for Development in GitHub Codespaces

1. Create a repository using colopl/pskel as a template
2. Create a new Codespace from the WebUI under <> Code -> Codespaces

Creating the Skeleton

After launching the development environment, run the following command in the terminal:

$ pskel init <YOUR_EXTENSION_NAME> "<COPYRIGHT_HOLDER / VENDOR_NAME>"

This will create an extension template in the ext directory and write project metadata files such as LICENSE and composer.json to the project root.

Additional options available in ext_skel.php are also supported.

Testing

Testing the Extension

We provide a convenient testing environment using the pskel command:

$ pskel test              # Test with standard PHP
$ pskel test debug        # Test with debug build PHP
$ pskel test gcov         # Generate code coverage using GCC Gcov
$ pskel test valgrind     # Memory check using Valgrind
$ pskel test msan         # Check using LLVM MemorySanitizer
$ pskel test asan         # Check using LLVM AddressSanitizer
$ pskel test ubsan        # Check using LLVM UndefinedBehaviorSanitizer
$ pskel clean-build-cache # Remove built PHP runtimes and cache

Testing Integration with External Services

You can integrate external services into your development environment by editing the compose.yaml file. A sample MySQL configuration is included in compose.yaml (commented out).

Code Coverage

Checking Coverage in Development Environment

You can check the code coverage using lcov with the pskel command:

$ pskel coverage
~~~
Reading tracefile ext/lcov.info
            |Lines       |Functions  |Branches
Filename    |Rate     Num|Rate    Num|Rate     Num
==================================================
[ext/]
bongo.c     |75.0%     20|80.0%     5|    -      0
==================================================
      Total:|75.0%     20|80.0%     5|    -      0

Checking Coverage in GitHub Pages

By enabling GitHub Pages for your repository and enabling Actions deployment, you can view code coverage generated by lcov and genhtml commands on GitHub Pages.

Releasing with PIE

PIE is the standard installer for distributing PHP extensions.

pskel init generates a composer.json with the php-ext metadata that PIE requires. When you push a tag (e.g. 1.0.0), the Release workflow automatically:

1. Creates a GitHub Release for the tag
2. Attaches a pre-packaged source archive (php_<extension_name>-<version>-src.tgz)
3. Builds Windows binaries (PHP 8.1 - 8.5, x64/x86, TS/NTS) with php/php-windows-builder and attaches them to the release

To make your extension installable with pie install <vendor>/<extension_name>, submit the repository to Packagist.

Frequently Asked Questions

Q: Can I use debuggers like gdb or lldb?

A: Yes. All development tools are pre-installed. For example, to use gdb:

$ gdb --args <php_binary> -dextension=./modules/your_extension_name.so example.php

Q: How is Valgrind installed?

A: Valgrind is downloaded from sourceware.org and built from source when the container image is built. The version is pinned by the VALGRIND_VERSION build argument in the Dockerfile. If you place a pre-fetched valgrind-<version>.tar.bz2 in the repository root (excluded from Git via .gitignore), it is used instead of downloading. Passing the SKIP_VALGRIND=1 build argument skips building Valgrind entirely. Valgrind is only supported on Debian-based images: building a non-Debian (e.g. Alpine) image fails unless SKIP_VALGRIND=1 is passed explicitly.

Q: Can I use editors other than Visual Studio Code?

A: While not recommended, you can use any editor that supports Development Containers.

Q: What if I have other questions?

A: Feel free to ask on GitHub or X (formerly Twitter).

License

BSD-3-Clause