Download the PHP package jbboehr/akashi without Composer

Akashi

Akashi turns PHP examples in Markdown and PHPDoc into executable tests. PHP fences in a README, documentation site, or source docblock form one shared corpus that PHPUnit executes in-process by default, while individual examples can opt into a child process. Supported native assert() calls remain unconditional, failures point back to the maintained source, and the same examples can participate in PHPStan verification or named consumer-fixture extraction.

Put an ordinary PHP fence in README.md or another selected Markdown file:

This example is tested by Akashi in this repository.

Quick PHPUnit Usage

Create a PHPUnit test such as tests/DocumentationExamplesTest.php:

Run vendor/bin/phpunit. Akashi discovers each selected PHP fence, rewrites supported native assert() calls so they cannot be disabled by PHP configuration, and executes each example as a named PHPUnit data set. The trait supplies the provider and test method; the project supplies only its corpus. The default backend isolates local variables and declarations in-process. When an assertion fails, the report identifies the maintained documentation example rather than only generated code.

Installation

Akashi requires PHP 8.1 or later. Install it with a compatible PHPUnit release:

Akashi supports the PHPUnit 10.5 and 11.5 release lines. Composer selects PHPUnit 10.5 on PHP 8.1 and the newest compatible release on later PHP versions.

Features

• Markdown PHP examples as named PHPUnit tests
• inline PHPDoc examples and references to canonical PHP files or named regions
• fast in-process execution by default
• opt-in child-process execution for examples that need process isolation
• unconditional documentation assertions
• expected throwable and exact stdout contracts
• source-aware parse, execution, assertion, and PHPStan failures
• one reusable example corpus for runtime and static-analysis verification
• stable example identities and legacy-marker compatibility for consumer-fixture extraction
• check or atomically update rendered copies from canonical PHP sources, with in-memory corrections and source-labelled unified diffs
• optional PHP-CS-Fixer checks for PHP embedded in Markdown and PHPDoc

Akashi executes trusted project code; neither runtime backend is a security sandbox. See Compatibility and Safety for the exact boundary.

Documentation and Status

Start with the Quick Start, or read the complete documentation.

The Markdown, inline PHPDoc, canonical external-example, synchronization, and optional inline-formatting workflows, both runtime backends, PHPUnit integration, PHPStan verification, and marked extraction are implemented. Both recorded consumer migrations are complete. Akashi is still pre-1.0; its categorized public API is usable but may change between minor releases before 1.0.

License

Akashi is licensed under AGPL-3.0-only WITH romic-exception. See LICENSE.md and the Romic Exception. Contributions follow CONTRIBUTING.md.