Installation

Requirements

• PHP 8.4 or newer and Composer 2 on the machine that runs the compiler
• A Composer project with its source beneath the project root
• An output directory that does not overlap any source directory

The compiler is a development dependency. Your application runs the generated PHP tree on whatever PHP version that tree targets (see targetPhpVersion in Project configuration); the compiler itself is not needed in production.

Memory needs depend on your source and Composer dependency graph. Choose a CLI memory limit that fits your project rather than treating one number as a universal minimum. See the release notes for memory improvements still in development; those results do not describe every published compiler release.

Install the compiler

composer require --dev atatusoft/ppphp
vendor/bin/ppphp --version

Composer selects Stable releases by default. The version command prints the exact release you have, which is worth including in any bug report.

Package availability: The unversioned command requires a Stable release of atatusoft/ppphp. Check the official release history for available versions and their package provenance. Composer does not select a release candidate with this command.

Installing a release candidate

For the latest published candidate, see 2026.3.1-rc-2 and its upgrade guidance. To reproduce an installation of the earlier 2026.3.1-rc-1 documented on this site, use its original package name:

composer require --dev atatusoft-ltd/ppphp-src:2026.3.1-rc-1

Keep the constraint exact; a looser one can resolve to a different build than the one you tested. The website release notes distinguish these historical instructions from upcoming improvements; the official release history lists all published versions.

Moving to the new package name

Existing installations keep working under atatusoft-ltd/ppphp-src. Wait until the release you want is published under atatusoft/ppphp before switching. Remove the old root requirement without updating dependencies, then add the new package:

composer remove --dev --no-update atatusoft-ltd/ppphp-src
composer require --dev atatusoft/ppphp

If the old package is in require rather than require-dev, omit --dev from the removal command. The new compiler remains a development dependency. For a release candidate, use the exact command from that release's notes instead of the unversioned second command. Do not leave both names in your root requirements.

Review and commit composer.json and composer.lock together after Composer succeeds. The CLI remains ppphp, PHP namespaces remain Atatusoft\Ppphp, and the source repository, release assets, and existing schema URLs keep their current locations. Published releases retain the package name they shipped with.

Initialize the project

Run the initializer from the project root:

vendor/bin/ppphp init

It creates ppphp.json, build/ppphp, .ppphp-cache, and stubs. A packaged release writes the URL of its own configuration schema as the first property, so your editor can validate and complete the file:

{
    "$schema": "https://github.com/atatusoft-ltd/ppphp-src/releases/download/2026.3.1-rc-1/ppphp.schema.json",
    "source": ["src"],
    "output": "build/ppphp",
    "cache": ".ppphp-cache",
    "targetPhpVersion": "8.4",
    "stubs": ["stubs"],
    "exclude": ["vendor", "build", ".ppphp-cache"]
}

The schema URL is tied to the exact release that wrote it and never changes afterwards. Builds made from a source checkout have no release metadata and omit the property. Ordinary ppphp commands never fetch the schema or check the network, so checking and building stay local.

All configured paths are relative to the project root. Output and cache paths may not overlap source, and the compiler rejects unsafe paths instead of risking source data.

See Project configuration for every field, multi-root layouts, stubs, exclusions, custom paths, and the complete Composer metadata contract.

Set up Composer to load the build

Your root composer.json should describe the source namespace you own. For example:

{
    "autoload": {
        "psr-4": {
            "App\\": "src/"
        }
    }
}

Run composer:configure to change the autoload path from your source directory to the generated PHP directory. It saves the original source mapping under extra.ppphp for future checks and builds. Preview the change before applying it:

vendor/bin/ppphp composer:configure --dry-run
vendor/bin/ppphp composer:configure
composer update --lock --no-interaction --no-scripts

Review the Composer diff before committing it. Do not map the same namespace to both .ppphp source and emitted PHP as competing runtime definitions.

Build one working program

Create src/Greeting.ppphp:

<?php

namespace App;

final class Greeting
{
    public function __construct(
        public readonly string $name,
    ) {}

    public string $message {
        get => 'Hello, ' . $this->name;
    }
}

Create src/index.php as the ordinary PHP entrypoint:

<?php

require_once dirname(__DIR__, 2) . '/vendor/autoload.php';

echo new App\Greeting('World')->message, "\n";

Check the project without replacing generated output, then build the complete tree:

vendor/bin/ppphp check
vendor/bin/ppphp build
composer dump-autoload --optimize
php -l build/ppphp/Greeting.php
php build/ppphp/index.php

The generated App\Greeting class is loaded through the projected PSR-4 mapping. The entrypoint is copied to build/ppphp/index.php, so it walks up two directories to load the project-root Composer installation. The final command prints Hello, World. .ppphp files are never executed directly; the generated tree is what runs. A complete build compiles selected .ppphp files, copies selected .php files byte-for-byte, validates the result, and atomically replaces build/ppphp only after the build succeeds.

Put the same workflow in CI

CI should install from composer.lock, print the compiler version for the log, check the complete project, build, refresh autoload metadata, and run the application test suite:

composer install --no-interaction --prefer-dist
vendor/bin/ppphp --version
vendor/bin/ppphp check --format=json
vendor/bin/ppphp build
composer dump-autoload --classmap-authoritative
vendor/bin/phpunit

Deploy the generated application tree together with the root Composer metadata and installed production dependencies. The compiler remains a development dependency and does not add a service or extension to production.

If you download release assets such as the schema or manifest directly, verify them against the published checksums first. See Verify downloads.

Continue with Project configuration for the full metadata reference, The CLI for selection and diagnostics, or Migrating from PHP for a file-by-file adoption plan.