WooCommerce 3.0 introduced CRUD objects for working with WooCommerce data. Whenever possible it is best-practices to use these objects in your code instead of directly updating metadata or using WordPress post objects. The following objects are handled by CRUD objects and data-stores:

• Orders
• Order line items
• Products
• Coupons
• Customers
• Customer downloads
• Payment tokens
• Shipping zones
• Webhooks

Each of these objects contains a schema for the data it controls (properties), a getter and setter for each property, and a save/delete method which talks to a data store.

The data store handles the actual saving/reading from the database – the object itself does not need to be aware of where the data is stored. You can read about data stores here.

The benefits of CRUD

• Structure – each object has a pre-defined structure and keeps it’s own data valid.
• Control – We control the flow of data, and any validation needed, so we know when changes occur.
• Ease of development – As a developer, you don’t need to know the internals of the data you’re working with, just the names.
• Abstraction – The data can be moved elsewhere e.g. custom tables, without affecting existing code.
• Unification – We can use the same code for updating things in admin as we do in the REST API and CLIs – everything is unified.
• Simplified code – less procedural code to update objects which reduces likelihood of malfunction and adds more unit test coverage.

CRUD object structure

The WC_Data class is the basic implementation for CRUD objects, and all CRUD objects extend it.

The most important parts to note: $data is an array of props supported in each object, and $id is the object’s ID.

The coupon object class is a good example of extending WC_Data and adding CRUD functions to all properties.

Data

$data stores the property names, and default values:

        /**
     * Data array, with defaults.
     * @since 3.0.0
     * @var array
     */
    protected $data = array(
        'code'                        => '',
        'amount'                      => 0,
        'date_created'                => '',
        'date_modified'               => '',
        'discount_type'               => 'fixed_cart',
        'description'                 => '',
        'date_expires'                => '',
        'usage_count'                 => 0,
        'individual_use'              => false,
        'product_ids'                 => array(),
        'excluded_product_ids'        => array(),
        'usage_limit'                 => 0,
        'usage_limit_per_user'        => 0,
        'limit_usage_to_x_items'      => 0,
        'free_shipping'               => false,
        'product_categories'          => array(),
        'excluded_product_categories' => array(),
        'exclude_sale_items'          => false,
        'minimum_amount'              => '',
        'maximum_amount'              => '',
        'email_restrictions'          => array(),
        'used_by'                     => array(),
    );

Getters and setters

Each one of the keys in this array (property) has a getter and setter, e.g. set_used_by() and get_used_by(). $data itself is private, so the getters and setters must be used to access the data.

Example getter:

    /**
     * Get records of all users who have used the current coupon.
     * @since  3.0.0
     * @param  string $context
     * @return array
     */
    public function get_used_by( $context = 'view' ) {
        return $this->get_prop( 'used_by', $context );
    }

Example setter:

    /**
     * Set which users have used this coupon.
     * @since 3.0.0
     * @param array $used_by
     * @throws WC_Data_Exception
     */
    public function set_used_by( $used_by ) {
        $this->set_prop( 'used_by', array_filter( $used_by ) );
    }

set_prop and get_prop are part of WC_Data. These apply various filters (based on context) and handle changes (so we can save only changes and not all props).

A note on $context: when getting data to use on the frontend or display, view context is used. This applies filters to the data so extensions can change the values dynamically.

edit context should be used when showing values to edit in the backend, and for saving to the database. Using edit context does not apply any filters to the data.

The constructor

The constructor of the CRUD objects facilitates the read from the database. The actual read is not done by the CRUD class, but by its data store.

Example:

    /**
     * Coupon constructor. Loads coupon data.
     * @param mixed $data Coupon data, object, ID or code.
     */
    public function __construct( $data = '' ) {
        parent::__construct( $data );

        if ( $data instanceof WC_Coupon ) {
            $this->set_id( absint( $data->get_id() ) );
        } elseif ( is_numeric( $data ) && 'shop_coupon' === get_post_type( $data ) ) {
            $this->set_id( $data );
        } elseif ( ! empty( $data ) ) {
            $this->set_id( wc_get_coupon_id_by_code( $data ) );
            $this->set_code( $data );
        } else {
            $this->set_object_read( true );
        }

        $this->data_store = WC_Data_Store::load( 'coupon' );
        if ( $this->get_id() > 0 ) {
            $this->data_store->read( $this );
        }
    }

