pskel

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 19 Open GitHub ↗

Pskel - PHP Extension Skeleton

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Pskel

[日本語](README_ja.md)

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](https://containers.dev/) and [Visual Studio Code](https://code.visualstudio.com/)
- 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](https://github.com/php/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](https://docs.github.com/en/codespaces)
- Development possible with just a browser

## Setup Instructions

### Preparing for Local Development

1. Install [Visual Studio Code](https://code.visualstudio.com/)
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:

```bash
$ 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:

```bash
$ 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:

### 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](https://github.com/php/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](https://github.com/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](https://packagist.org/).

## 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:

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

### Q: How is Valgrind installed?
A: Valgrind is downloaded from [sourceware.org](https://sourceware.org/pub/valgrind/) 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](https://containers.dev).

### Q: What if I have other questions?
A: Feel free to ask on GitHub or [X (formerly Twitter)](https://x.com/zeriyoshi).

## License

BSD-3-Clause

pskel

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README