Download the PHP package luttje/php-example-tester without Composer

PHP Example Tester

Use comments in markdown to automatically compile tested examples into your README.

[!Warning] This package is still in development. It is not yet ready for production use and the API may change at any time.

Installation

You can install the package via composer:

Usage

1. Prepare your README

Add the start and end comments to your README where you want each individual example to appear:

`

For a full example have a look at 👀 the example README with placeholders.

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

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.

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.

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

Document the example method here, as you normally would.

Here's the example code:

🤓 Yay calculations!

For a full example have a look at 🏗 the compiled example README.

[!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.

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 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 the short property to false will also copy the entire method signature into the README.md file for this result:

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:

Ignoring examples

Especially for the readme in the root of this package, we want to selectively ignore examples. This can be done by wrapping <!-- #EXAMPLE_COPY_IGNORE_START --> and <!-- #EXAMPLE_COPY_IGNORE_END --> comments around the sections of the readme where you want to not copy examples.

Command-line interface

The command has the following signature:

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

The path to the README file to write the compiled examples to. Defaults to README.md in the root of your project.

--input

The path to the README file to read the examples from. Defaults to the --output path.

Testing

Run the tests with:

License

The MIT License (MIT). Please see License File for more information.