Note how it sets the ID based on the data passed to the object, then calls the data store to retrieve the data from the database.

Once the data is read via the data store, or if no ID is set, $this->set_object_read( true ); is set so the data store and CRUD object knows it’s read. Once this is set, changes are tracked.

Saving and deleting

Save and delete methods are optional at CRUD object level because the WC_Data class can handle it. When save is called, the data store is used to store data to the database. Delete removes the object from the database. save must be called for changes to persist, otherwise they will be discarded.

The save method looks like this in WC_Data:

    /**
     * Save should create or update based on object existence.
     *
     * @since  2.6.0
     * @return int
     */
    public function save() {
        if ( $this->data_store ) {
            // Trigger action before saving to the DB. Allows you to adjust object props before save.
            do_action( 'woocommerce_before_' . $this->object_type . '_object_save', $this, $this->data_store );

            if ( $this->get_id() ) {
                $this->data_store->update( $this );
            } else {
                $this->data_store->create( $this );
            }
            return $this->get_id();
        }
    }

Update/create is used depending on whether the object has an ID yet. The ID will be set after creation.

The delete method is like this:

    /**
     * Delete an object, set the ID to 0, and return result.
     *
     * @since  2.6.0
     * @param  bool $force_delete
     * @return bool result
     */
    public function delete( $force_delete = false ) {
        if ( $this->data_store ) {
            $this->data_store->delete( $this, array( 'force_delete' => $force_delete ) );
            $this->set_id( 0 );
            return true;
        }
        return false;
    }

CRUD Usage Examples

Creating a new simple product

$product = new WC_Product_Simple();
$product->set_name( 'My Product' );
$product->set_slug( 'myproduct' );
$product->set_description( 'A new simple product' );
$product->set_regular_price( '9.50' );
$product->save();

$product_id = $product->get_id();

Updating an existing coupon

$coupon = new WC_Coupon( $coupon_id );
$coupon->set_discount_type( 'percent' );
$coupon->set_amount( 25.00 );
$coupon->save();

Retrieving a customer

$customer = new WC_Customer( $user_id );
$email    = $customer->get_email();
$address  = $customer->get_billing_address();
$name     = $customer->get_first_name() . ' ' . $customer->get_last_name();

The post Developing using WooCommerce CRUD objects first appeared on CODIBU.

If your extension just has a couple of simple settings, do you really need to create a new tab specifically for it? Most likely the answer is no.

When to Create a Section

Let’s say we had an extension that adds a slider to a single product page. This extension doesn’t have many options, just a couple:

• Auto-insert into single product page (checkbox)
• Slider Title (text field)

That’s only two options, specifically related to Products. We could quite easily just append them onto the core WooCommerce Products Settings (WooCommerce > Settings > Products), but that wouldn’t be very user friendly. Users wouldn’t know where to look initially so they’d have to scan all of the Products options and it would be difficult / impossible to link the options directly.

Fortunately, as of WooCommerce 2.2.2, there is a new filter in place that allows you add a new section, beneath one of the core settings’ tabs.

How to Create a Section

We’ll go over doing this through individual functions, but you should probably create a Class that stores all of your settings methods.

The first thing you need to is add the section, which can be done like this by hooking into the woocommerce_get_sections_products filter:

Make sure you change the wcslider parts to suit your extension’s name / text-domain.

The important thing about the woocommerce_get_sections_products filter, is that the last part products, is the tab you’d like to add a section to. So if you want to add a new tab to accounts section, you would hook into the woocommerce_get_sections_accounts filter.

How to Add Settings to a Section

Now that you’ve got the tab, you need to filter the output of woocommerce_get_sections_products (or similar). You would add the settings like usual using the WooCommerce Settings API, but check for the current section before adding the settings to the tab’s settings array.

For example, let’s add the sample settings we discussed above to the new wcslider section we just created:

We’re hooking into the same woocommerce_get_sections_products filter, but this time doing a check that the $current_section matches our earlier defined custom section (wcslider), before adding in our new settings.

Using the New Settings

