How WordPress Plugins Work Under the Hood

How WordPress Finds and Loads a Plugin

WordPress discovers plugin files in wp-content/plugins, but it loads a plugin’s PHP code during site startup only after someone activates it. That is why an installed plugin can appear in the administration area without changing how the site works.

A plugin can consist of one PHP file or a directory containing a main PHP file and supporting files. WordPress scans the plugin directory and its subdirectories for PHP files with a plugin header, a comment at the top of the file that identifies the plugin. The required field is Plugin Name; other fields can provide details such as the version and minimum WordPress or PHP requirements. WordPress uses this metadata to list the plugin in the administration area. The plugin header requirements describe the fields WordPress recognizes.

The main PHP file acts as the plugin’s entry point. When WordPress loads that file, PHP runs its top-level code. The file commonly uses that moment to register callbacks with WordPress hooks, which are named points where WordPress runs plugin code. A callback attached to the init hook, for example, runs later when WordPress reaches that point in startup. Supporting PHP files, scripts, and styles can add other parts of the plugin.

From installation to runtime loading

Installing a plugin places its files in the plugins directory. Activation is a separate action: WordPress records that the plugin should run, then calls its activation routine. On later requests, WordPress checks its active-plugin records and includes the files for valid active plugins. In a Multisite network, administrators can also activate a plugin across the network; WordPress tracks those plugins separately. The active-plugin loading reference describes how WordPress retrieves plugin paths.

WordPress loads its core code, then must-use and active plugins before continuing startup. After active plugins load, WordPress fires the plugins_loaded hook, which gives plugins that depend on other active plugins a point to run. The Plugin Handbook covers discovery and loading.

Activation, deactivation, and uninstall serve different purposes. When an administrator activates a plugin, its activation routine runs setup tasks, such as setting default options or creating a database table. When an administrator turns a plugin off, its deactivation routine can clear temporary data. Persistent settings and user data generally remain. When an administrator deletes a plugin, its uninstall routine can remove plugin-owned settings or tables. Developers register these routines through WordPress’s activation and deactivation hooks and uninstall methods.

Plugin updates do not automatically call activation routines. A plugin that needs to change its database structure after an update must use separate version-checking or upgrade logic rather than relying on activation.

A plugin’s files normally live in wp-content/plugins/. A simple plugin can consist of one PHP file; a larger plugin typically uses a folder with a main PHP file and supporting files. WordPress identifies the main file by the plugin header - a comment near the beginning of the file that includes a required Plugin Name field. Other header fields, such as the version, description, and author, provide information shown in the Plugins screen. The Plugin Header Requirements document lists the supported fields.

<?php
/**
 * Plugin Name: Example Plugin
 * Description: Adds an example feature.
 * Version: 1.0.0
 */

When WordPress loads an active plugin, it includes the main PHP file, and PHP runs any code outside functions during the request. The main file commonly loads other plugin files and registers callbacks for WordPress hooks, which let the plugin respond to events or change behavior. The header helps WordPress recognize and display the plugin, while the PHP code in the file provides its runtime behavior.

How Hooks Connect Plugins to WordPress

WordPress plugins use hooks to connect their code to named points in WordPress’s request lifecycle. A plugin registers a callback, a function that WordPress runs when a particular hook fires. This lets plugin code respond to events or change values without editing WordPress core.

WordPress loads an active plugin’s main file during startup, so the file can register callbacks before their hooks run. For example, plugins_loaded fires after active plugins load, followed later by init. A plugin that registers a callback for init therefore runs that code when WordPress reaches init, not when the registration line first executes. The Hooks Handbook describes this registration pattern and the main hook types.

Actions run code; filters return changed values

An action gives a plugin a chance to perform work at a specific point, such as registering a feature. The callback does not provide a replacement value to WordPress. Plugins attach action callbacks with add_action().

