README

Build tools and CLI utilities for PHPX WebAssembly projects.

Overview

This package provides the build system for PHPX applications, handling compilation, bundling, and deployment of PHP applications to WebAssembly.

Features

Build System: Compile and pack PHPX applications for WebAssembly
Watch Mode: Auto-rebuild on file changes during development
Vendor Optimization: Smart caching of production dependencies
Fast Builds: Cached vendor directory for quick rebuilds
Clean Architecture: Build artifacts in temporary directories

Installation

composer require syntaxx/phpx-build-tools --dev

Usage

Build Your Application

# Full build (pack + export)
vendor/bin/phpx-build build

# Pack only
vendor/bin/phpx-build pack

# Export only
vendor/bin/phpx-build export

Watch Mode (Auto-rebuild)

vendor/bin/phpx-build watch

Composer Scripts Integration

Add to your composer.json:

{
    "scripts": {
        "wasm": "phpx-build build",
        "wasm:watch": [
            "Composer\\Config::disableProcessTimeout",
            "phpx-build watch"
        ]
    }
}

How It Works

Build Process

Temporary Build Directory: Creates /tmp/phpx-build/{project}-{hash}
File Copy: Copies bootstrap.php, src/, and vendor files
Vendor Optimization: Uses cached production vendor (no dev dependencies)
PHPX Compilation: Transforms PHPX files to standard PHP
WebAssembly Packing: Bundles everything into .wasm data file
Export: Copies build artifacts to public/build/
Cleanup: Removes temporary directory

Vendor Caching

The build system caches the vendor directory based on composer.json and composer.lock hashes:

Cache Hit: Reuses existing vendor (~0.4s build time)
Cache Miss: Runs composer install --no-dev and caches result

Cache location: /tmp/phpx-build/{project}-vendor-{hash}

Watch Mode

Monitors for changes in:

src/ directory (PHP/PHPX files)
composer.json (dependencies)
composer.lock (dependency lock)

Features:

Initial build on startup
2-second debouncing to prevent excessive rebuilds
Colored output with clear status messages
Excludes temporary files and editor backups

Configuration

Create a phpx-build.json in your project root:

{
    "build": {
        "src": "src",
        "output": "public/build",
        "bootstrap": "bootstrap.php"
    },
    "watch": {
        "paths": ["src", "composer.json", "composer.lock"],
        "exclude": ["*.swp", "*.tmp", "~"]
    }
}

Requirements

PHP 8.3 or higher
inotify-tools (for watch mode on Linux)

Installing inotify-tools

# Ubuntu/Debian
sudo apt-get install inotify-tools

# Fedora/RHEL
sudo yum install inotify-tools

# Arch Linux
sudo pacman -S inotify-tools

Integration with PHPX Ecosystem

This package is designed to work seamlessly with:

PHPX-Compiler: Transforms PHPX syntax to PHP
WebAssemblyPacker: Bundles files for WebAssembly
PHPX-Framework: React-like component framework
PHPX-WasmRuntime: Runtime for executing PHP in browser

Development

# Clone the repository
git clone https://github.com/syntaxx/phpx-build-tools
cd PHPX-BuildTools

# Install dependencies
composer install

# Run tests
composer test

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please submit pull requests or open issues on GitHub.

Credits

Part of the PHPX ecosystem - bringing React-like development to PHP with WebAssembly.

syntaxx / phpx-build-tools

Maintainers

Details