Creating a plugin for WooCommerce

Want to create a plugin to extend WooCommerce? Plugins are essentially the same as regular WordPress plugins so for information on writing them see Writing a plugin

Check if WooCommerce is active ↑ Back to Top

Most WooCommerce plugins won’t need to run unless WooCommerce is already active. You can wrap your plugin in a check to see if WooCommerce is installed or not:

 * Check if WooCommerce is active
if ( in_array( 'woocommerce/woocommerce.php', apply_filters( 'active_plugins', get_option( 'active_plugins' ) ) ) ) {
    // Put your plugin code here

Main file naming ↑ Back to Top

The main plugin file should take the name of the plugin directly. E.g. a plugin called woocommerce-some-plugin would have it’s main file named woocommerce-some-plugin.php

Textdomains ↑ Back to Top

To follow the guidelines in, the text domain should match your plugin folder name. E.g. a plugin called woocommerce-some-plugin would have the text domain woocommerce-some-plugin. No underscores.

Follow WordPress PHP Guidelines ↑ Back to Top

WordPress has a set of guidelines to make all WordPress code consistent and easier to read. This includes quotes, indentation, brace style, shorthand php tags, yoda conditions, naming conventions, and a whole bunch more. Please read through the guidelines as they are very important so anyone can read your code.

These code conventions also prevent you from making dumb mistakes (like Apple did with iOS 7.0.6).

Custom Tables ↑ Back to Top

Creating custom tables should be avoided. If possible, you should always use WordPress custom post typestaxonomies, and options.

Prevent Data Leaks ↑ Back to Top

You should always try to prevent direct access data leaks. Add this line of code after the opening PHP tag in each PHP file:

if ( ! defined( 'ABSPATH' ) ) { 
    exit; // Exit if accessed directly

Readme ↑ Back to Top

All plugins should have the standard WordPress readme.

Use WordPress / WooCommerce UI ↑ Back to Top

It’s important to have a consistent UI across plugins than have totally different UIs for each plugin. All plugins should be hooked into the WordPress / WooCommerce UI. Application data should be loaded via API instead of via an iframe.

Admin Menu Screens ↑ Back to Top

Both WordPress and WooCommerce provide an extendable administration menu system, allowing for menu items to be added anywhere from the top level of the navigation, all the way through to as an integration sub-menu in the WooCommerce “Integrations” tab. It is important to understand the reasons for each of the various navigation systems, and in which circumstances we expect each to be employed.

tl;dr – which to use when, and why

If your plugin integrates with a third party service (for example, to receive tax rates, or connect to a helpdesk), you should use the integration class.
If your plugin adds a settings screen to set up the plugin, these settings should go under the appropriate tab on the WooCommerce > Settings screen.
If your plugin has settings which don’t fit under the existing tabs, and creating a sub-tab isn’t appropriate, create a top-level settings tab.
If your plugin adds administration screens which don’t involve settings (eg: “Checkout Add-ons” has a screen for managing the checkout add-on fields), use a sub-menu under the “WooCommerce” admin menu item.

WooCommerce Integrations Sub-Menu

WooCommerce provides a facility for registering product integrations. If integrations are registered, an Integrations tab is made available under the WooCommerce > Settings screen.

If your plugin interfaces with a third-party service other than a payment gateway or shipping method (which have their own structures), your settings screen should be placed in the Integrations tab.

If you’re integrating a plugin with WooCommerce, we strongly recommend that you use the WC_Integration class.

WordPress Settings Sub-Menu

The top-level Settings menu item within WordPress is reserved for screens only accessible to full-access administrators. If your plugin consists only of a single settings screen, and is a standalone product, your settings screen should go here.

As WooCommerce extensions are not standalone products, your settings screen would seem out of place if placed under the main WordPress Settings menu item.
Look how lost and out of place I look, being so far away from the other WooCommerce admin screens.

Look how lost and out of place I look, being so far away from the other WooCommerce admin screens.

WooCommerce Sub-Menu

If your plugin adds administration screens which don’t involve setting up your plugin, these screens can go here. An example would be our “Coupon Campaigns” extension, which adds a WooCommerce sub-menu item to create, edit and delete coupon campaigns, for “Checkout Add-ons” which adds a screen for managing checkout screen add-on fields.

Another reason for this kind of determining factor is that not all admin screens belong as WooCommerce sub-menu items. If everyone placed their settings screen links here, we’d end up with an overly lengthy administration menu, which isn’t convenient for the WooCommerce store owner or manager.

Settings used to set up your plugin do not belong in a WooCommerce sub-menu item.
If everyone placed their screen links here all willy-nilly, this is what the WooCommerce store owner would end up with. :)

If everyone placed their screen links here all willy-nilly, this is what the WooCommerce store owner would end up with. :)

