Skip to content
Tutorials Center
My learning

Topics

Lesson 1 of 39 ยท Getting Started

How WooCommerce Is Built

See how WooCommerce sits on top of WordPress: post types, HPOS tables, the WC() singleton, template and hook layers, and what to extend instead of edit.

WooCommerce is a WordPress plugin, and that single fact explains most of its design. It does not run its own web server, router or user system. It borrows WordPress's request lifecycle, users, options, post types, taxonomies, REST API and hook system, and adds a shop on top: products, a cart, checkout, orders, payment gateways, shipping, taxes and emails.

Before you write extension code you need a mental map of the layers, because every good WooCommerce extension plugs into the right layer and every fragile one reaches into the wrong layer. This lesson gives you that map. It builds on WooCommerce Basics and Plugin Structure and Object-Oriented Plugins, so skim those first if the words "hook" or "autoloader" are new.

WooCommerce needs WordPress and MySQL, so it cannot run on this site. All real WooCommerce code in this track is read-only. The runnable examples are plain-PHP stand-ins that copy an idea (here: a service container and a lazy singleton). They are not WooCommerce code, and the real classes do far more.

The layers at a glance

Read the stack from the bottom. Each layer only talks to the one below it.

flowchart TD
    A["Your extension plugin"] --> B["Hooks and filters<br/>(actions, filters, templates)"]
    B --> C["WooCommerce domain layer<br/>(CRUD classes, cart, checkout, gateways)"]
    C --> D["Data stores<br/>(products, orders, sessions)"]
    D --> E["WordPress core<br/>(posts, meta, options, users)"]
    D --> F["WooCommerce tables<br/>(HPOS orders, lookup tables, sessions)"]
    E --> G[("MySQL")]
    F --> G

Your code should touch the hook and domain layers, never the tables underneath them.

The sections below walk through each layer from the top.

The WC() singleton

The main plugin class is named WooCommerce, and a global function WC() returns its single instance. Through that instance you reach the long-lived services of the current request:

PHP
<?php
// Read-only: typical access to shared services (inside a WooCommerce request).
$cart     = WC()->cart;                 // WC_Cart, may be null in admin or CLI contexts
$session  = WC()->session;              // session handler
$customer = WC()->customer;             // WC_Customer for the current visitor
$gateways = WC()->payment_gateways();   // registered payment gateways
$mailer   = WC()->mailer();             // email manager
$countries = WC()->countries;           // countries, states and address formats

Two practical rules follow from this:

  • Some members are not always set up. The cart, session and customer are initialized for front-end requests. In wp-admin screens, REST calls, WP-CLI and cron they may be null unless you load them first. Always check before use (if ( WC()->cart )).
  • WC() is a service locator: convenient, but hiding dependencies. In your own classes, pass what you need into the constructor so you can test them without a running shop.

Newer WooCommerce versions also use an internal dependency-injection container for their own classes. Those classes live under Automattic\WooCommerce\Internal and are explicitly not public API: their names and signatures can change in any release. Extension code should rely on the public functions, classes and hooks that the developer documentation names.

Data: posts, tables and CRUD classes

WooCommerce storage has two generations, and mixing them up is the most common source of bugs.

Data Where it lives
Products and variations WordPress posts (post types product and product_variation), post meta, taxonomies, plus a lookup table for fast price and stock queries
Orders (modern stores) Dedicated tables: HPOS, High-Performance Order Storage (wc_orders and companion tables)
Orders (older stores, or compatibility mode) Posts of type shop_order and post meta
Customers WordPress users, plus a lookup table
Settings WordPress options
Carts and sessions A sessions table and cookies

Because the same logical thing (an order) can live in two places, WooCommerce hides the storage behind CRUD classes such as WC_Product and WC_Order. You call $product->get_price() or $order->get_total(), and a data store decides which table or meta key to read. The next chapters cover this in CRUD Classes and Data Stores and Orders and High-Performance Order Storage.

