Generate Your PHP Documentation

In my last post, I tell you to make your code well documented, for a reason. But sometimes, making your code documented wasn’t that much help at all.

I mean, to know what your code docs, you need at least code hinting that shows docs like IntelliSense, or you must open the source code. Of course, this can be inconvenient. Especially if your IDE/Editor doesn’t have that feature at all.

In a language like PHP, it seems that I can’t find proper/perfect code hinting that can be as good as IntelliSense for C# or C++. It not something that can’t be tolerated since it will be hard to know data type in variable especially a programming language like PHP. Look at the code bellow:

This code is for loading the class file and return the instance of that class. But in general, the variable $router can hold any value, like boolean, int, float or hold nothing (null).

You, the programmer may know what the data type is, but your computer can’t really know it at least until you run the code. Because of that, it will be hard to show code hint like method or property on $router var.

That why it better to get used to reading the documentation. It doesn’t have to be reading the docs on the source code, just look at any web documentation if available. It more friendly and easy to navigate. Look at this Amazon Web Service SDK.

You don’t have to make it manually, you can generate that. As long as your documentation is written correctly, you can generate your code docs easily.

You can use any docs generator you like, but in this post, I will show you an example how to generate docs using ApiGen. Don’t worry, it pretty easy.

apigen_website

Requirements

First thing first. You need any requirements and know how to run PHAR file. If you don’t know how you can read my other post on how to run .phar files.

You can also install it using composer, but I think the easiest way to do this is using the .phar version. That why, we will be using the .phar version.

Installation

You must download the ApiGen .phar file and can be downloaded from its github repository. If you feel lazy to search for it, you can click here. It will redirect you to ApiGen github repository download section. Download the .phar file and place it anywhere you like.

Running ApiGen

Now after you get the ApiGen .phar file, just run it with parameter generate with a path to your PHP project directory and output. Like this:

Parameter -s mean that you define the source directory where your code is and -d mean that you define the output directory.

If you want to get all parameter command you can do with ApiGen, you can enter CLI command like this:

To ease the process, you can create the .bat file if you are on windows or bash script if you are on Linux. I use this to generate PHP Docs using ApiGen and I just need to insert the path to my source code and docs title, like this:

Simple right? And the .bat file I’m using look like this:

You can copy my .bat source code if you want and use it whatever you want, it nothing special.

That it for now, thank you for reading. If you have any question or feedback, feel free to write them in the comment bellow. Don’t worry, it’s free.