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: woocommerceheader (WordPress 6.5+) — a dependency enforced by core WC requires at leastandWC 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 onplugins_loadedwith aWooCommerceclass 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
/**
* 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
namespace MyWcExtension;
final class Plugin {
public function init(): void {
( new Admin\ProductFields() )->register();
( new Checkout\Fees() )->register();
}
}
Common mistakes
| Symptom | Cause | Fix |
|---|---|---|
| Fatal error when WooCommerce is off | WooCommerce classes called in the main file | Logic only after woocommerce_loaded |
| A block checkout incompatibility warning | No cart_checkout_blocks | Test with blocks and declare it |
| The plugin's hooks never fire | Registered after the hook already ran | Register 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: woocommerceheader, so core won't activate the plugin without its dependency. In code the logic starts onwoocommerce_loaded, so without WooCommerce it simply never runs. I keepclass_existsonly 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:
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.
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.