You would now just use your newly created settings like you would any other WordPress / WooCommerce setting, through the get_option function and the defined ID of the setting.

For example, to use the previously created wcslider_auto_insert option, simply use the following code:

get_option( 'wcslider_auto_insert' )

Conclusion

When creating an extension for WooCommerce, think about where your settings belong before you create them. The key to building a useful product is making it easy to use for the end user, so appropriate setting placement is crucially important.

For more specific information on adding settings to WooCommerce, check out the Settings API documentation.

The post Adding a Section to a Settings Tab first appeared on CODIBU.

We’ve created this tutorial so you can see how to create a new integration.

Setting up the Integration

You’ll need at least two files to create an integration so you’ll need to create a directory.

Creating the Main Plugin File

Create your main plugin file to hook into the plugins_loaded hook and check if the WC_Integration class exists. If it doesn’t then the user most likely doesn’t have WooCommerce activated.

After you do that you need to register the integration. Load the integration file (we’ll get to this file in a minute). Use the woocommerce_integrations filter to add a new integration to the array.

Creating the Integration Class

Now that we have the framework setup let’s actually implement this Integration class. There already is a WC_Integration class so we want to make a child class. This way it inherits all of the existing methods and data.

You’ll need to set an id, a description, and a title for your integration. These will show up on the integration page.

You’ll also need to load the settings by calling:
$this->init_form_fields(); & $this->init_settings();

You’ll also need to save your options by calling the woocommerce_update_options_integration_{your method id} hook.

Lastly you have to input some settings to save! I’ve included two dummy fields below but we’ll go more into fields in the next section.

Creating Settings

If you took a look through the last section you’ll see that we added two dummy settings using the init_form_fields() method.

Types of Settings

WooCommerce includes support for 8 types of settings.

• text
• price
• decimal
• password
• textarea
• checkbox
• select
• multiselect

And these settings have attributes which you can use. These affect the way the setting looks and behaves on the settings page. It doesn’t affect the setting itself. The attributes will manifest slightly differently depending on the setting type. A placeholder for example doesn’t work with checkboxes. To see exactly how they work you should look through the source code. Ex.

• title
• class
• css
• placeholder
• description
• default
• desc_tip

Creating Your Own Settings

The built-in settings are great but you may need extra controls to create your settings page. That’s why we included some methods to do this for you.

First create a new setting. And under type enter in whatever new control you want.

Then create a new method to generate the HTML for that input. You can look through the source code for sample code. The below example creates a button that goes to WooThemes.com.

Validating & Sanitizing Data

To create the best user experience you’ll most likely want to validate and sanitize your data. The integration class already performs basic sanitization so that there’s no malicious code present but you could further sanitize by removing unused data. An example of sanitizing data would be integrating with a 3rd party service where all API keys are upper case. You could convert the API key to upper case which will make it a bit more clear for the user.

Sanitize

I’m going to show you how to sanitize data first because it’s a bit easier to understand. But the one thing you should keep in mind is that sanitizing happens after validation. So if something isn’t validated it won’t get to the sanitization step.

Validation

Validation isn’t always necessary but it’s nice to do. If your API keys are always 10 characters long and someone enters one that’s not 10 then you can print out an error message and prevent the user a lot of headache when they assumed they put it in correctly.

First set up a validate_{setting key}_field method for each field you want to validate. For example, with the api_key field you need a validate_api_key_field() method.

A complete example#

If you’ve been following along you should have a complete integration example. If you have any problems see our full integration demo.

The post Implementing the WC Integration Class first appeared on CODIBU.

You can view the WC_API class in our docs.

Callback URL

To trigger the WooCommerce API, you need to use a special URL. Before WooCommerce 2.0, you could use:

http://yoursite.com/?wc-api=CALLBACK

In WooCommerce 2.0+,  you can still use that or use our endpoint:

http://yoursite.com/wc-api/CALLBACK/

When this URL is called, WooCommerce:

1. Initializes the CALLBACK class, if it exists
2. Triggers an action based on the callback: woocommerce_api_callback. Note: CALLBACK will be sanitized and lower case.
3. Exit WordPress.

Hooking into the callback

Add an action to hook into the callback hook. For example:

add_action( 'woocommerce_api_callback', 'callback_handler' );

WooCommerce will exit after that action, but you can still redirect the user elsewhere from your handler if you wish.

The post WC_API – The WooCommerce API Callback first appeared on CODIBU.

But maybe you’d like to see what a store full of sample orders and products looks like. If so, we’ve got some data for you!

Sample data for WooCommerce is located in a file called either sample-products.csv or sample-products.xml, which are located in the WooCommerce plugin folder in woocommerce/sample-data/. You can get it in two ways:

• Re-download WooCommerce. Open the .zip and find the files in the folder.
• Get the file from your site via SFTP, etc.

Import via WooCommerce Products

This is the recommended approach.

From the WordPress Dashboard:

1. Go to: Products > All Products.
2. Select Import.
3. Run Importer. An Import Products screen appears.
   
4. Select Choose file and then select the sample-products.csv file you downloaded.
5. Continue. A Column Mapping screen appears.
6. Scroll down and Run the Importer.
   

You now have sample data in WooCommerce to learn from.

Import via WordPress Importer

From the WordPress Dashboard:

1. Go to: Tools > Import.
2. Select WordPress.
   
3. Run Importer.
4. Select Choose file and then select the sample-products.xml file you downloaded.
5. Upload file and import.
6. Import our default wooteam author, create a new user, or assign the posts to an existing user. This is your call to make, though we recommend assigning the posts to an existing user.
7. Tick or untick the box for Download and import file attachments. This imports all sample product images to your site if ticked.
   
8. Submit and your sample data is imported.

The post Importing WooCommerce Sample Data first appeared on CODIBU.

Removing /product/, /product-category/, or /shop/ from the URLs is not advisable due to the way WordPress resolves its URLs. It uses the product-category (or any other text for that matter) base of an URL to detect that it is an URL leading to a product category.

There are SEO plugins that allow you to remove this base, but that can lead to a number of problems with performance and duplicate URLs.

Better to avoid

You will make it harder for WordPress to detect what page you are trying to reach when you type in a product category URL.

Also, understand that the standard “Page” in WordPress always has no base text in the URL. For example:

• http://yoursite.com/about-page/ (this is the URL of a standard page)
• http://yoursite.com/about-page/product-category/category-x/ (this is the URL leading to a product category)

What would happen if we remove that ‘product-category’ part?

• http://yoursite.com/about-page/about-page/
• http://yoursite.com/about-page/category-x/

WordPress will have to do much more work to detect what page you are looking for when entering one of the above URLs. That is why we do not recommend using any SEO plugin to achieve this.

The post Removing /product/ , /product-category/ , or /shop/ from the URLs first appeared on CODIBU.

Hooks in WordPress essentially allow you to change or add code without editing core files. They are used extensively throughout WordPress and WooCommerce and are very useful for developers.

There are two types of hook: actions and filters.

• Action Hooks allow you to insert custom code at various points (wherever the hook is run).
• Filter Hooks allow you to manipulate and return a variable which it passes (for instance a product price).

There is an older article on hooks and filters here.

Using hooks

If you use a hook to add or manipulate code, you can add your custom code in a variety of ways:

• To a custom child theme’s functions.php file.
• Using a plugin such as Code Snippets.

Using action hooks

To execute your own code, you hook in by using the action hook do_action('action_name');. Here is where to place your code:

add_action( 'action_name', 'your_function_name' );

function your_function_name() {
// Your code
}

Using filter hooks

Filter hooks are called throughout are code using apply_filter( 'filter_name', $variable );. To manipulate the passed variable, you can do something like the following:

add_filter( 'filter_name', 'your_function_name' );

function your_function_name( $variable ) {
// Your code
return $variable;
}

With filters, you must return a value.

To learn more about options for using hooks and filters see our Snippet doc section.

Example

In the example below, both action hooks and filter hooks are used. This tutorial teaches you how to change and add fields to the checkout.

• Actions are used to:
  • Add a new field to the checkout
  • Add that new field to the order
• Filters are used to:
  • Override the labels and placeholders of existing fields
  • Make an existing field optional while it used to be required
  • Remove existing fields

Customizing checkout fields using actions and filters

API Documentation

