Architecture

On an installation with WooCommerce active, the extra WordPress objects can be listed with WP-CLI. The lab runs WP-CLI in a throw-away Docker container attached to the WordPress container; the commands below drop that wrapper, and the output is what the 11.2.1 store printed.

Source: WordPress developer resources: wp post-type list

The post-type and taxonomy listings are filtered by grep to the WooCommerce entries (the rest belong to WordPress itself), and the two pa_* taxonomies at the end are global attributes that other examples of this section created on the lab store. The output shows the WordPress side of the WooCommerce data model:

Source: WooCommerce docs: Data storage

The REST namespaces and the table list can be checked in a minute against any store:

Source: WordPress developer resources: REST API handbook

ec-hello/v1 is the route of a smoke-test plugin on the lab store; wp-abilities/v1 and mcp come from the WordPress Abilities API and the MCP Adapter plugin, which the AI page covers.

WooCommerce replaces very little of WordPress; it reuses it. The WordPress plugin loader includes the main file. The WordPress hook system, described on the next page, is the only extension mechanism, so a WooCommerce callback and a callback of the merchant’s own plugin sit in the same priority list. The template loader decides which file renders a request: for a classic theme WooCommerce filters template_include and loads a template from the templates/ directory unless the theme overrides it, and for a block theme the Site Editor templates are used and WooCommerce contributes block templates and patterns. The REST server serves wc/v3 and wc/store/v1 like any other namespace. Users, roles and capabilities come from WordPress: a WooCommerce customer is a WordPress user with the customer role, and a guest has no user at all (the cart of a guest is a session row identified by a cookie, see below). Cron is WordPress cron, with Action Scheduler layered on top for work that must survive and be retried.

The two places where WooCommerce deliberately steps beside WordPress are storage and the shopper’s state. Orders can leave wp_posts entirely (HPOS), and the cart and the customer of a visitor live in a WooCommerce-owned session table and cookie (the table wp_woocommerce_sessions and the cookie wp_woocommerce_session_<hash>; for a logged-in user the session is keyed by the user ID, which the lab confirmed: a WP-CLI process run as user 1 shows a session handler whose customer ID is 1). The cart is also the object WordPress knows least about: it is loaded only on requests that need it, as the next listing shows.

Source: WooCommerce source: includes/class-woocommerce.php

The same command without the --exec argument prints WC_Cart, WC_Session_Handler and WC_Customer, because a WP-CLI process is not an admin request. The rule is in WooCommerce::init(): wc_load_cart() runs only for a "frontend" request, which the class defines as not admin (or an AJAX call), not cron and not REST. It matters for any code that runs from an admin screen or a scheduled action: WC()->cart is null there, and calling wc_load_cart() first is the documented workaround.

The two code directories are two eras of the same plugin, and the difference decides how a class is found, built and supported.

Source: WooCommerce source: src directory

The src/ directory has these top-level folders: Abilities, Admin, Blocks, Caches, Caching, Checkout, Database, Enums, Gateways, Internal, LayoutTemplates, Proxies, StoreApi and Utilities, plus Container.php, Packages.php, Autoloader.php and Deprecated.php. The folder names show how the plugin absorbed its former feature plugins: src/Blocks holds what used to be the standalone WooCommerce Blocks plugin (148 entries in Blocks/BlockTypes), src/StoreApi the Store API (40 files in Routes/V1) and src/Admin what was the WooCommerce Admin plugin.

The rule of Internal deserves emphasis because it decides whether an extension survives updates. The namespace Automattic\WooCommerce\Internal (59 entries in 11.2.1) holds implementation classes that the source marks @internal: WooCommerce may rename, move or delete them in any release, and the backward-compatibility promise of the plugin does not cover them. FeaturesController, CustomOrdersTableController and the abstractions of HPOS live there, and so do most of the classes the container builds at boot. When an official recipe has to use one, it guards it, as the HPOS recipe book does with class_exists() before it asks the container for the CustomOrdersTableController. The public helpers sit one level up: Automattic\WooCommerce\Utilities\FeaturesUtil, OrderUtil, PluginUtil, the enums in Enums (OrderStatus, ProductType and the others), and the extension points of the Store API and the blocks.

The flowchart condenses the decision. Its first question is the one that matters in practice: is the class meant for you?

Source: WooCommerce docs: HPOS recipe book

Three class loaders cooperate, and knowing them explains two classes of errors: a "class not found" for a WC_ class that has been moved, and a fatal error during an in-place update.

The page on extension development shows how a plugin of your own should use Composer; for the PHP basics see namespaces and autoloading and Composer and packages.

The main file does five things before any hook has fired, and it is short enough to read in a minute:

