PHPackages luttje/php-example-tester - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Testing & Quality](/categories/testing) 4. / 5. luttje/php-example-tester ActiveLibrary[Testing & Quality](/categories/testing) luttje/php-example-tester ========================= Use comments in markdown to automatically compile tested examples into your README 0.5.0(2mo ago)0835↓86.7%2MITPHP ^8.3 Since Dec 26Compare [ Source](https://github.com/luttje/php-example-tester)[ Packagist](https://packagist.org/packages/luttje/php-example-tester)[ Docs](https://github.com/luttje/php-example-tester)[ GitHub Sponsors](https://github.com/luttje)[ RSS](/packages/luttje-php-example-tester/feed)WikiDiscussions Synced 2d ago READMEChangelog (8)Dependencies (15)Versions (11)Used By (2) PHP Example Tester ================== [](#php-example-tester) Use comments in markdown to automatically compile tested examples into your README. [![run-tests](https://github.com/luttje/php-example-tester/actions/workflows/run-tests.yml/badge.svg)](https://github.com/luttje/php-example-tester/actions/workflows/run-tests.yml)[![Coverage Status](https://camo.githubusercontent.com/ae23d751eabd026fcad5188eb3407bf3727902de0b544fdf85da51b36b35118b/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f6c7574746a652f7068702d6578616d706c652d7465737465722f62616467652e7376673f6272616e63683d6d61696e)](https://coveralls.io/github/luttje/php-example-tester?branch=main) Warning This package is still in development. It is not yet ready for production use and the API may change at any time. Installation ------------ [](#installation) You can install the package via composer: ``` composer require luttje/php-example-tester ``` Usage ----- [](#usage) ### 1. Prepare your README [](#1-prepare-your-readme) Add the start and end comments to your README where you want each individual example to appear: > ``` > ### `exampleMethod` > > Document the example method here, as you normally would. > > **Here's the example code:** > > > > This will be replaced with the example code. > > > > *🤓 Yay calculations!* > ``` *For a full example have a look at [👀 the example README with placeholders](tests/Fixtures/ExampleClassTest.README.md?plain=1).* You must provide a fully qualified path to the method you want to copy. You can also provide a fully qualified path to a class to copy the entire class. ### 2. Write tests for that example code [](#2-write-tests-for-that-example-code) Write your tests in a separate static method in your test class. This package can then extract the body of the method and use it as the example code. ``` use Luttje\ExampleTester\Tests\TestCase; final class ExampleClassTest extends TestCase { public static function exampleMethod(): void { // This is an example method. $a = 1; $b = 25; $c = $a + $b; echo $c; // This is the end of the example method. } /** * @test */ public function testExampleMethod(): void { ob_start(); self::exampleMethod(); $output = ob_get_clean(); $this->assertSame('26', $output); } } ``` ### 3. Compile the examples into your README [](#3-compile-the-examples-into-your-readme) Run the `example-tester` command to compile the examples into your README using the `vendor/bin/example-tester compile` command. ``` vendor/bin/example-tester compile ``` After running the command, the examples will be compiled into your README. This is a section in your README may look like after running the command: > ### `exampleMethod` > > [](#examplemethod) > > Document the example method here, as you normally would. > > **Here's the example code:** > > ``` > // This is an example method. > $a = 1; > $b = 25; > > $c = $a + $b; > > echo $c; > // This is the end of the example method. > ``` > > > > *🤓 Yay calculations!* *For a full example have a look at [🏗 the compiled example README](tests/Fixtures/ExampleClassTest.README.expected.md?plain=1).* Note You can make your workflow even smoother by adding the `example-tester compile`command to your `composer.json` scripts. That way you can run it with `composer compile-readme`. ``` { "scripts": { "compile-readme": [ "vendor/bin/example-tester compile" ] } } ``` Advanced usage -------------- [](#advanced-usage) You've seen the simple syntax to mark the start of an example, but you can also provide some extra options to the `#EXAMPLE_COPY_START` comment in the form of a JSON object: ``` ``` Is equivalent to this simpler syntax: ``` ``` However providing a JSON object unlocks the ability to configure additional properties, like the `short` property. ### The `short` property [](#the-short-property) The `short` property defaults to `true` and ensures only the body of the method or class is copied into the README.md file. #### Setting `short` to `false` for a method [](#setting-short-to-false-for-a-method) > Setting the `short` property to `false` will also copy the entire method signature into the README.md file for this result: > > ``` > public static function exampleMethod(): void > { > // This is an example method. > $a = 1; > $b = 25; > > $c = $a + $b; > > echo $c; > // This is the end of the example method. > } > ``` #### Setting `short` to `false` for a class [](#setting-short-to-false-for-a-class) > For classes it may make more sense to set `short` to `false` to copy the entire class into the README.md file for this result: > > ``` > use Luttje\ExampleTester\Tests\TestCase; > > final class ExampleClassTest extends TestCase > { > public static function exampleMethod(): void > { > // This is an example method. > $a = 1; > $b = 25; > > $c = $a + $b; > > echo $c; > // This is the end of the example method. > } > > /** > * @test > */ > public function testExampleMethod(): void > { > ob_start(); > self::exampleMethod(); > $output = ob_get_clean(); > > $this->assertSame('26', $output); > } > } > ``` ### Ignoring examples [](#ignoring-examples) Especially for the readme in the root of this package, we want to selectively ignore examples. This can be done by wrapping `\` and ``comments around the sections of the readme where you want to not copy examples. ``` #### Ignored example This example will be ignored. Should not be removed. ``` ### Command-line interface [](#command-line-interface) The command has the following signature: ``` compile [--output OUTPUT] [--input INPUT] ``` **You must run the command from the root of your project.** That way the command can find the vendor directory containing the composer autoload file. ### `--output` [](#--output) The path to the README file to write the compiled examples to. Defaults to `README.md` in the root of your project. ``` vendor/bin/example-tester compile --output DOCS.md ``` ### `--input` [](#--input) The path to the README file to read the examples from. Defaults to the `--output` path. Testing ------- [](#testing) Run the tests with: ``` composer test ``` License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 45 — FairBetter than 91% of packages Maintenance85 Actively maintained with recent releases Popularity17 Limited adoption so far Community16 Small or concentrated contributor base Maturity54 Maturing project, gaining track record Bus Factor1 Top contributor holds 67.3% of commits — single point of failure How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** — Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~120 days Recently: every ~209 days Total 8 Last Release 77d ago PHP version history (4 changes)0.2.1PHP ^8.1 0.4.0PHP ^8.1|^8.2|^8.3|^8.4 0.4.1PHP ^8.2|^8.3|^8.4 0.5.0PHP ^8.3 ### Community Maintainers ![](https://www.gravatar.com/avatar/d50c11122445f7743eb6ec278ca6322a0f3d9c9296df290a66c0e5ab0df5e750?d=identicon)[luttje](/maintainers/luttje) --- Top Contributors [![luttje](https://avatars.githubusercontent.com/u/2738114?v=4)](https://github.com/luttje "luttje (37 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (12 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (6 commits)") --- Tags phptestexamplesreadmeluttje ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/luttje-php-example-tester/health.svg) ``` [![Health](https://phpackages.com/badges/luttje-php-example-tester/health.svg)](https://phpackages.com/packages/luttje-php-example-tester) ``` ### Alternatives [behat/behat Scenario-oriented BDD framework for PHP 4.0k101.8M2.2k](/packages/behat-behat)[infection/infection Infection is a Mutation Testing framework for PHP. The mutation adequacy score can be used to measure the effectiveness of a test set in terms of its ability to detect faults. 2.2k28.9M2.4k](/packages/infection-infection)[psalm/plugin-laravel Psalm plugin for Laravel 3355.3M346](/packages/psalm-plugin-laravel)[phparkitect/phparkitect Enforce architectural constraints in your PHP applications 9224.3M28](/packages/phparkitect-phparkitect)[laraveldaily/filacheck Static analysis for Filament projects - detect deprecated patterns and code issues 11975.6k](/packages/laraveldaily-filacheck)[jolicode/castor A lightweight and modern task runner. Automate everything. In PHP. 54743.1k4](/packages/jolicode-castor) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)