Writing a Module

Topics

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.
  • 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. Additionally it is a good practice to check whether the module code was already loaded in some other way, and in that case not load the actual code to prevent a fatal error due to redeclarations. This convention was introduced because some modules also exist as standalone plugins that can be used outside of the Performance Lab plugin.
  • The module must neither rely on any 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 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 is within a single file /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 ( function_exists( 'my_module_show_admin_notice' ) ) {
    return;
}

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

/**
 * 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' );

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: