Lesson 2.3. Extension Plugin

Monday, 9:40 AM

The client deactivated WooCommerce "to test speed". The site is a white screen. So is the admin.

Your plugin calls WC() right in the main file. Without WooCommerce that function doesn't exist, and PHP dies before WordPress can show anything.

Goal

After the lesson you build an extension skeleton that doesn't crash without WooCommerce, declares compatibility and passes the WooCommerce → Features check.

Key concepts

  • The Requires Plugins: woocommerce header (WordPress 6.5+) — a dependency enforced by core
  • WC requires at least and WC tested up to — WooCommerce versions in the header
  • Declaring compatibility on before_woocommerce_init: custom_order_tables, cart_checkout_blocks
  • Start the logic on woocommerce_loaded, or on plugins_loaded with a WooCommerce class check
  • Namespaces, Composer autoload, no logic in the main file

Diagram

sequenceDiagram
  participant WP as WordPress
  participant P as Your plugin
  participant WC as WooCommerce
  WP->>P: load my-plugin.php
  WC->>P: before_woocommerce_init
  P->>WC: declare_compatibility(HPOS, blocks)
  WC->>P: woocommerce_loaded
  P->>P: Plugin::init() — hooks, services

Code

my-wc-extension.php:

PHP
<?php
/**
 * Plugin Name:       My WC Extension
 * Description:       An example WooCommerce extension.
 * Version:           1.0.0
 * Requires at least: 6.5
 * Requires PHP:      8.1
 * Requires Plugins:  woocommerce
 * WC requires at least: 9.0
 * WC tested up to:   10.3
 * Text Domain:       my-wc-extension
 */

defined( 'ABSPATH' ) || exit;

require __DIR__ . '/vendor/autoload.php';

add_action( 'before_woocommerce_init', static function () {
	if ( class_exists( \Automattic\WooCommerce\Utilities\FeaturesUtil::class ) ) {
		\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'custom_order_tables', __FILE__, true );
		\Automattic\WooCommerce\Utilities\FeaturesUtil::declare_compatibility( 'cart_checkout_blocks', __FILE__, true );
	}
} );

add_action( 'woocommerce_loaded', static function () {
	( new \MyWcExtension\Plugin() )->init();
} );

src/Plugin.php:

PHP
<?php
namespace MyWcExtension;

final class Plugin {
	public function init(): void {
		( new Admin\ProductFields() )->register();
		( new Checkout\Fees() )->register();
	}
}

Common mistakes

SymptomCauseFix
Fatal error when WooCommerce is offWooCommerce classes called in the main fileLogic only after woocommerce_loaded
A block checkout incompatibility warningNo cart_checkout_blocksTest with blocks and declare it
The plugin's hooks never fireRegistered after the hook already ranRegister on woocommerce_loaded / init

Weak and strong answer

Question: How do you make sure a plugin won't crash without WooCommerce?

Weak answer. Check class_exists( 'WooCommerce' ).

Strong answer. Since WordPress 6.5 — the Requires Plugins: woocommerce header, so core won't activate the plugin without its dependency. In code the logic starts on woocommerce_loaded, so without WooCommerce it simply never runs. I keep class_exists only for code that runs earlier.

Why the second is stronger: The candidate knows the modern dependency mechanism and explains the load order.

Practice

The skeleton takes four commands — run them in your own project:

BASH
wp scaffold plugin my-wc-extension
cd wp-content/plugins/my-wc-extension
composer init --name=me/my-wc-extension --autoload=src/
composer dump-autoload

Then rewrite the main plugin file from the start of the lesson in the IDE below: WooCommerce headers, compatibility declarations, start on woocommerce_loaded. Verify it with Run.

TEXT

Interview Questions

A plugin header since WordPress 6.5. Core won't activate the plugin until its dependencies are active, and won't deactivate a dependency while a dependent plugin is active.

WooCommerce shows a warning in the plugin list if the WooCommerce version is newer than the tested one. It's a signal for the admin before updating.

before_woocommerce_init: WooCommerce collects declarations before it initializes features. A later declaration is ignored.

Save your progress

Sign in or create a free account to mark lessons as completed and continue the whole course. You will come back to this lesson.