Creating a plugin for WooCommerce

Want to create a plugin to extend WooCommerce? Plugins are essentially the same as regular WordPress plugins. More information at: Writing a plugin

Note: We provide this page as guidance for third-party developers. WooCommerce.com is no longer accepting new submissions to be sold on our website as of 1 February 2016.

Check if WooCommerce is active ↑ Back to top

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

/**
 * 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 adopt the name of the plugin, e.g., A plugin with the directory name of plugin-name would have its main file named plugin-name.php.

Text domains ↑ Back to top

Follow guidelines for Internationalization for WordPress Developers, the text domain should match your plugin directory name, e.g., A plugin with a directory name of plugin-name would have the text domain plugin-name. No underscores.

Localization ↑ Back to top

All text strings within the plugin code should be in English. This is the WordPress default locale, and English should always be the first language. If your plugin is intended for a specific market (e.g., Spain or Italy), appropriate translation files for those languages should be included within your plugin package. More at: Using Makepot to translate your plugin.

Follow WordPress PHP Guidelines ↑ Back to top

WordPress has a set of guidelines to keep all WordPress code consistent and easier to read. This includes quotes, indentation, brace style, shorthand php tags, yoda conditions, naming conventions, and more. Please review the guidelines.

Code conventions also prevent basic mistakes, as Apple made with iOS 7.0.6.

Custom Database Tables & Data Storage ↑ Back to top

Creating custom database tables should be avoided. Whenever possible, you should always use WordPress post types, taxonomies, and options.

Consider the permanence of your data. Here’s a quick primer:

  • If the data may not always be present (i.e., it expires), use a transient.
  • If the data is persistent but not always present, consider using the WP Cache.
  • If the data is persistent and always present, consider the wp_options table.
  • If the data type is an entity with n units, consider a post type.
  • If the data is a means or sorting/categorizing an entity, consider a taxonomy.

Logs should be written to a file using the WC_Logger class.

Prevent Data Leaks ↑ Back to top

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 need a standard WordPress readme. In addition, you should add two extra headers to the top of the readme file.

  • WC requires at least
  • WC tested up to

Your readme might look something like this:

=== Plugin Name ===
Contributors: (this should be a list of wordpress.org userid's)
Tags: comments, spam
Requires at least: 4.0.1
Tested up to: 4.3
Stable tag: 4.3
License: GPLv3 or later License
URI: http://www.gnu.org/licenses/gpl-3.0.html
WC requires at least: 2.2
WC tested up to: 2.3

Plugin Author Name ↑ Back to top

Consistency is important to us and our customers. Products offered through WooCommerce.com should provide a consistent experience for all aspects of the product, including who the customer contacts if they have queries.

It should also be obvious for the customer to differentiate a product purchased at WooCommerce.com from a product purchased elsewhere, when looking through their plugin list in WordPress.

Thus, the following plugin headers should be in place:

  • The Plugin Author is WooCommerce
  • The Developer header is YourName/YourCompany, with the Developer URI field listed as http://yourdomain.com/
  • Copyright information is “WooCommerce”

For example:

/**
 * Plugin Name: WooCommerce Extension
 * Plugin URI: http://woocommerce.com/products/woocommerce-extension/
 * Description: Your extension's description text.
 * Version: 1.0.0
 * Author: WooCommerce
 * Author URI: http://woocommerce.com/
 * Developer: Your Name
 * Developer URI: http://yourdomain.com/
 * Text Domain: woocommerce-extension
 * Domain Path: /languages
 *
 * Copyright: © 2009-2015 WooCommerce.
 * License: GNU General Public License v3.0
 * License URI: http://www.gnu.org/licenses/gpl-3.0.html
 */

In the WooCommerce Helper plugin — required for customers to receive product updates — developer information is included as part of the plugin info to ensure developers are given the credit they deserve.

Plugin URI ↑ Back to top

Ensure that the Plugin URI line of the above plugin header is provided. This line should contain the URL of the plugin’s product/sale page on WooCommerce.com (if sold by WooCommerce) or to a dedicated page for the plugin on your website.

Use WordPress/WooCommerce UI ↑ Back to top