The rule that saves you the most pain: never read or write WooCommerce data with get_post_meta(), update_post_meta() or raw SQL when a CRUD method exists. On an HPOS store, order data is not in post meta at all, so your code silently reads nothing.

PHP
<?php
// Read-only: the safe way to read an order, on any storage mode.
$order = wc_get_order( $order_id );
if ( $order instanceof WC_Order ) {
    $total  = $order->get_total();
    $status = $order->get_status();
    $note   = $order->get_meta( '_my_plugin_note' );   // not get_post_meta()
}

The hook layer

Almost every behavior in WooCommerce is surrounded by actions and filters. There are hundreds, and they follow a woocommerce_ naming scheme: woocommerce_before_single_product, woocommerce_add_to_cart, woocommerce_order_status_completed, woocommerce_checkout_fields. Templates call do_action() at fixed points, and domain classes call apply_filters() before returning values such as prices.

Hooks are the supported extension surface. They are documented, versioned and kept stable across releases (a hook that is removed goes through a deprecation period first). The hook map lesson shows how to find the right one quickly.

The template layer

Front-end HTML comes from PHP template files in the plugin's templates/ folder. A theme can override any of them by copying the file to your-theme/woocommerce/ with the same relative path. Plugins can ship their own templates and let themes override those too. Template Overrides and Plugin Templates explains the lookup order.

Modern stores may also use block-based cart, checkout and product pages. Those are rendered with JavaScript blocks and the Store API, so some classic PHP template hooks do not fire there. You will meet this in Cart and Checkout Blocks Extensibility.

What to extend and what never to edit

Do Do not
Add behavior with actions and filters from your own plugin Edit files inside wp-content/plugins/woocommerce/ (updates erase them)
Override templates in the theme, or ship plugin templates Copy whole core classes into your plugin
Read and write through CRUD classes (wc_get_product, wc_get_order) Query wp_postmeta or wp_wc_orders directly for business data
Subclass the documented base classes (WC_Payment_Gateway, WC_Shipping_Method, WC_Email) Call Internal classes or underscore-prefixed private methods
Store your own data under a unique prefix Reuse WooCommerce meta keys for your own meaning

A stand-in service container

Real WooCommerce lazily builds many services. This first stand-in shows the core idea of a tiny container: you register factories, and each service is built once, the first time somebody asks for it. It also detects a circular dependency, which is the classic way containers fail.

PHP A tiny lazy service container

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

Notice that nothing is built until cart is requested, and that asking twice returns the same object. That is exactly why WC()->cart can be a shared object for the whole request.

A stand-in for the WC() accessor

WC() is a global function wrapping a singleton. Real WooCommerce adds members as the request progresses (the cart appears only for front-end requests). The second stand-in mimics that with a magic getter, and shows why code must check for null.

PHP A WC()-style singleton with late members

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with fgets(STDIN)), it gets the next line from this box.

The real WC() is more elaborate, but the lesson holds: check what is available in the current context before you use it.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What does WC() return?

    WC() is a global accessor for the one WooCommerce instance, through which you reach services such as the cart, session and payment gateways.
  2. 2. Why should you avoid get_post_meta() for order data?

    With High-Performance Order Storage, orders live in dedicated tables. The CRUD methods on WC_Order read from whichever storage is active.
  3. 3. Which of these is a supported way to change checkout behavior?

    Hooks are the stable extension surface. Edits inside the plugin are erased by updates, and Internal classes can change at any time.
  4. 4. Why check if ( WC()->cart ) before using the cart?

    The cart, session and customer are set up for front-end requests, so other contexts may not have them unless you load them.

Summary

  • WooCommerce is a WordPress plugin: it reuses posts, users, options, hooks and the REST API.
  • WC() returns the shared main instance; some members (cart, session) exist only in certain request contexts.
  • Products are posts plus lookup tables; modern orders use HPOS tables. Always go through CRUD classes, never raw meta or SQL.
  • Hooks and template overrides are the supported extension points; core files and Internal classes are not.
  • Pass dependencies into your own classes instead of calling WC() everywhere; a container or factory keeps them testable.

Next: Development Environment and Tooling