WooCommerce is a plugin with a large and complicated codebase.
If you’re a developer, understanding the underlying code in detail is hugely beneficial, and will almost certainly pay dividends in the long term.
If you can write a bit of PHP (most of Business Bloomer is made of PHP Snippets), you definitely need to search the core every now and then. Otherwise, Stackoverflow won’t be sufficient on its own.
If you happened to see and use the WooCommerce Visual Hook Guides such as the one for the Single Product Page, well, those are simply generated (manually…) from the code itself by executing many PHP searches. I personally keep a copy of the latest plugin files in my PC downloads, so that I can always search through it when looking for a hook or a specific function.
So, follow along with me in this article as we explore the WooCommerce codebase, how it’s structured, and some of its inner secrets!
Where to find the code
To explore the WooCommerce codebase you have a couple of alternatives, other than downloading the plugin files from https://wordpress.org/plugins/woocommerce
Firstly, and most accessible, is browsing the code online via the WordPress Trac. This is the most convenient way to navigate the code as it’s always up to date and instantly available. All you need is an internet connection and access to a browser.
This method is great for quick code lookups and bookmarking code files to reference at a later date. You can even bookmark a particular line number too. e.g. to link to the render method of the Checkout Gutenberg block (which begins at line 66) you can use this URL: https://plugins.trac.wordpress.org/browser/woocommerce/trunk/packages/woocommerce-blocks/src/BlockTypes/Checkout.php#L66
The other option to view the code is to clone the official WooCommerce GitHub repository. This is recommended if you need to explore the code in more detail locally via your preferred editor, as you have access to more powerful search tools.
To do this you’ll need to use the command line to download and manage the WooCommerce repository. If you’re using macOS or a Linux operating system then you can use the built-in Terminal app. Git Bash is an excellent choice for Windows users.
Whatever terminal app you’re using, open it, and run the following command to clone WooCommerce to a local directory on your computer:
git clone https://github.com/woocommerce/woocommerce.git
You can either clone it directly into your local WordPress plugins directory (located in /wp-content/plugins/), or instead, clone WooCommerce to a generic folder on your computer and symlink it to your local WordPress plugins folder. The advantage with this method is that you can easily add/remove WooCommerce from a particular local WordPress instance. It’s not tied to a specific one.
Once you’ve cloned the repo then make sure you also run the following command to install the plugin dependencies and external packages.
npm install && composer install
This is important as not all WooCommerce code is included in the core repository. For example, the Gutenberg blocks are contained in a separate repository by default. To include them in the codebase you’ll need to use the above command to specifically install them.
Once all dependencies and external repositories have been installed they’re instantly available. Here’s the same Checkout block code we looked at earlier on the WordPress Trac, but now we have access to it locally.
Code Structure
The WooCommerce plugin is organized into several top level folders:
- /assets
- /i18n
- /includes
- /lib
- /packages
- /sample-data
- /src
- /templates
- /vendor
The assets folder contains a large collection of styles, fonts, images, and JavaScript which help with plugin aesthetics and interactivity both in the WordPress admin and on the frontend.
Standard plugin folders such as i18n, sample-data, and vendor contain functionality for internationalization features, sample product data, and 3rd party libraries respectively.
The template folder contains all the structured PHP templates used for various WooCommerce content such as the cart, checkout, emails etc. Each template can be overwritten by copying it to the relevant location in a custom theme (usually a child theme) so it’s worth browsing through this folder in detail to see all the available templates that can be customized. Please note: customizing WooCommerce via snippets is better than overriding templates.
The main core of the plugin functionality is contained in the includes, lib, packages, and src folders. In particular, the includes folder contains the main list of PHP plugin classes for a variety of WooCommerce features.
Also, all the Gutenberg block definitions available in WooCommerce are located in the packages folder.
Exploring the code
The main plugin file in the root folder is woocommerce.php. This bootstraps the autoloader and packages.
The autoloader manages loading of packages and classes located in the /src directory. Packages include code developed outside of the core WooCommerce plugin, such as the editor blocks.
Once all autoloaded code has been loaded, the main WooCommerce class is then included and instantiated via:
WooCommerce::instance()
This creates a new instance of the WooCommerce class and stores it inside a static class variable. This new instance is then returned and stored in a global variable so it can be accessed from anywhere.
Searching the Codebase
Most modern code editors provide powerful search functions to be able to navigate the codebase. For the examples shown below we’re using VS Code but it really doesn’t matter that much as almost all editors provide similar search functionality.
We can find out a lot about the codebase by performing some basic searches. For instance if we look for what hooks are available then searching for ‘add_filter‘ returns around 380 filter hooks!
Compare that to action hooks which returns even more at around 618 matches for the search term ‘add_action‘.
There’s plenty of scope for refining our searches such as doing searches only on specific file types, and for strings that specifically match the search term case and if it’s a whole word.
e.g. The following search result displays matches for ‘WooCommerce‘ where it’s a whole word, is case sensitive, and is located only in a PHP file (other file types are ignored).
One of the reasons VS Code is so popular is because of the huge number of extensions available, and there are several that can help with code navigation. One particular extension that stands out is Bookmarks.
It allows you to bookmark locations in your code so that you can jump back to specific code sections of interest at the click of a button. It comes in really handy, especially for large codebases such as WooCommerce.
In the following screenshot I’ve bookmarked a few WooCommerce action hooks for quick access that I’d like to come back to later on.
Just clicking on any of the bookmarked items in the explorer panel will take you directly to a specific line of code.
There are many other terms that you could search for. Perhaps you’d like to explore what WooCommerce classes are available. This type of search could be made more powerful when combined with Regex.
For example, it’s easy to search for class names that contain ‘WC’ at the beginning (e.g. ‘WC_Structured_Data’). But what about classes that contain ‘WC’ anywhere in the class name? For that, Regex is required as you’d need to search for the string ‘class’ followed by a space, which is then followed by a string that contains ‘WC’ anywhere inside.
With Regex you can also do things like searching for a function name (or part of a name) that is a method of a class and not a stand-alone function. The possibilities are endless and so a good working knowledge of Regex is highly recommended.
A quick WooCommerce customization example
Let’s say you need to customize the Checkout page, and specifically need to display a subtitle under the “Billing details” heading.
What you could do is a WooCommerce plugin file search for the ‘Billing details‘ string, to see if there is “something” that you can then use in your custom code. In this case I’ll use NotePad++ code editor, just to show that any software is valid:
I got 2 search results, but only one is relevant to the checkout page. So, I open that specific file (form-billing.php), at that specific line (28):
…and notice there is a do_action() right after the heading!
This gives us the chance to “inject” some code in there without overriding the whole template file. I go to my child theme’s functions.php and write the following:
/**
* @snippet Add Subtitle Below Billing Heading @ Checkout
* @how-to businessbloomer.com/woocommerce-customization
* @author Rodolfo Melogli, Business Bloomer
* @compatible WooCommerce 5
* @community https://businessbloomer.com/club/
*/
add_action( 'woocommerce_before_checkout_billing_form', 'bbloomer_billing_details_subtitle' );
function bbloomer_billing_details_subtitle() {
echo '<h4>This is a subtitle</h4>';
}
And here’s the “after”:
Keep Exploring!
We’ve only scratched the surface of what is quite frankly a very large codebase. It would take you a long time to look through every single line of code but hopefully I’ve managed to whet your appetite enough to continue digging around the fascinating WooCommerce codebase and learn even more!