What is the WordPress Dynamic API Reference?
- WP-a2z.org is an API reference for WordPress.
- It contains lots of information about the WordPress source code.
- It’s dynamic; it reads, parses and displays the latest source code.
- It’s also a WordPress Multisite website, with sub-domains for selected plugins and themes.
What does it do?
- It displays the inline documentation and PHP source for WordPress.
- It allows you to navigate through the files, classes, APIs and hooks.
- More often than not you can do this just by clicking on links.
- Other times you’ll have to perform a search.
What’s it for?
- It’s supposed to help you understand how WordPress works
- and/or how a plugin works
- and/or how a theme works
- or a combination of the above.
How does WP-a2z achieve its aims?
On the original site you wroteUse this site to navigate your way through WordPress core, discovering APIs and hooks and the files and classes used to implement them. Find out how they are used in WordPress and popular plugins. Discover how you can use them in your own code.Q. Those are bold statements. Is it as easy as you suggest? A. To be honest? No, it’s not that easy. I think that some parts of the navigation are significantly easier than on developer.wordpress.org. But you still need to refer to the codex.wordpress.org and the source. One of the problems is that there’s just so much information: over 5000 APIs, 1700 action hooks and filters and 225 PHP classes – and that’s just in the WordPress core. It’s a lot easier to discover how smaller stuff, such as Hello Dolly, fits into WordPress than it is for monsters such as jetpack.wp-a2z.org or woocommerce.wp-a2z.org. Elsewhere in the WP-a2z site you’ll find a FAQ that says that a2z represents the vision…
WP-a2z… The complete reference for the WordPress Application Programming InterfaceQ. Is it the complete reference? A. How do you define complete? I suppose it’s everything you already know, plus all the missing bits.
So what’s missing?
The dynamic API reference for the PHP code is just the tip of the iceberg.- What about understanding the main paths executed during page load?
- What is the sequence of action hooks and filters invoked?
- What files are loaded and what functions are invoked?
- What database accesses are performed?
- What percentage of WordPress is now implemented with jQuery/JavaScript? Where’s the API reference for that?
- What about AJAX or WP-API requests?
- What about the unit tests?
How have you used WP-a2z?
Q. How do you use the API Reference to find out how to do things? Can you give some examples? A. Tacitly. I started developing the dynamic API reference for my own plugins. There’s an API reference page for each of my plugins; see www.oik-plugins.com/apis. When I’m developing new code, or altering existing code, I use it to find a specific function or general technique I’ve used before. When I’ve found something like the function or hook I’m looking for I use the call tree to see how the routine is invoked, or dive deep into the function to see what it does. Earlier this year I decided that I needed to be able to navigate my way into WordPress core code. I decided to extend my routines to parse that as well. The code for WP-a2z was developed in parallel with WP-Parser; two approaches with similar aims. Nowadays, when I want to follow what’s going on in someone else’s plugin or theme I build an a2z for it. More often than not, I can find things with a Google search using thea2z keyword.
But, I still need to be able to open up and edit the code locally in my favourite editor or IDE.
What’s the future for WP-a2z?
Q. What needs to happen for WP-a2z to become the “go to” resource? A. I don’t believe that WP-a2z, in its current form, is anywhere near the final solution.It needs to be able to help developers find answers to their questions.
- It needs to be speedy.
- It needs to be up to date.
- It needs to be complete.
- It needs to be usable.
So how can we help?
Q. Why work on WP-a2z rather than WP-Parser? A. Both projects have their challenges. WP-Parser is ahead in some areas and WP-a2z is ahead in others. Future development of WP-a2z includes: building where used trees for files, identifying function invocation through callbacks, better support for detecting method invocation and logging the action and filter hook invocation sequence during page load. We also need to do a better job of displaying the carefully crafted content from the docblocks. Q. Can other developers create clones of your site for their own plugins or themes? A. Yes. The source is available on GitHub. But it would probably be easier to create a new sub-domain.Is there anything else?
Many years ago I was working on a system which could produce an amazing number of error messages. The technical authors responsible for the Messages and Codes manual had little or no capability to extract the information about each error message from the source code. So I set about writing a routine that would automagically create the main content. 95% of the time, extracting the information was fairly easy. But there were cases when it was necessary to partially interpret the code in order to determine values for API parameters. The same is true for WordPress code; there will be cases where either the parsing routine has to be a little smarter or the developer/documentor has to provide the automated tools with better hints. In order to produce the file trees we’ll have to use rule based logic, similar to that in makepot.The more people there are working on solving these problems the more chance we have of building a complete and usable API reference.
