API Builder changes

Yii 1.1 Tips, Snippets and Tutorials
1

Hi,

As you all know Yii has a great class reference available on its website, and anyone can generate its own local version of it using the API builder provided. While it does its job perfectly fine, since it has been made to only do Yii’s API it isn’t necessarily easy to use it to generate another API, e.g. one of your own extension.

Now because I wanted to be able to do that, and to use Yii’s API builder, I made some changes to make this a little easier. Mainly, I removed a bunch of the hard-coded settings from the command itself, to put them on an external configuration file. That way, while you can still use it to generate Yii’s API of course, it’s also quite easy to have it generate another API, be it of an extension for Yii, or a full project, based on Yii or not.

The idea is that you now call the api command with only one parameter, the name of a PHP file that must return a config array, with:




	'pageTitle'		=> 'MyExt Class Reference',		// optional: Class Reference

	'baseSourceUrl'		=> 'http: //myext.domain/repository/trunk',

	'version'		=> '1.0',

	'fileTypes'		=> array('php'),	// optional: array('php')

	'exclude'		=> array('.svn'),	// optional: array(.svn')

	'docPath'		=> 'myext/doc',

	'items'			=> 'myext/sce',		// can also be an array of files/folders

							// (useful when some file must be treated first)

	'offline'		=> TRUE,		// optional: TRUE

	'check'			=> FALSE,		// optional: FALSE

I also added two other things :

  • support for the @throws tag, now listed as {throws} before the {return}

  • (ugly hack) support for namespaces

The namespace support certainly isn’t done in the best way possible, but while working on a little project (not Yii-related, but for which I wanted to use Yii’s API builder as well) I needed it to have a basic support for namespaces. What does it mean? That when using namespaced files, it will be supported (i.e. classnames will be “translated” to their fully namespaced names) if:

  • you only have one namespace per file

  • you only use “namespace NAME;” and “use CLASS”; or “use CLASS as ALIAS;” – IOW, while PHP supports a “use CLASS as ALIAS, CLASS, CLASS as ALIAS;” the API builder doesn’t. It’s probably not too complicated to change the regexp (used to extract those) to add such support, but I’m no regexp guru and didn’t care to bother with this, quite frankly.

Like I said earlier, what this support will do is "translate" the classnames to their full namespaced names, so if you have this:




namespace MyApp;

use Foo\Bar as Foobar;

use \Class;

Then all the “Foobar” occurrences will be replaced by “Foo\Bar” (e.g. using {@link Foobar::run} would be the same as having used Foo\Bar::run), the ones of “Class” would not be touched (the leading backslash isn’t used/shown if fully qualified names), and anything else would be prefixed with “MyApp” e.g. “SomeClass” would become “MyApp\SomeClass”

(So obviously, if you don’t use namespace then nothing changes.)

As for the filenames (of generated HTML files) the backslashes are simply replaced by dots, e.g. "Foo.Bar.html" for the Foo\Bar class.

Alright, I think that’s about it, so attached is the patch to get all those changes. ( And if you wanna see what it looks like, the class reference of my little namespaced project (for which I made/use this) is available at bysma.bitbucket.org/api.html )

Hopefully this might be useful to some,

-pinpin