Simple Class API Generator

Code GeneratorDuring the week at work, I was putting together a Web Service in PHP and while doing so I had to prepare some documentation for the Web services classes. I couldn’t find any library apart from phpDocumentor which could do the job. phpDocumentor is too full on and I needed a simple solution. And thats when I dug deep into the Reflection API.

PHP 5 comes with a complete reflection API that adds the ability to reverse-engineer classes, interfaces, functions and methods as well as extensions. Additionally, the reflection API also offers ways of retrieving doc comments for functions, classes and methods. This is extremely handy when you want to generate an API for the code you are writing. Thats exactly what I managed to do using the Reflection API.

SCA Generator Source

Shown below is the source code for the API generator. As you can see, I am using the SCA_Generator class itself to generate its own API.

Simple Class API Generator

And the output of the above API generation results in the following:

/**
 * This is an API generator Class.
 *
 * It will generate documentation for a given class which has already been
 * loaded with an include or require call.
 *
 * @author Jeffery Fernandez 
 * @copyright Free to use as long as you keep the Authors name intact
 * @link http://jefferyfernandez.id.au/2007/09/01/simple-class-api-generator/
 *
 * @todo Get the constants of the class
 *
 * Simple Class API Generator
 * @since 1st September, 2007
 * @version 0.2 Updated on 2nd September, 2007
 */
Class SCA_Generator
{

	/**
	 * To store the Class name
	 *
	 * @var $class_name
	 */
	private $class_name;

	/**
	 * The constructor for the API Generator
	 *
	 * @param string $class_name The name of the Class for which to generate the API
	 * @return void
	 */
	public function __construct($class_name)


	/**
	 * A Test function with bogus params
	 *
	 * @param SCA_Generator $blah
	 * @param array $test
	 * @return void
	 */
	public static function test_function(SCA_Generator $blah[, $test = array ()])


	/**
	 * Generates the API for the Class
	 *
	 * @param boolean $show_private Decide to show private variables/functions
	 * @param boolean $show_protected Decide to show protected variables/functions
	 * @return void
	 */
	public function create_class_api([$show_private = false[, $show_protected = false]])


}

Now this is just one use of what you can do with the Reflection API. Soon after I finished this Class, I was thinking about an other scenario whereby the software project you are working on is Version controlled. Take for example if you are using Subversion version control system, you can implement post-commit hooks.

Analyse Source CodeThis means if after someone has committed some code changes to a file belonging to the software project, you can utilise the Version control system’s post-commit hook script to trigger another script to analyse what has changed. The script should analyse what lines have changed and then detect which functions it belonged to. Then we can loop through the changed functions and analyse if the functions where properly documented. If not send the user who committed the changes a Warning email saying “You need to properly document the source code”. Any takers ?

This entry was posted in PHP. Bookmark the permalink.

One Response to Simple Class API Generator

  1. Pingback: Simple Class API Generator | prosoxi.com

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>