For a comprehensive view of the WooCommerce API, see the API Documentation.

Available WooCommerce action hooks and filters

For details on what the action hooks and filters do, reference the WooCommerce Hooks Reference.

The post WooCommerce Hooks: Actions and filters first appeared on CODIBU.

Custom code should be copied into your child theme’s functions.php file.

How Are Checkout Fields Loaded to WooCommerce?

The billing and shipping fields for checkout pull from the countries class (class-wc-countries.php) and the get_address_fields function. This allows WooCommerce to enable/disable fields based on the user’s location.

Before returning these fields, WooCommerce puts the fields through a filter. This allows them to be edited by third-party plugins, themes and your own custom code.

Billing:

$address_fields = apply_filters('woocommerce_billing_fields', $address_fields);

Shipping:

$address_fields = apply_filters('woocommerce_shipping_fields', $address_fields);

The checkout class adds the loaded fields to its ‘checkout_fields’ array, as well as adding a few other fields like “order notes”.

$this->checkout_fields['billing']    = $woocommerce->countries->get_address_fields( $this->get_value('billing_country'), 'billing_' );
$this->checkout_fields['shipping']   = $woocommerce->countries->get_address_fields( $this->get_value('shipping_country'), 'shipping_' );
$this->checkout_fields['account']    = array(
    'account_username' => array(
        'type' => 'text',
        'label' => __('Account username', 'woocommerce'),
        'placeholder' => _x('Username', 'placeholder', 'woocommerce')
        ),
    'account_password' => array(
        'type' => 'password',
        'label' => __('Account password', 'woocommerce'),
        'placeholder' => _x('Password', 'placeholder', 'woocommerce'),
        'class' => array('form-row-first')
        ),
    'account_password-2' => array(
        'type' => 'password',
        'label' => __('Account password', 'woocommerce'),
        'placeholder' => _x('Password', 'placeholder', 'woocommerce'),
        'class' => array('form-row-last'),
        'label_class' => array('hidden')
        )
    );
$this->checkout_fields['order']  = array(
    'order_comments' => array(
        'type' => 'textarea',
        'class' => array('notes'),
        'label' => __('Order Notes', 'woocommerce'),
        'placeholder' => _x('Notes about your order, e.g. special notes for delivery.', 'placeholder', 'woocommerce')
        )
    );

This array is also passed through a filter:

$this->checkout_fields = apply_filters('woocommerce_checkout_fields', $this->checkout_fields);

That means you have full control over checkout fields – you only need to know how to access them.

Overriding Core Fields

Hooking into the  woocommerce_checkout_fields filter lets you override any field. As an example, let’s change the placeholder on the order_comments fields. Currently, it’s set to:

_x('Notes about your order, e.g. special notes for delivery.', 'placeholder', 'woocommerce')

We can change this by adding a function to our theme functions.php file:

// Hook in
add_filter( 'woocommerce_checkout_fields' , 'custom_override_checkout_fields' );

// Our hooked in function - $fields is passed via the filter!
function custom_override_checkout_fields( $fields ) {
     $fields['order']['order_comments']['placeholder'] = 'My new placeholder';
     return $fields;
}

You can override other parts, such as labels:

// Hook in
add_filter( 'woocommerce_checkout_fields' , 'custom_override_checkout_fields' );

// Our hooked in function - $fields is passed via the filter!
function custom_override_checkout_fields( $fields ) {
     $fields['order']['order_comments']['placeholder'] = 'My new placeholder';
     $fields['order']['order_comments']['label'] = 'My new label';
     return $fields;
}

Or remove fields:

// Hook in
add_filter( 'woocommerce_checkout_fields' , 'custom_override_checkout_fields' );

// Our hooked in function - $fields is passed via the filter!
function custom_override_checkout_fields( $fields ) {
     unset($fields['order']['order_comments']);

     return $fields;
}

Here’s a full list of fields in the array passed to woocommerce_checkout_fields:

• Billing
  • billing_first_name
  • billing_last_name
  • billing_company
  • billing_address_1
  • billing_address_2
  • billing_city
  • billing_postcode
  • billing_country
  • billing_state
  • billing_email
  • billing_phone