WC() calls WooCommerce::instance(), which constructs the object once. The constructor defines the constants (WC_ABSPATH, WC_VERSION, WC_ROUNDING_PRECISION and about a dozen more), registers the extra tables in the $wpdb object so that $wpdb->order_itemmeta and $wpdb->wc_product_meta_lookup exist, calls includes() and finally init_hooks(). includes() loads about a hundred files; which ones depends on the request:

Source: WooCommerce source: woocommerce.php

The last row is a useful reminder of how old the plugin is: it carries layout fixes for themes that WordPress released between 2010 and 2023. The init_hooks() method is where the process becomes WooCommerce. It registers the activation hook (WC_Install::install), a shutdown function that logs fatal errors, some thirty hooks of its own, and then asks the container for roughly sixty-five service classes: thirty-three are only fetched, because their constructor or init() attaches hooks, and thirty-two more are fetched and told to register().

The next example is the plugin pocket-coffee-architecture. Its main file hooks seven moments of the boot at priority -10000, which is earlier than anything WooCommerce registers, and records for each whether the WooCommerce class and the function WC() exist. Its only other jobs are to declare compatibility with two WooCommerce features, which the feature-flag section explains, and to add a WP-CLI command that prints the log.

Source: WooCommerce docs: Building your first extension

The class that keeps the log is in includes/class-boot-log.php. The file name matters: the WordPress coding standard expects a class file to be called class-<name>.php, and it also expects a file to contain either functions or classes, not both. The first version of this plugin kept the class in the main file, and PHP_CodeSniffer reported both rules, which is why the class has its own file.

Source: WordPress developer resources: Plugin header requirements

Activating the plugin and running the command prints the boot of a real request:

The first line is the lesson of the page. WordPress includes active plugins in the order of their folder names, and pocket-coffee-architecture sorts before woocommerce, so when this file runs the WooCommerce class does not exist yet. Any code that runs at include time and calls WC(), wc_get_order() or FeaturesUtil fatals or silently does nothing, depending on whether the call is guarded. That is the reason every extension waits for a WooCommerce hook; the header line Requires Plugins: woocommerce makes WordPress refuse to activate the plugin without WooCommerce but does not change the load order. The six later lines show that the order of the hooks is the order of the figure:

The callbacks behind each step can be listed from the global $wp_filter, the array that stores every hook. The priorities in the figure come from this script, which prints the callbacks WooCommerce attached to the hooks of the boot; the lab shows only the lines that belong to WooCommerce and to the example plugin.

Source: WordPress developer resources: WP_Hook

The output is an excerpt of the real listing, which has about sixty entries on init alone (the Closures of the example plugin and of other plugins on the lab store are omitted). The important entries are WooCommerce::on_plugins_loaded at priority -1, which fires woocommerce_loaded after every other plugin has been included (the code comment explains the reason: the plugin directory name changes the load order, and woocommerce_loaded makes the signal independent of it), and WooCommerce::init at init priority 0, which is the method that makes the WooCommerce objects exist.

WooCommerce::init() runs these steps in order, and each is a place an extension can hook:

The pair of actions before_woocommerce_init and woocommerce_init is the one to remember. Declaring compatibility belongs to the first, and code that needs the product factory, the order factory or the cart belongs to the second or later. The woocommerce_loaded action is the right place to check that WooCommerce is present and to create your own plugin’s objects; it is early enough for classes and functions but too early for the factories.

One more property of the bootstrap shapes extension code: the same files serve every kind of request, so a hook callback must check what kind of request it is in. WooCommerce::is_request() is private, but WordPress and WooCommerce expose enough to ask the same questions: is_admin(), wp_doing_ajax(), wp_doing_cron(), wp_is_serving_rest_request() and defined( 'WP_CLI' ). WooCommerce’s own check for a REST request sniffs the request URI (the wp-json prefix or a rest_route parameter), because core’s REST_REQUEST constant is defined only after parse_request, long after the plugin has to decide what to load; the filter woocommerce_is_rest_api_request lets a site with an unusual REST path correct the answer, and the source comment tells code that runs after parse_request to prefer wp_is_serving_rest_request(). The Store API request of the Checkout block is a REST request and is not an admin request, so code guarded with is_admin() is skipped there, which is correct for admin-only features and wrong for anything that should run during checkout.

Two patterns recur in init_hooks(). A service whose constructor or init() attaches hooks is simply fetched ($container->get( OrderCountCacheService::class )), which is why the bootstrap list looks like a list of unused values. A service that implements RegisterHooksInterface (since 8.5.0; 25 classes in 11.2.1) has a register() method and is fetched and registered explicitly, so that the construction of an object and the attachment of its hooks are separate steps. Extensions are free to copy the second pattern, because it keeps constructors free of side effects and makes the class testable without WordPress: construct the object, then call register() from woocommerce_loaded. The plugin used on the hooks page does exactly that.

