#StandWithUkraine
Andrey “Rarst” Savchenko —  — Software — php, yoast

Make PHP code self-explaining with PHPXref

phpxref_icon I wish this one occurred to me sooner.

For a long time I struggled with internals of WordPress (and my… intuitive PHP skills contributed to issue). I decided that I need some kind of indexing. WikidPad didn’t fit task well. I wanted something like online WordPress code references such as one by Joost de Valk.

Then it shined on me I can make my own with same tools. PHPXref is utility that takes any PHP code and creates easy to use cross-referenced documentation.

What it does

App scans directory with code and digests all files in it to produce set of documentation in HTML format. It generates:

  • lists of functions, classes, variables and constants;
  • all of those are highlighted in code and linked to their definitions;
  • comments (if present) are automatically used for function descriptions;
  • native PHP functions are linked to their official documentation.

phpxref_documentation

phpxref_documentation

It is still same code but presented in form much easier to navigate and understand. With all explanations always only click away.

Setting up

PHPXref is command line utility. It read settings from plain text phpxref.cfg file that must be manually edited (as always I suggest Notepad++).

Minimum required is only setting directory to scan in there.

For those who wish to tinker there are many more settings, including option to change documentation appearance.

Issues

I don’t like how embedded search works, it doesn’t seem to work with partial function names. On other hand it is easy enough to look things up in generated lists.

Documentations also ends up quite large. My docs for WordPress with all of plugins used and few themes almost reached 170 megabytes.

Overall

Pure bliss for browsing and understanding PHP code (WordPress or whatever else). I learned more in only few days since I generated docs than in months before that.

Freeware, open source and easily scriptable to keep docs fresh.

Home&download http://phpxref.sourceforge.net/

Related Posts

8 Comments

  • Lyndi #

    Wow, very nice. From what I can gather from their site PHPXref could be very handy, especially for those bigger, more involved projects. This should also help a lot if there is more than one coder working on the same project. I will download later today. Thanks for this.

  • Rarst #

    @Lyndi Knew you will like it. It is excellent way to study code, especially if it's not yours. Or yours and older than three days. :)

  • TechZoomIn #

    Great dude. Thanks for sharing...I'm using similar kind of tool called Winsyntax.

  • Rarst #

    @TechZoomIn Slightly different thing. :) Winsyntax is editor, while PHPXref is documentation generator. For editor I am more than content with Notepad++.

  • JeeMan #

    Just wanted to say thank you for this suggestion. I was trying to go through some php code (i.e. code for very lightweight CMS, Leap (http://leap.gowondesigns.com/) - Try it out, very cool!). All the php code is in one file, without any indentation. But after a little time, I remembered your post here. Used PHPXref, and it generates very beautiful documentation about the code, with everything laid out very clearly. Thanks for this Rarst, you've made my day (and saved me some time)!

  • Rarst #

    @JeeMan You are welcome. :) I think there is no better praise for a post than feedback that it solved issue easily and completely for someone. Bookmarked that CMS to take a look later [this decade].

  • Tobey #

    Thanks a bunch for this article Rarst, I read it like half a year back and now working on a project remembered it and found it again to point me at this great open-source tool. Best luck man!

  • Rarst #

    @Tobey Glad it is of use to you (eventually). :) By the way you might like NetBeans IDE for PHP. I've been using it lately and it is also quite good with inline documentation in PHP files. Among other things.