• Shipping
  • shipping_first_name
  • shipping_last_name
  • shipping_company
  • shipping_address_1
  • shipping_address_2
  • shipping_city
  • shipping_postcode
  • shipping_country
  • shipping_state
• Account
  • account_username
  • account_password
  • account_password-2
• Order
  • order_comments

Each field contains an array of properties:

• type – type of field (text, textarea, password, select)
• label – label for the input field
• placeholder – placeholder for the input
• class – class for the input
• required – true or false, whether or not the field is require
• clear – true or false, applies a clear fix to the field/label
• label_class – class for the label element
• options – for select boxes, array of options (key => value pairs)

In specific cases you need to use the woocommerce_default_address_fields filter. This filter is applied to all billing and shipping default fields:

• country
• first_name
• last_name
• company
• address_1
• address_2
• city
• state
• postcode

For example, to make the address_1 field optional:

// Hook in
add_filter( 'woocommerce_default_address_fields' , 'custom_override_default_address_fields' );

// Our hooked in function - $address_fields is passed via the filter!
function custom_override_default_address_fields( $address_fields ) {
     $address_fields['address_1']['required'] = false;

     return $address_fields;
}

Defining select options

If you are adding a field with type ‘select’, as stated above you would define key/value pairs. For example:

$fields['billing']['your_field']['options'] = array(
  'option_1' => 'Option 1 text',
  'option_2' => 'Option 2 text'
);

Priority

Priority in regards to PHP code helps establish when a bit of code — called a function — runs in relation to a page load. It is set inside of each function and is useful when overriding existing code for custom display.

Code with a higher number set as the priority will run after code with a lower number, meaning code with a priority of 20 will run after code with 10 priority.

The priority argument is set during the add_action function, after you establish which hook you’re connecting to and what the name of your custom function will be.

In the example below, blue text is the name of the hook we’re modifying, green text is the name of our custom function, and red is the priority we set.

Examples

In this example, the code is set to redirect the “Return to Shop” button found in the cart to a category that lists products for sale at http://example.url/category/specials/.

There, we can see the priority is set to 10. This is the typical default for WooCommerce functions and scripts, so that may not be sufficient to override that button’s functionality.

Instead, we can change the priority to any number greater than 10. While 11 would work, best practice dictates we use increments of ten, so 20, 30, and so on.

With priority, we can have two functions that are acting on the same hook. Normally this would cause a variety of problems, but since we’ve established one has a higher priority than the other, our site will only load the appropriate function, and we will be taken to the Specials page as intended with the code below.

Adding Custom Shipping And Billing Fields

Adding fields is done in a similar way to overriding fields. For example, let’s add a new field to shipping fields – shipping_phone:

What do we do with the new field? Nothing. Because we defined the field in the checkout_fields array, the field is automatically processed and saved to the order post meta (in this case, _shipping_phone). If you want to add validation rules, see the checkout class where there are additional hooks you can use.

Adding a Custom Special Field

To add a custom field is similar. Let’s add a new field to checkout, after the order notes, by hooking into the following:

This gives us:

Next we need to validate the field when the checkout form is posted. For this example the field is required and not optional:

A checkout error is displayed if the field is blank:

Finally, let’s save the new field to order custom fields using the following code:

The field is now saved to the order.

If you wish to display the custom field value on the admin order edition page, you can add this code:

This is the result:

Example: Make phone number not required

Adding Custom Fields To Emails

To add a custom field value to WooCommerce emails — a completed order email, for example — use the following snippet:

The post Customizing checkout fields using actions and filters first appeared on CODIBU.

Register the taxonomy for menus

When registering taxonomies for your custom attributes, WooCommerce calls the following hook:

$show_in_nav_menus = apply_filters('woocommerce_attribute_show_in_nav_menus', false, $name);

So, for example, if your attribute slug was ‘size’ you would do the following to register it for menus:

add_filter('woocommerce_attribute_show_in_nav_menus', 'wc_reg_for_menus', 1, 2);

function wc_reg_for_menus( $register, $name = '' ) {
     if ( $name == 'pa_size' ) $register = true;
     return $register;
}

Now use your attribute in Appearance > Menus. You will notice, however, that it has default blog styling when you click on a link to your taxonomy term.

Create a template