WooCommerce Settings Tab

WooCommerce Settings tabs are intended for top-level, broad topics around setting up WooCommerce.

If your plugin requires settings which don’t fall under any of the provided settings tabs, and does not interface with a third-party service, feel free to use a new WooCommerce Settings tab.

We make this distinction so as to avoid overly lengthy settings tab bars, which do not provide a pleasant user experience for the store owner or store manager.

If everyone placed their settings in a new settings tab, we'd soon run out of space!

If everyone placed their settings in a new settings tab, we’d soon run out of space!

WooCommerce Settings Section

As of 2.2, there is a new filter in place that allows you add a new section, beneath one of the core settings’ tabs, like so:

If your settings require a page but fall under one of the top level tabs like Products, please add them in a section, in order to keep it more organised and easier for the user.

Read about how to do this here – Adding a Section to a Settings Tab – all it takes is a few lines of code!

Make it Extensible ↑ Back to Top

Developers should use WordPress actions and filters to allow for easy modification / customization of their items without users having to touch the plugin’s core code base.

Additionally, if your plugin creates a front-end output, it’s recommended to have some sort of templating engine in place so that users of the plugin can create custom template files in their theme’s woocommerce folder that will overwrite the plugin’s template files.

For more information, check out Pippin’s post on Writing Extensible Plugins with Actions and Filters.

Remove Unused Code ↑ Back to Top

With version control there’s no point in leaving commented out code in the plugin. It must makes it annoying to scroll through and read the code. Remove it and add it back in later if you need it.

Comment! ↑ Back to Top

If you have a function what does the function do? There should be comments for most if not every function in your code. Someone (including yourself) may want to modify your code and comments are very helpful for that. We recommend using PHP Doc Blocks similar to WooCommerce.

Avoid God Objects ↑ Back to Top

God Objects are objects that know too much or do too much. The whole point of object oriented programming is taking a large problem and breaking it down into smaller parts. By having functions do too much it’s hard to follow that logic and a bug will be much harder to fix. Instead of having a couple of massive functions, break them down into smaller pieces.

Test Your Code with WP_DEBUG ↑ Back to Top

You should always develop with WP_DEBUG mode on so you can see all of the PHP warnings that are sent to the screen. It’s usually simple things like making sure a variable is set before checking the value.

Separate Business Logic & Presentation Logic ↑ Back to Top

It’s a good practice to separate business logic (ex. how the plugin works) from presentation logic (ex. how it looks). Two separate pieces of logic are more easily maintained and swapped out if necessary. A simplistic example would be have two different classes one for displaying the end results and one for the admin settings page.

Use Transients to Store Offsite Information ↑ Back to Top

If you provide some sort of service via an API it’s best to store that information so that future queries will be done much faster and the load on your service is lessened. You can use WordPress transients to store data for a certain amount of time.

Logging Data ↑ Back to Top

Sometimes you may want to log data which can be especially useful for debugging purposes. This is great with two conditions:

  • Any logging should be opt in.
  • You should use the WC_Logger class. A user can then view the logs on their system status page.
Back to the top