PHP Inline Documentation

Many of the core WordPress files feature inline documentation. This documentation, in the form of a code comment, gives specific details on how functions and code work. All PHP inline documentation is formatted using inspiration from the PHPDoc standard for PHP commenting, meaning there are some differences between the PHPDoc standard and the WordPress implementation of inline documentation. The following comment sample is the standard template for documenting a WordPress function:

/**
 * Short Description
 *
 * Long Description
 *
 * @package WordPress
 * @since version
 *
 * @param    type    $varname    Description
 * @return   type                Description
 */

Inline documentation is an invaluable resource when exploring functions in WordPress. The comment includes a short and long description, detailing the purpose of a specific function. It also features the WordPress version in which it was added. This helps determine what new functions are added in each release of WordPress.

Parameters are also listed, along with the data type of the parameter and a description of what the parameter should be. The return type and description are also listed. This helps you understand what value a specific function will return. For example, when creating a new post in WordPress, the newly created post ID would be returned if successful.

Now look at the following real inline documentation for the delete_option( ) function:

/**
 * Removes option by name. Prevents removal of protected WordPress options.
 *
 * @since 1.2.0
 *
 * @global wpdb $wpdb WordPress database abstraction object.
 *
 * @param string $option Name of option to remove. Expected to not be SQL-escaped.
 * @return bool True, if option is successfully deleted. False on failure.
 */