You need to theme your attribute to make it display products as you want. To do this:

1. Copy woocommerce/templates/taxonomy-product_cat.php into your theme folder
2. Rename the template to reflect your attribute – in our example we’d use taxonomy-pa_size.php

You should now see this template when viewing taxonomy terms for your custom attribute.

The post Using custom attributes in menus and taxonomy archives first appeared on CODIBU.

Your WooCommerce extension should:

• Adhere to all WordPress plugin coding standards, as well as best practice guidelines for harmonious existence within WordPress and alongside other WordPress plugins.
• Have a single core purpose and use WooCommerce features as much as possible.
• Not do anything malicious or underhanded — for example, inserting spam links or up selling services outside of the WooCommerce.com ecosystem.
• Not subvert or override Marketplace connections in core — for example, extensions cannot create branded top level menu items or introduce their own telemetry.

Merchants make use of WooCommerce extensions daily, and should have an unified and pleasant experience while doing so without advertising invading their WP Admin or store.

Note: We provide this page as a best practice for developers.

Check if WooCommerce is active

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
}

Note that this check will fail if the WC plugin folder is named anything other than woocommerce.

Main file naming

The main plugin file should adopt the name of the plugin, e.g., A plugin with the directory name plugin-name would have its main file named plugin-name.php.

Text domains

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. Do not use underscores.

Localization

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), include appropriate translation files for those languages within your plugin package. Learn more at Using Makepot to translate your plugin.

Follow WordPress PHP Guidelines

WordPress has a set of guidelines to keep all WordPress code consistent and easy 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

Avoid creating custom database tables. Whenever possible, 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

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

All plugins need a standard WordPress readme.

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
Requires PHP: 5.6
Stable tag: 4.3
License: GPLv3 or later License
URI: http://www.gnu.org/licenses/gpl-3.0.html

Plugin Author Name

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 finding information on who to contact with queries.

Customers should be able to easily to differentiate a product purchased at WooCommerce.com from a product purchased elsewhere, just by looking through their plugin list in WordPress.

Thus, the following plugin headers should be in place:

• The Plugin Author isYourName/YourCompany
• The Developer header is YourName/YourCompany, with the Developer URI field listed as http://yourdomain.com/

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: Your Name
 * Author URI: http://yourdomain.com/
 * Developer: Your Name
 * Developer URI: http://yourdomain.com/
 * Text Domain: woocommerce-extension
 * Domain Path: /languages
 *
 * Woo: 12345:342928dfsfhsf8429842374wdf4234sfd
 * WC requires at least: 2.2
 * WC tested up to: 2.3
 *
 * License: GNU General Public License v3.0
 * License URI: http://www.gnu.org/licenses/gpl-3.0.html
 */

Declaring required and supported WooCommerce version

Use the follow headers to declare “required” and “tested up to” versions:

• WC requires at least
• WC tested up to

Plugin URI

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.

Woo Plugin Header For Updates

WooCommerce core looks for a Woo line in the plugin header comment, to ensure it can check for updates to your plugin, on WooCommerce.com. This line looks like this:

Woo: 12345:342928dfsfhsf8429842374wdf4234sfd

This is only required for products sold on WooCommerce.com.  Using this line for products listed on WordPress.org or elsewhere is not required or necessary.

For products sold on WooCommerce.com, Vendors can find this snippet by logging in to their logging in to the Vendors Dashboard and going to Extensions > All Extensions. Then, select the product and click Edit product page. This snippet will be in the upper-right-hand corner of the screen.

See the plugin header comment example above for how the Woo header looks in context.

Make it Extensible

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

If your plugin creates a front-end output, we recommend to having a templating engine in place so users can create custom template files in their theme’s WooCommerce folder to overwrite the plugin’s template files.

Remove Unused Code

With version control, there’s no reason to leave commented-out code; it’s annoying to scroll through and read. Remove it and add it back later if needed.

Comment

If you have a function, what does the function do? There should be comments for most if not all functions in your code. Someone/You may want to modify the plugin, and comments are helpful for that. We recommend using PHP Doc Blocks  similar to WooCommerce.

Avoid God Objects

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

Test Your Code with WP_DEBUG