A filter passes a value to a callback and expects it to return the value WordPress will use. A plugin can use add_filter() to change page content, a query setting, or another value. Filter callbacks should return the filtered value; otherwise, later code gets an incorrect value. The Actions documentation explains how WordPress runs callbacks attached to actions.

For example, a plugin can append a short note to singular page content with the the_content filter:

function example_add_page_note( $content ) {
    if ( is_singular() ) {
        $content .= '<p>Additional information.</p>';
    }

    return $content;
}

add_filter( 'the_content', 'example_add_page_note', 10, 1 );

The plugin registers the callback when WordPress loads its file. WordPress calls it when it applies the_content to content being displayed. The callback receives the current content, appends the note for a singular post or page, and returns the resulting content.

Priorities and accepted arguments control callback behavior

The third argument to add_filter() is the priority, which sets the callback’s order relative to other callbacks on the same hook. The default is 10; lower numbers run earlier. Callbacks with the same priority run in the order WordPress registered them. If another plugin also changes the_content, priority can determine whether this callback sees that plugin’s change first or second.

The fourth argument, accepted_args, sets how many values WordPress passes to the callback. The example sets it to 1 because the callback accepts only the content value. If the callback needs more values supplied by the hook, increase accepted_args and declare matching parameters. Check the hook’s documentation to see which additional arguments it passes.

Hook timing follows the request

WordPress runs hooks at specific points as it handles each request. After loading active plugins, it fires plugins_loaded, then later fires hooks such as init during setup and wp after it has prepared the main query. When a theme displays post content, WordPress applies the_content, so filters can change the value before WordPress outputs it.

A plugin must register a callback before WordPress reaches the hook. Registering a callback while the plugin file loads makes it available for hooks that run later in the request. Registering it after a hook has already fired does not run that callback for that earlier event. The WordPress hook reference describes hooks as the points where plugins and themes connect their code to WordPress.

The right hook depends on when the code needs to run. Use an early setup hook for configuration that must exist before WordPress handles the main query. Use a content filter such as the_content when the code needs to alter content as WordPress prepares it for display.

How Plugins Use WordPress APIs and Store Data

WordPress plugins use built-in APIs to add features and save data without changing WordPress core files or tables. These APIs give WordPress a consistent way to load plugin behavior, manage settings, and expose content. The Plugin Handbook describes plugins as extensions that work through WordPress rather than by editing its core.

A plugin can store simple settings as named values in the WordPress database with the Options API. The Settings API connects that option to an administrative form and handles its submission. For example, a plugin can register a text setting like this:

add_action( 'admin_init', function () {
    register_setting(
        'acme_settings',
        'acme_banner_text',
        [
            'type'              => 'string',
            'sanitize_callback' => 'sanitize_text_field',
            'default'           => '',
        ]
    );
} );

The plugin’s settings form submits to WordPress’s options.php handler and includes settings_fields( 'acme_settings' ). WordPress then saves the submitted value under acme_banner_text. When the plugin later displays the banner, it retrieves the saved value with get_option( 'acme_banner_text', '' ) and escapes it for HTML output with esc_html(). The plugin should also check that the person changing the setting has the required capability, or permission, for that action.

Plugins use other WordPress APIs according to the kind of data they manage. A custom post type gives a plugin a content type of its own, such as events or products, that WordPress can manage alongside posts and pages. Post metadata stores additional fields associated with a post or custom post, while the Options API suits site-wide settings. Plugins can register custom database tables when the way they organize or retrieve data does not fit the built-in options. Developers should plan how to create, upgrade, and remove those tables.

Plugins also choose how people and other software interact with their features. A shortcode is a bracketed marker, such as [event_list], that WordPress replaces with generated content. A block provides an editor component that users can insert and configure in the block editor. A plugin that needs to let external clients request or update its data can expose a REST API endpoint, a URL that accepts structured requests. The endpoint should check permissions before allowing changes.