A consequence for debugging: the hook callbacks of WooCommerce are methods of container objects, so to remove one with remove_action() you must hold the same object, which the container gives you (wc_get_container()->get( Class::class )) at the cost of depending on an Internal class. The hooks page shows the safer alternatives.

Asking the controller for every feature, including the experimental ones, prints the list of the installation:

Source: WooCommerce docs: High-Performance Order Storage

The list has 32 entries on 11.2.1. The enabled column is the state of this store on the day of the run (several of the values, such as fulfillments and email_improvements, are rollout flags that differ from store to store and from day to day), not a default. Reading the list requires four distinctions:

A second, older family of flags was retired in 11.1.0. The WooCommerce Admin features (analytics, coupons, onboarding, homescreen, marketing, core-profiler, launch-your-store and about twenty more) used to be queried with Features::is_enabled() and toggled with Features::enable() and Features::disable(). In 11.1.0 enable() and disable() were deprecated, and the legacy slugs became a compatibility shim that always answers true (analytics and remote inbox notifications still read their options); calling Features::is_enabled( 'analytics' ) now logs a deprecation notice that says the shim "will be removed in" a later version. Code written for the old API, and any plugin that checks one of those slugs, should stop checking the flag and rely on the feature itself. The woocommerce_admin_features filter, which used to let a site drop admin features, still runs for the shim and carries a @since 11.1.0 note.

A feature is defined by FeaturesController::add_feature_definition( $slug, $name, $args ). The arguments are the interface between the feature and the Features screen, and they are worth knowing when you read the settings page or the source:

Source: WooCommerce source: FeaturesController.php

Each value may also be a callback that returns the value, which is how the descriptions are translated lazily. The definitions themselves are in the source of the controller and of two controllers that add their own (HPOS and cost of goods sold), added inside get_feature_definitions() to avoid circular container lookups. Third-party code cannot register a feature: the older action woocommerce_register_feature_definitions (8.3.0) was deprecated in 9.9.0 in favour of definitions inside the controller, and the source comment says the action should only be used for testing. The extension point that is public is the other half of the system.

A plugin that touches orders, checkout or the product editor declares what it supports, with FeaturesUtil::declare_compatibility() during before_woocommerce_init. The first declaration of the example plugin, HPOS, is the one the Marketplace requires of every new submission; the second states that the plugin works with the Cart and Checkout blocks. The call is idempotent for the same value, throws an Exception when a plugin declares the same feature both compatible and incompatible, returns false for an unknown feature, and accepts either the full path of the plugin file (__FILE__) or the directory/file.php form.

The sequence diagram follows one declaration from the plugin to the Plugins screen:

Source: WooCommerce docs: High-Performance Order Storage

The queued declaration is normalised lazily: the first query of the compatibility information resolves plugin files to plugin IDs and logs an error for a file that WordPress does not know. The result for the example plugin, and the proof that a late call fails:

Source: WooCommerce docs: High-Performance Order Storage

Run with WP_DEBUG on, the late call also prints Function FeaturesController::declare_compatibility was called incorrectly. FeaturesController::declare_compatibility should be called inside the before_woocommerce_init action, a message added in WooCommerce 7.0. The 30 "uncertain" features are those the plugin said nothing about; what WooCommerce does with them depends on the default_plugin_compatibility of each definition. On the merchant’s side, the controller adds plugin-row warnings on the Plugins screen, filters the plugin list by feature (the views_plugins filter), and can stop a plugin that is incompatible with an enabled feature from being activated from the Plugins screen; FeaturesUtil::allow_enabling_features_with_incompatible_plugins() and allow_activating_plugins_with_incompatible_features() are the escape hatches for test setups.

The command wp wc hpos compatibility-info prints the same information from the HPOS side. On the lab store it listed the example plugin among the compatible ones.

The feature system answers "may the merchant turn this part of WooCommerce on". It is the wrong tool for an extension’s own switches. WooCommerce’s own contribution guide asks contributors not to use filters as feature flags and to prefer an option, because options persist in the database and are already filterable; an extension should follow the same rule and store its switches in options registered on its settings page, as the settings page shows. What an extension does take from the system is the read side: if a behaviour depends on HPOS, ask OrderUtil::custom_orders_table_usage_is_enabled() (a public helper) instead of reading the option; if it depends on the Checkout block, test the page content rather than the cart_checkout_blocks value, for the reason in the previous subsection.