Extension Development

An extension is a directory in wp-content/plugins/ (or a single PHP file there) whose main file starts with a header comment. The directory name is the plugin slug, and by convention the main file has the same name plus .php: pocket-coffee-extension/pocket-coffee-extension.php. WordPress identifies the plugin by that relative path, which is why wp plugin activate pocket-coffee-extension and the active_plugins option use it.

A plugin passes through four states, and each has its own place for code:

Other places can hold WooCommerce code (the theme’s functions.php, a must-use plugin in wp-content/mu-plugins/, a code-snippets plugin), but a theme’s code disappears when the theme changes, and must-use plugins have no activation, no dependency check and no uninstall. Anything a merchant should be able to switch off, update or remove belongs in a regular plugin. The official guidance adds that an extension should have a single core purpose, use WooCommerce features as much as possible and not advertise inside the merchant’s admin; the checklist at the end collects the rules.

The layout of the example, with the purpose of each file:

Source: WooCommerce developer docs: Extension development best practices

Source: WordPress Plugin Handbook: Plugin basics

The header is a PHP comment in the first 8 KB of the main file (WordPress reads exactly that much with file_get_contents( $file, false, null, 0, 8 * KB_IN_BYTES )), one Field: value pair per line. Only Plugin Name is required. The example uses this one:

get_plugin_data() shows which of these fields the installed software understands. On the test site:

The three WooCommerce fields are keys of the array only because WooCommerce is active and added them in wc_enable_wc_plugin_headers(); without WooCommerce, get_plugin_data() does not return them. The empty Woo value is expected for an extension that is not sold on woocommerce.com.

Source: WooCommerce developer docs: Plugin header comments

Source: WordPress Plugin Handbook: Header requirements

The Requires Plugins header keeps an administrator from activating the extension without WooCommerce, but it is not a substitute for a runtime check: WP-CLI and file-system changes can still produce the state "extension active, WooCommerce missing", the header has no version constraint, and WordPress does not guarantee the order in which active plugins are loaded. A defensive extension has three layers, from the weakest to the strongest guarantee:

@woocommerce/create-woo-extension is a template for @wordpress/create-block, the WordPress tool that generates plugins and blocks. It generates a plugin with a React admin page that is registered in the WooCommerce admin (wc-admin), PHP and JavaScript unit-test setup, linting and Prettier configuration, a wp-env configuration and a build based on @wordpress/scripts with the WooCommerce dependency-extraction plugin. The generator needs Node.js with npm, Composer, and Docker if the bundled wp-env environment is used; the Docker part is described in Installation and Local Environments and Docker getting started on this site.

Source: WooCommerce developer docs: How to build your first extension

What was and was not run. The generator was not run for this page: running it executes a package downloaded from the npm registry together with a build toolchain, which the environment where the page was written did not allow. Everything in this section comes from the template sources in the WooCommerce repository (packages/js/create-woo-extension on the trunk branch, read on 2026-10-27), the package metadata on the npm registry (version 2.1.0 published 2026-10-21) and the developer documentation. The trunk sources may differ slightly from the published tarball, so treat the file lists below as indicative and compare them with the output of your own run.

Variants. The template accepts --variant=<name>: add-report (a new report under Analytics), dashboard-section (a section in the Analytics overview), sql-modification (a filter that changes the SQL of the Products report), table-column (extra columns in the Products report) and add-task (a task in the onboarding task list). Without a variant the extension adds an example page to the WooCommerce admin that shows components from @woocommerce/components.

Files generated by the default variant (the template folder lists these; create-block adds package.json, and npm install and npm run build add node_modules/ and build/):

Two points deserve a second look in the scaffold. First, its WooCommerce check is the older activation-hook-plus-plugins_loaded pattern shown above and does not add Requires Plugins; add the header yourself. Second, the template header has no WC requires at least or WC tested up to; add them (L-1 values above) and the compatibility declarations of the next section. The tooling versions on 2026-10-27 were @woocommerce/create-woo-extension 2.1.0, @wordpress/env 12.0.0 and @wordpress/scripts 37.0.0 (npm latest).