These interfaces rely on WordPress registration and storage APIs. For example, a plugin registers a custom post type during WordPress setup, then adds metadata to each item through metadata functions. It can expose that post type to the REST API when appropriate. Using the documented APIs lets WordPress handle these features consistently; direct changes to core tables or files bypass that structure and risk breaking compatibility with WordPress updates or other plugins. The Plugin Basics documentation covers WordPress’s supported plugin conventions.

How Plugin Code Runs Across Admin, Front-End, and Background Requests

WordPress loads active plugin PHP as part of handling site requests, but each plugin feature should run only in the context that needs it. A plugin typically registers callbacks during startup; WordPress runs each callback when its hook fires. That means an admin settings page, a public page, an AJAX call, a REST API request, and a scheduled task can enter different parts of the same plugin.

For browser assets, plugins should register and enqueue scripts or styles through WordPress’s asset functions. Enqueueing tells WordPress to include an asset on the page. Front-end assets belong on the wp_enqueue_scripts hook. Admin assets belong on admin_enqueue_scripts, where the hook supplies the current screen identifier so a plugin can restrict files to its own settings page. The WordPress enqueuing guidance describes these hooks and the recommended approach. For example, a settings-page script should load on that page, rather than on every dashboard screen or public page.

An AJAX request sends data to the server without loading a new page. WordPress routes these requests through named actions, with separate hooks for logged-in and logged-out visitors. The plugin’s browser script can issue the request, while a PHP callback handles it and returns a response. A REST request works similarly in that WordPress dispatches it to a registered handler, but it uses a URL-based API endpoint and can serve browsers, other services, or command-line clients. In both cases, the request needs the server-side callback; it does not need unrelated page markup or assets.

Scheduled tasks let a plugin run a callback later, such as when it needs to perform periodic cleanup. WordPress runs scheduled tasks when site activity triggers them, so a callback can run during a later request instead of at an exact clock time. A plugin should keep the scheduled callback focused on its task and avoid initializing admin screens or front-end output for it.

This separation avoids unnecessary work. Keep startup code small: register hooks, then load larger features or files only when WordPress handles the relevant screen, request, or scheduled event. Since active plugin files participate in WordPress requests, doing expensive work at file load or enqueueing every asset globally adds work where the feature is not used.

What Plugin Execution Means for Security, Performance, and Compatibility

WordPress runs active plugins as PHP code while handling site requests. Their callbacks can change responses, read or write site data, and affect behavior that other plugins also change. WordPress connects that code through shared hooks, so plugin quality and compatibility influence how reliably the site handles requests.

For security, plugins should validate submitted data against expected rules, sanitize it into a suitable form, and escape it for the context where it appears, such as HTML or an attribute. A capability check confirms that the current user has permission to perform an action. A nonce is a token WordPress uses to help verify that a request was made for the intended action; it does not grant permission, so it does not replace a capability check. Plugins should use WordPress database APIs and prepared queries when working with stored data, rather than inserting untrusted values directly into SQL. WordPress documents these safeguards in its guidance on plugin security and user capabilities.

A plugin’s performance depends on what its code does and when it runs. If a hook fires on every request, WordPress runs its attached callback on every request. Repeated expensive database queries or other unnecessary work on those hooks add cost to page requests. When inspecting a plugin, look for callbacks on broad, frequently triggered hooks and check whether they repeat database work that could run only in a narrower context. WordPress runs callbacks according to hook priority and registration order, as described in its documentation on actions and callback order.

Plugins can conflict when they share hooks, depend on a particular load order, or rely on behavior that changes in a WordPress or PHP release. Two callbacks that modify the same value can produce different results depending on their priority; callbacks at the same priority run in registration order. Before updating WordPress, PHP, or a plugin, check the plugin’s stated requirements and test the change in a nonproduction environment. The plugin basics documentation describes plugin metadata, including minimum version requirements.

What I'm building

Delegate tasks. Get software.

Give Vroni a GitHub issue, bug report, spec, or rough idea. It reads the repo, plans the change, writes code, runs checks, and works toward a review-ready pull request.

Take a look at vroni.com