function delete_option( $option ) {

The inline documentation features a clear description of the purpose of this function. You can see that the function is part of the WordPress package and was added in version 1.2.0. The comment also lists any PHP globals that are used within the function or method, which can include an optional description of the global.

The only parameter required for this function is $option, which is described as the option name. Finally, the return value is boolean; True if successful and False on failure.

Another important tag that may exist within the inline documentation is the @deprecated tag. A deprecated function in WordPress is a function that should no longer be used. Typically, if a function is @deprecated, a new function will exist that replaces it. Let's look at an example of the @deprecated tag for the get_the_author_description() function.

/**
 * Retrieve the description of the author of the current post.
 *
 * @since 1.5.0
 * @deprecated 2.8.0 Use get_the_author_meta()
 * @see get_the_author_meta()
 *
 * @return string The author's description.
 */
function get_the_author_description() {

As you can see, the @deprecated tag exists within the inline documentation. In this example, the appropriate new function to use is the get_the_author_meta() function. The deprecated function was added to WordPress in 1.5.0 and deprecated in the 2.8.0 release. This is especially important information to verify that your plugin is using the most up‐to‐date functions within the WordPress core software.

For more information on the PHP Documentation Standards, visit the WordPress Handbook section at https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/php.

JavaScript Inline Documentation

As with PHP, JavaScript files also include templated code documentation. WordPress follows the JSDoc 3 standard for inline JavaScript documentation. The format of the JSDoc 3 standard is similar to the WordPress PHP format, but there are some slight differences. To learn more about WordPress commenting in JavaScript, visit the handbook at https://make.wordpress.org/core/handbook/best-practices/inline-documentation-standards/javascript.

Inline documentation is an ongoing process. All new functions added to WordPress are documented using this process. Helping to document existing functions is a great way to dive into core contributing to WordPress.

Finding Functions

Now that you understand how to use inline documentation to learn functions in WordPress, you need to know how to find those functions. To start, make sure you have downloaded the latest version of WordPress to your local computer. You will be searching through these code files for functions.

Every core file, excluding images, can be viewed in a text editor program. When choosing a text editor to use, make sure it supports searching within files. You can find an extensive list of text editors on the Codex at https://wordpress.org/support/article/glossary/#text-editor.

When searching through the core WordPress files for a specific function, you need to make sure calls to that function are filtered out or you may get hundreds of results. The easiest way to do this is to include the word function at the start of your search. For example, to find wp_insert_post(), simply search for function wp_insert_post.

Common Core Files

Many of the functions you use in your plugins are located in specific core files. Exploring these files is a great way to find new and exciting functions to use in your plugins.

The wp‐includes folder features many of the files used for public‐side functions: that is, functions used on the public side of your website.

Navigating the Handbook

The Plugin Developer Handbook covers a wide range of plugin development topics. To quickly find a topic of interest, you can use the search field. There is also extensive navigation on the left with topics and subtopics covering a large variety of plugin development material.

The handbook is an exceptional resource when developing WordPress plugins. If you are interested in contributing to the handbook, reach out to the WordPress Docs Team at https://make.wordpress.org/docs.

Code Reference

Another invaluable tool on WordPress.org for plugin developers is the Code Reference. The Code Reference is a detailed handbook of WordPress functions, classes, methods, and hooks. You can easily search using the search field and filter the results by the type of item you are looking for.

The Code Reference is largely generated using the inline comments that we reviewed earlier in this chapter. Let's look at the add_option() function as an example: https://developer.wordpress.org/reference/functions/add_option.

As shown in Figure 16‐1, the top of the code reference page shows the function with all the available parameters. Next is a detailed description of exactly what the function does, in this case creating a new option value in the database. The parameters are then listed with each parameter type, whether it is required or not, a short description explaining the parameter, and the default value.

Next the return value is shown, if one exists. The source file is identified, so you know where the function is defined, in this case wp‐includes/option.php as well as the code defining the function. Next we have the changelog, which identifies what version of WordPress introduced this function. The related section shows “Uses” and “Used by” functions. The final section is the “User Contributed Notes” section. This is the one area where a user can log in and submit example code and notes to expand the entry. As you can see, this visual resource may be an easier way to digest the information that exists within the WordPress Core software.

Visit the Code Reference at https://developer.wordpress.org/reference.

Searching the Codex

You can search the Codex in a few different ways. The most common way is to use the Codex search located at https://wordpress.org/search or to enter your search terms in the search box located in the header of WordPress.org. The default search for the Codex is everything, but you can also search the Support Forums, Developer Documentation, or Support Docs, as shown in Figure 16‐2.

The Codex also features an extensive glossary. This can help you become familiar with terms used in the Codex, as well as in WordPress. You can access the glossary at https://wordpress.org/support/article/glossary.

The Codex home page also features an index of articles organized by topic. The articles are ordered by level of difficulty, with an article specific to the latest version of WordPress near the top. This article details new features, functions, changes, and so on, in the latest version of WordPress. It's always helpful to read this article to become familiarized with any changes to functions and methods for developing plugins in WordPress.

Function Reference

One big benefit of the Codex is the function reference section located at https://codex.wordpress.org/Function_Reference. This section lists all functions in the Codex for the more popular WordPress API functions. This page is a must‐bookmark for any WordPress plugin developer.

Each individual function reference page contains a description of the function, basic usage example, parameters required for the function, and return values. Think of these function reference pages as quick and easily readable inline documentation on a function. Most function pages also feature an example, or more, demonstrating practical uses of that particular function.

PHPXref

PHPXref is a cross‐referencing documentation generator. Quite simply, it is a developer tool that can scan a project directory and translate the files processed into readable cross‐referenced HTML files. It automatically processes PHPDoc commenting to produce documentation for the functions included.

An online hosted version of PHPXref is also available, which is more specifically for WordPress. The online version is located at https://phpxref.ftwr.co.uk/wordpress.

Visiting the WordPress PHPXref site, you'll be confronted with what looks like a Windows Explorer layout, as shown in Figure 16‐3.

As you can see, the standard WordPress folder displays on the left with the core subdirectories and root files listed. As an example, click into the wp‐includes directory and click the plugin.php file. Clicking this link brings up a summary view of the current file selected, in this case plugin.php. This summary view has useful information including a list of every function in the file, as shown in Figure 16‐4.

Getting a top‐level glance at all functions in a WordPress core file is a great way to find new functions and even locate existing functions for reference. Clicking any listed function takes you to the section of the page detailing the usage of the function. This information is extracted from the inline documentation saved in the WordPress Core file. If the function is not documented in WordPress, this section will be empty. You can also easily view the source of any file by clicking the Source View link near the header of the page.

It's easy to see how useful the WordPress PHPXref site is for a developer. This is another required tool to add to your resource arsenal.

Hooks Database

The WordPress hooks database, which was created and is supported by Adam Brown, is the essential resource for discovering hooks in WordPress. Adam built a system that digs through all WordPress core files and extracts every action and filter hook that exists in WordPress. He has been indexing these values since WordPress 1.2.1 and updates the hooks database with each new major version of WordPress.

One of the best features of the hooks database is you can view all new hooks added in each version of WordPress. Hooks are one of the most powerful features that you can use when creating plugins in WordPress. Clicking any hook name produces a hook detail screen showing where the hook is defined in the WordPress Core code.

To visit the hooks database, visit https://adambrown.info/p/wp_hooks.

Make WordPress

The Make WordPress section of WordPress.org is a collection of websites and team groups dedicated to contributing to different parts of the WordPress project. You can view all teams on the official website at https://make.wordpress.org. These are important WordPress teams for plugin developers to follow:

• Core: This is the core team that creates the WordPress software. If you are interested in contributing to the core development of WordPress, or just want to stay in the loop on active discussions, this is the team for you.
• Design: The team is dedicated to designing and developing the user interface of WordPress. This is the perfect team for designers and user experience (UX)–focused users.
• Accessibility: Accessibility is an extremely important part of all website development. This team focuses on making WordPress accessible to everyone on the Internet.
• Polyglots: WordPress is used by millions of websites around the globe. This team focuses on translating WordPress into as many languages as possible.
• Plugins: The plugin review team is tasked as the gatekeepers for all plugins released in the official WordPress Plugin Directory. This team is especially important to keep up‐to‐date on development, security, and guidelines for building and releasing plugins.
• Documentation: A critical component to all software projects is good documentation. This is the WordPress team dedicated to that effort.

As you can see, there are many different teams dedicated to the growth and success of the WordPress project. The teams consist largely of volunteers who help coordinate and run project initiatives. You can view an aggregated list of team meetings at https://make.wordpress.org/meetings.

Support Forums

WordPress.org features a large support forum for topics ranging from using WordPress to plugin development. You can visit the support forums at https://wordpress.org/support.

Multiple forum sections can help expand your knowledge on plugin development and can support any public plugins you have released. The following are the forum sections specific to plugins:

• https://wordpress.org/support/forum/wp-advanced: Discussions are more advanced and complex than usual.
• https://wordpress.org/support/forum/multisite: Anything and everything regarding the Multisite feature.
• https://wordpress.org/support/forum/plugins-and-hacks: Plugin support questions. If you release a plugin to the Plugin Directory, users can submit support issues specific to your plugin.

WordPress Slack

Often it's nice to have a live conversation when seeking help for plugins or about WordPress development. WordPress uses Slack for live chat and has a number of active chat rooms or channels. To join the WordPress Slack Workspace, you need to follow the instructions at https://make.wordpress.org/chat.

• #core: This is the main channel for WordPress Core discussions. Room conversations focus primarily on the development of the WordPress software and the management of the WordPress.org systems. This room is not for general WordPress discussions, but rather specific to core development or bugs and issues found within the core. Most of the core WordPress developers and contributors are in this room and willing to help you.
• #pluginreview: This channel is dedicated to the discussion of technical reviews on plugins submitted to the WordPress Plugin Directory on WordPress.org. This is a great place to chat with the Plugin Review Team regarding publishing your plugin on WordPress.org.

These Slack channels are an awesome resource for real‐time help when developing plugins in WordPress. Many WordPress experts hang out in these rooms and enjoy helping others learn WordPress.

WordPress Development Updates

When developing plugins, and releasing to the public, you need to stay current on new features and functionality coming in the new version of WordPress. This can help you verify not only if your plugin is compatible with the latest version but also what new features your plugins can take advantage of. One of the best ways to track WordPress development is through the Make WordPress Core site at https://make.wordpress.org/core.

The Make WordPress Core site is a blog that focuses on the core development of WordPress. You can also find out about the weekly developer chats that take place in the Slack channel #core. These chats discuss the current status of the upcoming WordPress version, feature debates and discussions, and much more.

WordPress Ideas

WordPress.org features an ideas section for creating and rating ideas for future versions of WordPress. This is actually a great resource for gathering ideas for plugins. Many of the ideas submitted could be created using a plugin. The more popular an idea is, the more popular the plugin will most likely be.

The WordPress Ideas area is at https://wordpress.org/ideas.

Community News Sites

There are some great websites that focus on WordPress developer–related news and articles. Many of these sites feature development‐focused tutorials and tips that can be used when creating your plugins. The following sections explore useful community news sites that are available.

Local Events

Another great resource is local WordPress events. When learning to create plugins in WordPress, it can help to find other enthusiastic developers near you to learn from and work with.

WordCamps are locally organized conferences covering anything and everything WordPress. Many WordCamps feature plugin‐development‐specific presentations given by some of the top plugin developers in the community. These presentations are a great way to learn new and advanced techniques to use in your plugins. To find a WordCamp near you, visit https://central.wordcamp.org.

WordPress Meetups are also a great way to meet local developers in your area. Meetups generally happen more often, typically on a monthly basis, and are a local gathering of WordPress enthusiasts. Meetups are also generally smaller, more focused groups allowing for more in‐depth and personal conversations to take place. To find a local WordPress Meetup, visit https://www.meetup.com/pro/wordpress.

Browser

WordPress is web software; therefore, you will spend much of your time debugging plugins in your web browser. Some browsers stand above the rest when it comes to developer features. The two more popular development browsers are Firefox and Google Chrome. Both of these browsers feature development tools and can be expanded with additional tools to make debugging and troubleshooting much easier.

Firefox features powerful web development tools called the Firefox Developer Tools. These tools enable you to easily edit, debug, and monitor HTML, CSS, and even JavaScript. Firefox also supports Extensions enabling you to enhance the features in Firefox. You can learn more about Firefox Developer Tools at https://developer.mozilla.org/en-US/docs/Tools.

Google Chrome is also a great development browser. Chrome features a built‐in set of tools called Chrome DevTools. These tools can enable you to edit and debug HTML, CSS, and JavaScript in real time. You can also install extensions in Chrome that add additional functionality to the browser. You can learn more about Chrome DevTools at https://developers.google.com/web/tools/chrome-devtools.

Editor

Creating plugins for WordPress is as simple as creating a PHP file. PHP files are actually text files with a .php extension. Because of this, you can develop PHP files using any basic text editor. Although text editors can certainly get the job done, they won't offer the more advanced features such as syntax highlighting, function lookup, spell‐check, and so on.

Deploying Files with FTP, SFTP, and SSH

When developing plugins, you need to decide whether you plan to run a local instance of WordPress on your computer or use an external web server. If using an external server, you need to use some method to push your files to your server. The most popular method is using SFTP.

File Transfer Protocol (FTP) is a standard network protocol used to copy files from your computer to another computer, or a web server in this case. For FTP, FileZilla is a free, open source FTP client that works on Windows, macOS, and Linux. You can learn more about FileZilla and can download the client at https://filezilla-project.org.

Secure File Transfer Protocol (SFTP) is also a popular method for deploying files to a server. The major difference between FTP and SFTP is that SFTP is encrypted. This means any account info, usernames, passwords, and files you transfer are sent over an encrypted transport. Many popular FTP clients, including FileZilla, also support SFTP.

Secure Shell (SSH) is a third option for transferring files to a web server. SSH is more than just a way to transfer files. For example, you can interact with MySQL using SSH. A popular SSH client is PuTTY, which runs on Windows and UNIX platforms and can be found at https://www.putty.org. Mac users can use the built‐in shell called Terminal when working with SSH.

phpMyAdmin

On occasion you may need to directly work with the WordPress database. The most common method to do this is by using phpMyAdmin, which is a free tool, written in PHP, which provides a simple web interface to view and manage a MySQL database. Most web hosts have this tool installed by default.

Using phpMyAdmin, you can easily view what data your plugin adds to WordPress tables. This can significantly help speed up the debug process. You can also run phpMyAdmin on your computer by downloading the software package at https://www.phpmyadmin.net/downloads.