Other scaffolds: @woocommerce/extend-cart-checkout-block (a create-block template with several examples of extending the block checkout, covered in Cart and Checkout Blocks), and the example extensions inside the WooCommerce repository. The example in this page is a plain PHP plugin because it needs no JavaScript build.

Source: WooCommerce developer docs: Scaffolding and sample store data

Source: GitHub: create-woo-extension template

The three files below are the complete extension. The main file does only what has to happen before WooCommerce is ready or when it is missing; the class holds the behaviour.

WooCommerce lets a plugin say that it has been tested with a feature, or that it knows it does not work with it. The feature registry in 11.2.1 contains these IDs (FeaturesUtil::get_features()): analytics, cart_checkout_blocks, rate_limit_checkout, marketplace, order_withdrawal, order_attribution, site_visibility_badge, hpos_datastore_caching, remote_logging, deferred_transactional_emails, customer_review_request, email_improvements, blueprint, variation_gallery, point_of_sale, fulfillments, push_notifications, custom_order_tables and cost_of_goods_sold, plus experimental ones such as mcp_integration and rest_api_caching (listed with get_features( true )). Two matter for nearly every extension:

The declaration is code in the main file:

Source: WooCommerce developer docs: Compatibility and interoperability

Rules, from the source of FeaturesUtil and the tests on the test site:

Source: WooCommerce developer docs: HPOS recipe book (declaring compatibility)

Source: WooCommerce developer docs: Compatibility and interoperability for extensions

Activation hook. register_activation_hook( __FILE__, $callback ) runs once, in the request that activates the plugin, after the plugin file has been included. Use it for one-time setup: default options, a first scheduled action, creating a table with dbDelta() if there is really no alternative. It does not run when the plugin is updated, when WP-CLI or an auto-update replaces the files, or on a multisite network activation for every site, so it is the wrong place for data migrations and the wrong place to check for WooCommerce (the activation request has WooCommerce loaded only if it sorts earlier). The example stores its version with add_option() and nothing else.

Upgrades. Plugins are updated by replacing files, so the code must discover that data written by an older release needs changing. The example keeps the installed version in the option pocket_coffee_extension_version and compares it with the constant on init:

Keep each migration idempotent. A migration that touches thousands of rows must not run in one request: queue it as a background job (see Action Scheduler). WooCommerce itself uses the same pattern with its woocommerce_db_version option and queued update callbacks.

Where to store what. The WooCommerce data-storage primer gives the rule of thumb: expiring data in a transient; persistent data that may be absent in the object cache (wp_cache_*); persistent, always-needed settings in an option; an entity with many units in a post type; a way of grouping entities in a taxonomy; debugging output in a log written with WC_Logger. Avoid custom database tables when one of these fits; the Marketplace guidelines say so explicitly. Products, orders, customers and coupons are read and written through their CRUD classes ($product->get_meta(), $order->update_meta_data() and save()), which respect the data store in use, including HPOS, caches and the hooks other plugins listen to.

Security of what is stored and printed. Validate and sanitize input when it arrives (sanitize_text_field( wp_unslash( ... ) ) and the regular expression in save_roast_date()), escape when it leaves (esc_html(), esc_attr(), esc_url(), wp_kses_post()), use nonces for requests the plugin handles itself and capability checks for anything that changes data. The product editor’s own nonce and capability check cover the save action used in the example; a custom AJAX handler or REST route would need its own. The WordPress security documentation is the reference.

Source: WordPress Plugin Handbook: Activation and deactivation hooks

Source: WordPress APIs: Security