It’s important to keep a consistent UI across plugins. All plugins should be hooked into the WordPress/WooCommerce UI. Application data should be loaded via API instead of 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 to 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 ↑ Back to top

  • If your plugin integrates with a third party service (e.g., to receive tax rates or connect to a Help Desk), you should use the integration class.
  • If your plugin adds a settings screen to set up the plugin, settings should be under an appropriate tab on the WooCommerce > Settings screen.
  • If your plugin has settings that don’t fit under existing tabs, and creating a sub-tab isn’t appropriate, create a top-level settings tab.
  • If your plugin adds administration screens that don’t involve settings (e.g., Checkout Add-Ons has a screen for managing checkout add-on fields), use a sub-menu under the WooCommerce admin menu item.

WooCommerce Integrations Sub-Menu ↑ Back to top

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 that 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 ↑ Back to top

The top-level Settings menu in WordPress is reserved for screens that are only accessible by full administrators. If your plugin has 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 look out of place under the main WordPress Settings menu.
Look how lost and out of place I look, being so far away from the other WooCommerce admin screens.
How a plugin would look if located under WordPress Settings, far away from the the WooCommerce admin.

WooCommerce Sub-Menu ↑ Back to top

If your plugin adds administration screens that don’t involve setting up your plugin, these screens can sit under the WooCommerce Sub-Menu. For example, Coupon Campaigns adds a WooCommerce sub-menu item to create, edit and delete coupon campaigns; Checkout Add-Ons adds a screen for managing checkout screen add-on fields.

Another reason is that not all admin screens belong in the WooCommerce sub-menu. If everyone placed their settings screen here, there would be a lengthy administration menu. This is inconvenient 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 screen links here, this is what the WooCommerce store owner would see.

WooCommerce Settings Tab ↑ Back to top

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

If your plugin requires settings that don’t fit any of the provided settings tabs, and does not interface with a third-party service, use a new WooCommerce Settings tab.

We make this distinction to avoid lengthy settings tab bars, which do not provide a pleasant UX for a store owner or manager.

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

WooCommerce Settings Section ↑ Back to top

As of 2.2, there is a new filter that allows you add a section beneath a core Settings tab:

If your settings require a page but fall under one of the top level tabs like Products, add them in a section to keep it organized and user friendly.

More info at 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 modification/customization without users having to touch the plugin’s core code base.

And if your plugin creates a front-end output, it’s recommended to have a templating engine in place so users can create custom template files in their theme’s WooCommerce folder that overwrites 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 reason to leave in commented out code that can be annoying to scroll through and read. Remove it and add it back later if needed.

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/You may want to modify, and comments are helpful for that. We recommend using PHP Doc Blocks  similar to WooCommerce.

Avoid God Objects ↑ Back to top

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

Test Your Code with WP_DEBUG ↑ Back to top

Always develop with WP_DEBUG mode on, so you can see all PHP warnings sent to the screen. It’s usually 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 (i.e., how the plugin works) from presentation logic (i.e., how it looks). Two separate pieces of logic are more easily maintained and swapped if necessary. An example is to 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 a service via an API, it’s best to store that information so future queries can be done faster, and the load on your service is lessened. WordPress transients can be used to store data for a certain amount of time.

Logging Data ↑ Back to top

You may want to log data that can be useful for debugging purposes. This is great with two conditions:

  • Allow any logging as an ‘opt in’.
  • Use the WC_Logger class. A user can then view logs on their system status page.

If adding logging to your extension, here’s a snippet for presenting a link to the logs, in a way the extension user can easily make use of.

UI for service integration plugins ↑ Back to top

If your plugin relies on connecting to an external service (for example, your service is a payment gateway, shipping method, or other service integration), it’s important to inform your users that a connection is required in order to use the plugin.

To do this, we recommend an admin notice, linking to the specific service integration screen within WooCommerce.

We recommend a notice with this text format, as it's consistent and informs the user.
We recommend a notice with this text format, as it’s consistent and informs the user.

The following code was taken directly out of an integration we developed with Mailchimp, and forms part of a larger PHP class. The code has been preserved, rather than modified to be an example, for your reference in the context of a PHP class.

↑ Back to top

WooCommerce - the most customizable eCommerce platform for building your online business.

Back to the top