PHP Documentation with Sami

With Sami it is very easy to create beautiful documentation of your PHP application or API. It is also great to make API documentation of your whole composer 'vendor' folder.

Step 1. Download Sami

Download the Sami 'phar' file here.

Put this file in the root of your application. That makes it easy to find. You could place it anywhere you like as long as you can find it back.

Step 2. Prepare the documentation

Create a folder in the root of your application named 'docs' or 'documentation'.

In this folder you create subfolders for every different section you want to create documentation for. We are going to build documentation for the composer 'vendor' folder.
So we are going to create a subfolder named 'vendor' into the 'docs' folder.

Step 3. Configuration file

Now we have to create a configuration file for Sami. In the root of the 'docs' folder we create a file named 'vendor.sami.php' with the following content:

<?php

/**
 * relative path to the source you want to 'catch'
 * the sample below means that the 'document-this-folder' folder relates as starting 2 levels up from the 'docs' folder.
 * 
 * |- root
 * |--- document-this-folder
 * |------ docs
 *
 */

$dir = dirname( __DIR__, 2 ) . '/folder-to-document';  

$iterator = Symfony\Component\Finder\Finder::create()
    ->files()
    ->name('*.php')
    ->exclude('build')
    ->exclude('tests')
    ->in($dir);

/**
 * The build_dir and cache_dir are relative to the 'docs' folder itself, so they will be in the 'docs' folder itself.
 * You could give it any name you want, but keep it a bit logical to what your documentation contains.
 */
$options = [
    'theme'                => 'default',
    'title'                => 'Folder to Document API Documentation',
    'build_dir'            => __DIR__ . '/folder-to-document/build',  // relative path to the build
    'cache_dir'            => __DIR__ . '/folder-to-document/cache',  // relative path to Twig assets/templates
];

$sami = new Sami\Sami($iterator, $options);

return $sami;

• build_dir: When you create another documentation project within the reach of this folder structure, change the 'folder-to-document' with another subfolder name.
• cache_dir: Same recommendation as with the 'build_dir' tag.

Step 4. Generating the documentation

Open a terminal or DOS/terminal prompt and go to the root of the 'docs' folder.

Now type:

php ../sami.phar update folder-to-document.sami.php

Step 5. Viewing the documentation

After the command has executed, you can run the built-in PHP server to see how your documentation works.
Run:

php -S localhost:8000 -t build/

and visit http://localhost:8000/folder-to-document/ to see the result.

or go to the 'build' folder and run:

php -S localhost:8000