The text domain is the plugin slug, pocket-coffee-extension; the header’s Domain Path: /languages tells WordPress where the files are. Every user-facing string goes through __(), esc_html__() or the other i18n functions with a literal string and the domain (the tools that extract strings read the source, they do not run it), placeholders are numbered or commented with a /* translators: */ comment, and the strings are written in English, the WordPress default; extra languages ship as translation files or come from translate.wordpress.org for plugins hosted on WordPress.org. The example loads its files on init with load_plugin_textdomain(). WordPress 6.7 and later can report a translation requested before init with a notice (_load_textdomain_just_in_time was called incorrectly), so keep calls to the translation functions out of the main file’s top level and out of class constants.

WP-CLI generated the template, and a Spanish file made the strings translatable. The Pocket Coffee shop’s default language is Spanish, and the extension’s three strings were translated:

The .po file was pocket-coffee-extension-es_ES.po with three msgid/msgstr pairs. The .pot also lists the plugin header fields (name, description, author) as translatable strings. See Taxes, Coupons, Currencies and i18n for store-level multilingual setup.

Source: WordPress developer note: i18n improvements in 6.7

Source: WordPress Plugin Handbook: Internationalization

Three different operations are easy to confuse:

uninstall.php is preferred over register_uninstall_hook() because the file is not loaded on normal requests and WordPress defines WP_UNINSTALL_PLUGIN before running it; the guard defined( 'WP_UNINSTALL_PLUGIN' ) || exit; stops anyone from requesting the file directly. WordPress does not load the plugin’s own code during the uninstall, so the file may not call its classes or constants.

What the example’s uninstall.php removes, and what it keeps:

Test run on the shop, with a product that had a roast date and an order that the plugin had logged (order 405):

Design decisions in the file:

Source: WordPress Plugin Handbook: Uninstall methods

Coding standard. PHP_CodeSniffer with the Woo and WordPress rule sets is the baseline. The standards on the test site came from woocommerce/woocommerce-sniffs 2.0.0, wp-coding-standards/wpcs 3.4.1 and phpcompatibility/phpcompatibility-wp 2.1.8 on PHP_CodeSniffer 3.13.6. The extension passed both checks:

On PHP 8.3 the WooCommerce-Core standard needs --runtime-set testVersion 7.4-; without it the PHPCompatibility sniff aborts with a trim() deprecation. The testVersion also tells the compatibility sniffs which PHP floor to enforce, which should match Requires PHP. To show that the standard is active, this throw-away plugin was checked (an unsanitized superglobal, interpolated SQL, unescaped output, a missing nonce, and an order read as a post):

The last two lines of the snippet, get_post( 12 ) and update_post_meta() on something that is an order, were not reported: PHPCS cannot know that ID 12 is an order. The HPOS rules are about meaning, not syntax, so the compatibility declaration needs a review of every place where the plugin touches orders, plus a test with HPOS enabled and with it disabled.

Other tools. php -l for syntax, PHPUnit for units (the generator ships a tests/ folder and the WooCommerce repository documents a wp-env based setup), Playwright for end-to-end tests (WooCommerce publishes @woocommerce/e2e-utils-playwright, 0.5.1 on 2026-10-27) and the Woo Quality Insights Toolkit (QIT), which runs the Marketplace’s managed tests (API, end-to-end, activation, security, PHP compatibility, malware and validation) against a release candidate. The managed tests need a woo.com account and were not run; the process is on Testing, Deployment and Marketplace, and the PHPUnit side is introduced in Testing with PHPUnit and Pest. Turn on WP_DEBUG and WP_DEBUG_LOG while developing, because WooCommerce reports misuse of its own APIs with wc_doing_it_wrong(), and test with the plugin active together with a few other popular plugins and with both a block theme and a classic theme.

Source: WooCommerce developer docs: Security best practices

Source: WooCommerce developer docs: Testing

The official extension guidelines, with the points verified above in bold:

The Marketplace review adds a business review (revenue share, naming, pricing), UX review and the QIT tests; see the Marketplace page of this subsection.

Source: WooCommerce developer docs: Extension development best practices

Source: WooCommerce developer docs: Submitting your product to the Woo Marketplace