Date:
03 Aug 2011
Category:
Announcements
Discuss:
6 comments

Documentation has never been Symphony's strong point. More specifically, before Symphony 2.2 comments in the actual code were both cryptic and sparse. However the release of Symphony 2.2.2 marks a special milestone in its history — Symphony now has a fully documented core.

A united effort between the Core and User Experience Working Groups, the API Reference now includes all classes and methods within the Symphony core, both PHP and JavaScript!

Why is this important? Well, for a start it is an excellent example of how the community Working Groups have worked together, independently from the core development team, to contribute to the project.

Secondly, we discovered and squashed a ton of niggly bugs along the way, from mis-named methods to missing arguments, to cyclical object references and even some performance bottlenecks.

But by far the biggest benefit is for you, dear developer. If you're looking to learn how Symphony works, fixing a bug, writing an extension, or coding a custom data source, you now have a single point of reference to visualise the Symphony source. No more blindly stumbling through classes in a text editor.

The API Reference is broken down by packages, which map (more or less) on to the directory structure of Symphony itself.

Within each package (e.g. toolkit) is a list of classes, followed by exceptions, interfaces, functions and constants. Click through to a class (e.g. AdministrationPage) to view its own constants, properties and methods.

Every item has a link through to its location in the source code on Github. So even if you're looking through the reference for an older Symphony version, you can still click through and see that older source code. Similarly every item can be expanded/contracted for quicker scanning, and the # beside each provides a handy hyperlink.

For the real nerds among you, enable the Show private methods option to include all private properties and methods in the listings.

What's more, we now have an up to date list of deprecated code that you should avoid and finally a list of every delegate in the system. If you don't know your AdminPagePostGenerate from your EntryPreRender then you've got some reading to do, son.

How does it work?

The PHP source is documented using the established PHPDoc syntax, while JavaScript uses a similar JSDoc commenting syntax. The source is then run through PHPDoctor and JSDoc Toolkit, both of which have custom templates to generate XML rather than the usual (gasp) HTML framesets. The combined XML is then read from a couple of custom Dynamic XML data sources and crunched with a far-from-concise-1200-line XSLT page.

If you would like to recreate the documentation yourself (it's easy!) then download symphony-phpdoc and symphony-jsdoc and follow our instructions.

Hopefully this new sprinkling of documentation awesomesauce will significantly further your understanding of Symphony's inner workings, and enable you to continue baking even bigger slices of Symphony awesomecake.

Comments

HUGE kudos to Nick for spearheading this entire effort, and for designing the lovely API section. Brilliant, as usual.

More credit should go to Brendan for taking one (or two, or three) for the team by writing the code comments themselves. What a loser. I just stole the glory by making it look pretty.

You guys rock. I would've written about 50 x as many extensions if this had been around when I was getting started with Symphony.

  • Henry
  • 03 Aug 11, 1:18 pm

I have to say this is truly an amazing level of documentation. If I ever see anyone complain about open source project documentation, I will link them here, and tell them "this is how it should be done".

And it looks beautiful too :)

Very nice!!!!

  • Lewis
  • 09 Aug 11, 9:38 pm

Awesome stuff! Thanks Brendan & Nick!

Create an account or sign in to comment.

Symphony • Open Source XSLT CMS

Server Requirements

  • PHP 5.3-5.6 or 7.0-7.3
  • PHP's LibXML module, with the XSLT extension enabled (--with-xsl)
  • MySQL 5.5 or above
  • An Apache or Litespeed webserver
  • Apache's mod_rewrite module or equivalent

Compatible Hosts

Sign in

Login details