README

Validate PHP code examples in documentation.

This file describes version 2 which uses php8 attributes.

For version 1 which uses docblock style annotations see this link.

Why?

Did you update your library, but forgot to update code examples in README? Are your users complaining on syntax errors in your examples? Do you find it too cumbersome to manually test all examples? Readme-Tester lets you automate the process of validating PHP code examples in documentation files.

A simple example

Readme-Tester uses php8 style attributes inside HTML-comments (to make them invisible after rendering on for example github) to specify the expected result of a code example.

The following simple example asserts that the code outputs content.

<!--
#[ReadmeTester\ExpectOutput('/foo/')]
-->
```php
echo "foobar";
```

For more information read the documentation.

Installation

Using phive (recommended)

Install using phive

phive install hanneskod/readme-tester

As a phar archive

Download the latest phar archive from the releases tab.

Optionally rename readme-tester.phar to readme-tester for a smoother experience.

Using composer

Install as a composer dependency

composer require --dev hanneskod/readme-tester

This will make readme-tester avaliable as vendor/bin/readme-tester.

From source

To build you need make

make
sudo make install

The build script uses composer to handle dependencies and phive to handle build tools. If they are not installed as composer or phive respectivly you can use something like

make COMPOSER_CMD=./composer.phar PHIVE_CMD=./phive.phar

Getting started

Using the command line tool is as simple as

readme-tester README.md

For more detailed information use

readme-tester -h

hanneskod / readme-tester

Maintainers

Details