Generate Documentations For PHP Projects and REST API Through Sami

by Shahroze Nawaz  June 27, 2017

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 a REST API documentation tool becomes acute because of wide distribution and use of the API.

rest api documentation tool

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

Notice the following chunk of comments in the above code:

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.

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, Sami 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

Instal Sami

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

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

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

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 https://github.com/ahmedkhan847/mysqlwithelasticsearch.git

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:

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:

http://phpstack-21306-71265-194073.cloudwaysapps.com/build/

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:

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()

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:

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:

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 document 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.

Create PHP websites without the worry of server management.

Deploy your PHP app on optimized PHP hosting servers.

About Shahroze Nawaz

Shahroze is a PHP Community Manager at Cloudways - A Managed PHP Hosting Platform. He’s always in search of new frameworks and methods to implement them. Besides his coding life, he loves movies and playing soccer with friends. You can email him at shahroze.nawaz@cloudways.com

Stay Connected:

You Might Also Like...