Always develop with WP_DEBUG mode on, so you can see all PHP warnings sent to the screen. This will flag things like making sure a variable is set before checking the value.

Separate Business Logic & Presentation Logic

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

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

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.

Error codes

This information is intended for the third-party developers so products they write can better handle errors. Error codes are produced by the Product Build Server when uploading a new submission or updating an existing product on the Marketplace.

error_success

The operation has completed successfully.

error_pbs_prepare_apache

Internal error with the Product Build Server – cannot initialize the Apache daemon.

error_pbs_prepare_mysql

Internal error with the Product Build Server – cannot initialize the MySQL daemon.

error_pbs_prepare_wp

Internal error with the Product Build Server – cannot initialize WordPress.

error_pbs_prepare_wc

Internal error with the Product Build Server – cannot initialize WooCommerce.

error_pbs_prepare_dependencies

Internal error with the Product Build Server – cannot configure dependencies.

error_pbs_test_malware_scanning

Malware scanning error. This can happen if your product contains malware in the code.

Here’s an example output:

ObfuscatedPhp /tmp/product_clone/woocommerce-example/includes/views/html-settings-page.php
0x406:$ini_set:  ini_set(
0x506:$ini_set:  ini_set(
ObfuscatedPhp /tmp/product_clone/woocommerce-example/includes/views/html-extras-page.php
0x406:$eval:  exec(

This means that the character at the absolute position 0x406 (1030) and 0x506 (1286) in the file html-settings-page.php doesn’t pass the $ini_set rule, because it is using call_user_func in that file. Also, the other file html-extras-page.php doesn’t pass the rule $register_function which is using exec call.

error_pbs_test_extracting

Cannot extract the product. Most common issue is the top directory of the zip does not match its slug.

error_pbs_test_phpcs

phpcs checks failed. The check uses the WooCommerce-Core sniffs with following phpcs.xml:

To install locally:

1. Go to your product directory.
2. Install WooCommerce sniffs with composer require woocommerce/woocommerce-sniffs.
3. Put phpcs.xml above in the product directory.
4. Run ./vendor/bin/phpcs --warning-severity=0 -s --ignore-annotations --extensions=php,html . .

error_pbs_test_installing

Cannot install the product. Most common issue is the top directory of the zip does not match its slug.

error_pbs_test_activating

Cannot activate the product. Refer to the build output for more details.

error_pbs_test_deactivating

Cannot deactivate the product. Refer to the build output for more details.

error_pbs_test_host_plan_installing

This error means that your product is incompatible with other products in the host plan. Refer to the build output for more details.

error_pbs_test_host_plan_activating

This error means that your product is incompatible with other products in the host plan. Refer to the build output for more details.

error_pbs_test_host_plan_deactivating

This error means that your product is incompatible with other products in the host plan. Refer to the build output for more details.

error_pbs_missing_theme_info_file

Your theme is missing the theme info file theme_info.txt under the root directory.

error_pbs_incomplete_theme_info

Your theme info file theme_info.txt contains malformed data structure. It should contain the product ID, hash and main file, all separated by new lines. For example:

887931
2429c1dde521031cd053886b15844bbf
storechild/style.css

error_pbs_incomplete_theme_header

Your theme main file contains malformed data structure. Provide Theme Name, Version, and the Woo headers in your main file.

error_pbs_incomplete_plugin_header

Your plugin main file contains malformed data structure. Provide Plugin Name, Version, and the Woo headers in your main file.

error_pbs_invalid_woo_header

Your product main file contains an invalid Woo header structure. Use the format ID:HASH. For example:

 * Woo: 390890:911c438934af094c2b38d5560b9f50f3

error_pbs_invalid_id

Your product main file contains an invalid product ID in the Woo header.

error_pbs_invalid_hash

Your product main file contains an invalid hash in the Woo header.

error_pbs_missing_main_file

Your product is missing the main file.

error_pbs_missing_changelog_file

Your product is missing the changelog.txt file.

error_pbs_product_version_mismatch

The version in your product’s main file does not match with the provided version in changelog.txt.

error_pbs_invalid_changelog_format

Your product contains malformed changelog.txt structure. Refer to changelog.txt as an example.

The post WooCommerce Plugin Developer Handbook first appeared on CODIBU.