Chat with us, powered by LiveChat

This website uses cookies

Our website, platform and/or any sub domains use cookies to understand how you use our services, and to improve both your experience and our marketing relevance.

Using PHP Documentation Generator Sami for REST API Documentation

June 27, 2017

5 Min Read
PHP Documentation Generator
Reading Time: 5 minutes

Developers regularly create large blocks of code that form parts of API’s and other mid to large level projects. While there is a (more or less) agreed upon convention for code writing, every developer has a personal comment and documentation writing standards. Some add small cryptic notes while others attach full-length Google Docs that document the method or class in painful details. This problem becomes very severe when the number of end users increases and there is a need for proper documentation of the project. In the case of APIs, particularly REST APIs, the need for using PHP documentation generator for REST API documentation becomes acute because of wide distribution and use of the API.

Now I will start with an example of a  well formed code:


namespace SearchElastic;

use SearchElastic\SearchAbstract\SearchAbstract;


*  Class to perform basic search extends from SearchElastic\SearchAbstract\SearchAbstract


class Search extends SearchAbstract



    * Search in Elasticsearch.


    * @param  string  $query

    * @return Result from elasticsearch


   public function search($query)



       $client = $this->client->getClient();

       $result = array();

       // Change the match column name with the column name you want to search in it.

       $params = [

               'index' => $this->client->getIndex(),

               'type'  => $this->client->getType(),

               'body'  => [

                   'query' => [

                       'match' => [ $this->searchColumn => $query],




       $query  = $client->search($params);

       return  $this->extractResult($query);



Notice the following chunk of comments in the above code:


    * Search in Elasticsearch.


    * @param  string  $query

    * @return Result from elasticsearch


This long form comment is called DocBlock, a multi-line comment declared at the top of an implementation of any class, interface, method, attributes and properties etc. This tells the reader (developer or end user) what action(s) this code block performs, what parameters are required, and if it returns any values. You can add more information in the DocBlock.

A DocBlock starts with a forward slash and two asterisks (/**), which is similar to the start of a multiline comment but with an additional asterisk, and ends with an asterisk and forward slash (*/). It also contains tags, annotations and descriptions for defining namespaces and class instances.

First PHP Website Migration Is Free At Cloudways

Cloudways Engineers can migrate your website Flawlessly

Generate Documentation for API’s

DocBlocks are important because they are used by a well known Symfony document generator package called Sami. Very popular in PHP community, this PHP documentation generator also provides the ability to create custom twig templates and work with versioned documentation on GitHub.

In this article, I will use Sami and a GitHub project Sync Mysql data with Elasticsearch to automatically generate documentation.

You might be interested in: How To Create Simple REST API In Symfony 3.1

Install Sami

To install Sami for a PHP application, I assumed that you have already launched a PHP stack server and the application on Best PHP Hosting of Cloudways.

Now SSH to your project folder and run the following composer command:

$ composer require sami/sami

After the installation, you can check whether Sami has been installed properly and available for action.  For this, run the following command:

$ php vendor/sami/sami/sami.php

The output should be:

This shows that Sami is ready to generate documentation.

Clone GitHub Application

I recently discovered a great package Sync Mysql data to Elasticsearch on GitHub which has proper comments and Docblocks.

To start, you should clone this package to your application, using the following command:

$ Git clone

If you view the src files of this package, you will see the proper comments added to all the coding blocks. These blocks help Sami understand the structure and properties of the components of the package.

Create the config.php File

You need to create a config.php file in the config folder in the root directory. Sami reads this file and creates the document files accordingly. The minimum requirement for document generation process is the folder path where the code is kept.

Here  is what to include in the config.php:


return new Sami\Sami('mysqlwithelasticsearch/src/');

Now run the following command in the terminal:

$ php vendor/sami/sami/sami.php update config/config.php

Sami will read the config file and generates two folders in the project’s root directory, build (contains the output files) and cache (contains twig template cache).

Now access the build folder’s URL in the browser. In my case the URL is:

You will see the following output containing all classes, namespaces, methods, properties and variables defined in the code:

So by using the basic configuration, I have generated the entire (properly formatted) project documentation using Sami.

You can also expand config.php file by defining more configurations like iterators,options and versions for Git compatible documentation. Sami uses Symfony’s Finder component with arrays as a parameter.

Here is a more advanced configuration:

use Sami\Sami;

use Sami\RemoteRepository\GitHubRemoteRepository;

use Symfony\Component\Finder\Finder;

$dir = __DIR__ . '/../mysqlwithelasticsearch/src';

$iterator = Finder::create()






$options = [

   'theme'                => 'default',

   'title'                => 'MYsql with Elasticsearch API Documentation',

   'build_dir'            => __DIR__ . '/../build',

   'cache_dir'            => __DIR__ . '/../cache',


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

return $sami;

I have saved the source path in $dir, and then in $iterator. I included all PHP files and exclude the build and test folders (thus including just the code files only). The $options have the default theme and the title for the document. Additionally, it contains the build_dir for output and cache_dir for twig caching.

Configure Git Versions

When working with versions in Git, you must add the ‘%version%’ tag. For generating documentation for all the tags in version 2.0, it’s sub-branches and the master branch, you need to specify add() and addFromTags()


use Sami\Sami;

use Sami\RemoteRepository\GitHubRemoteRepository;

use Sami\Version\GitVersionCollection;

use Symfony\Component\Finder\Finder;

$dir = __DIR__ . '/../mysqlwithelasticsearch/src';

$iterator = Finder::create()






$versions = GitVersionCollection::create($dir)


   ->add('2.0', '2.0 branch')

   ->add('master', 'master branch');

return new Sami($iterator, array(

   'theme'  => 'default',

   'versions'  => $versions,

   'title'  => 'MYsql with Elasticsearch API Documentation',

   'build_dir'  => __DIR__.'/../build/%version%',

   'cache_dir'  => __DIR__.'/../cache/%version%',

   'remote_repository' => new GitHubRemoteRepository(username/repository', '/path/to/repository’),

   'default_opened_level' => 2,


Now run the update command in the terminal:

$ php vendor/sami/sami/sami.php update config/config.php

Now you will see the build directory containing folders for each version.

Create Custom Themes

Till now, I am using the default theme. However, Sami provides the flexibility to create your own themes.

For this, you need to create a theme folder in the root and define the path in the config.php file:

$templates = $sami['template_dirs'];

$templates[] = __DIR__ . '/../themes/';

$sami['template_dirs'] = $templates

Now to create a new theme, you need to add the folder with theme’s name. Every theme contains a manifest.yml file, often with the following content:

name:   newtheme

parent: default

The custom theme will extend the default theme properties.

Final Words

Sami greatly eases the documentation generation process for API and PHP projects of all scales. With a simple configuration, you are done with this essential yet tiresome task.

Note that Sami is not the only PHP documentation generator or REST API documentation tool in the market today. You could also try out phpDocumentor. However, Sami provides several advanced options that are not found in other options.

So try out Sami for your next project! If you have a question or would like to contribute to the discussion, do leave a comment below.

Share your opinion in the comment section. COMMENT NOW

Share This Article

Launch PHP websites without the worry of Server Management.

Pre-Installed Optimized Stack with Git, Composer & SSH

Shahroze Nawaz

Shahroze is a PHP Community Manager at Cloudways - A Managed PHP Hosting Platform. Besides his work life, he loves movies and travelling. You can email him at

Get Our Newsletter
Be the first to get the latest updates and tutorials.

Do you like what you read?

Get the Latest Updates

Share Your Feedback

Please insert Content

Thank you for your feedback!

BFCM 2019