Writing a Module

Modules in the Performance Lab pluginPlugin A plugin is a piece of software containing a group of functions that can be added to a WordPress website. They can extend functionality or add new features to your WordPress websites. WordPress plugins are written in the PHP programming language and integrate seamlessly with WordPress. These can be free in the WordPress.org Plugin Directory https://wordpress.org/plugins/ or can be cost-based plugin from a third-party share various similarities with WordPress plugins:

  • They must have a slug, a name, and a short description
  • They must function 100% standalone
  • They must have an entry point file that initializes the module
  • Their entry point file must contain a specific headerHeader The header of your site is typically the first thing people will experience. The masthead or header art located across the top of your page is part of the look and feel of your website. It can influence a visitor’s opinion about your content and you/ your organization’s brand. It may also look different on different screen sizes. comment with metaMeta Meta is a term that refers to the inside workings of a group. For us, this is the team that works on internal WordPress sites like WordCamp Central and Make WordPress. information about the module

Every module surfaces on the admin settings page of the Performance Lab plugin, where it can be enabled or disabled.

Module requirements

  • The production code for a module must all be located in a directory /modules/{focus}/{module-slug} where {module-slug} is the module’s slug and {focus} is the focus area: an identifier of a single focus (e.g. images). This should correspond to a section on the Performance Lab plugin’s settings page. See the perflab_get_focus_areas() function for the currently available focus areas.
  • The entry point file must be called load.php and per the above be located at /modules/{focus}/{module-slug}/load.php.
  • The load.php entry point file must contain a module header with the following fields:
    • Module Name: Name of the module (comparable to Plugin Name for plugins). It will be displayed on the Performance Lab plugin’s settings page.
    • Description: Brief description of the module (comparable to Description for plugins). It will be displayed next to the module name on the Performance Lab plugin’s settings page.
    • Experimental: Either Yes or No. If Yes, the module will be marked as explicitly experimental on the Performance Lab plugin’s settings page. While all modules are somewhat experimental (similar to feature plugins), for some that may apply more than for others. For example, certain modules we would encourage limited testing in production for, where we’ve already established a certain level of reliability/quality, in other cases modules shouldn’t be used in production at all.
  • As the first lines of actual PHPPHP PHP (recursive acronym for PHP: Hypertext Preprocessor) is a widely-used open source general-purpose scripting language that is especially suited for web development and can be embedded into HTML. http://php.net/manual/en/intro-whatis.php. code, the load.php file must contain a check for a module-specific version constant that it sets afterwards. This is to prevent loading the module in case a standalone plugin version of the same feature is already active on the site. The constant name should be clearly associated with the module name, and it must use the string “Performance Lab ” concatenated with the Performance Lab version constant as its value. See the example code below for what this constant check and declaration should look like.
  • The load.php file must not contain any unconditional declarations, i.e. it shouldn’t define any functions, classes, constants etc unconditionally. The file should barely contain any code at all. The actual code for the module should be included in separate files that are part of the module directory. The load.php file should only be used to include these files.
  • The module must neither rely on any PHP code from outside its directory nor on any external PHP code. If relying on an external PHP dependency is essential for a module, the approach should be evaluated and discussed with the wider team.
  • The module must use the performance-lab text domain for all of its localizable strings.
  • All global code structures in the module PHP codebase must be prefixed (e.g. with a string based on the module slug) to avoid conflicts with other modules or plugins.
  • All test code for a module (e.g. PHPUnit tests) must be located in a directory /tests/modules/{focus}/{module-slug} where {module-slug} is the module’s slug and {focus} is the focus area (i.e. the same folder names used above).
    • If tests require some test-specific structures (e.g. dummy data or mock classes), those should be implemented in a directory like /tests/testdata/modules/{focus}/{module-slug}.
  • The module must adhere to the WordPress coding and documentation standards.

Top ↑

Module recommendations

  • Modules should be written with a future WordPress coreCore Core is the set of software required to run WordPress. The Core Development Team builds WordPress. merge in mind and therefore use coding patterns already established in WordPress core. For this reason, using PHP language features like autoloaders, interfaces, or traits is discouraged unless they are truly needed for the respective module.
  • Modules should always be accompanied by tests, preferably covering every function and class method.
  • Modules should refrain from including infrastructure tooling such as build scripts, Docker containers etc. When such functionalities are needed, they should be implemented in a central location in the Performance Lab plugin, in a way that they can be reused by other modules as well – one goal of the Performance Lab plugin is to minimize the infrastructure code duplication that is often seen between different projects today.

Top ↑

Example

The following is a minimum module entry point file /modules/images/my-module/load.php (i.e. the module slug is my-module, and the focus is images). Since the module is just a demo module, it is very simple and all its code requires only two files, /modules/images/my-module/load.php and /modules/images/my-module/hooks.php.

<?php
/**
 * Module Name: My Module
 * Description: Enhances performance for something.
 * Experimental: No
 *
 * @package performance-lab
 * @since n.e.x.t
 */

// Do not load the module code if its code is already loaded through another means.
if ( defined( 'MY_MODULE_VERSION' ) ) {
	return;
}

define( 'MY_MODULE_VERSION', 'Performance Lab ' . PERFLAB_VERSION );

// Load the actual module code.
require_once __DIR__ . '/hooks.php';

For reference, here is what the hooks.php file for this demo plugin could look like. Note that the n.e.x.t annotation is a convention that should be used in the Performance Lab plugin for new code, which will be replaced with the correct version number prior to being included in a release.

<?php
/**
 * Hook callbacks used for My Module.
 *
 * @package performance-lab
 * @since n.e.x.t
 */

/**
 * Displays an admin notice that the module is active.
 */
function my_module_show_admin_notice() {
    ?>
    <div class="notice notice-info">
        <p>
            <?php esc_html_e( 'The "My Module" module is currently enabled.', 'performance-lab' ); ?>
        </p>
    </div>
    <?php
}
add_action( 'admin_notices', 'my_module_show_admin_notice' );

Last updated: