Skip to content
Tutorials Center
My learning

Topics

Lesson 2 of 39 ยท Getting Started

Development Environment and Tooling

Set up a local WooCommerce site with sample data, use WP-CLI, Query Monitor, WC_Logger and the status report, and add coding standards and IDE stubs.

Good WooCommerce development is mostly good feedback loops. You change a line, load a product page or place a test order, and need to see quickly what happened: which hooks ran, which queries were slow, what your code logged. A well-prepared local environment gives you those answers in seconds, while a poor one makes every bug a guessing game.

This lesson sets up the tools you will use for the rest of the track: a local site with realistic data, WP-CLI commands for WooCommerce, debug constants, Query Monitor, the WooCommerce logger and status report, and linting and IDE support. If you have not built a local WordPress site yet, read Local Environment and Debugging WordPress first.

None of these tools run on this site, so the commands below are read-only. The runnable examples at the end are stand-ins: a logger with levels and a threshold that copies how WC_Logger filters messages. They are not the real class.

A local site worth testing on

Use a local environment that gives you PHP, MySQL, a web server and HTTPS (Laravel Herd, Local, DDEV, wp-env or Docker all work). Then install WordPress and WooCommerce:

Terminal
# Read-only: run inside your WordPress folder
wp core install --url=https://shop.test --title="Dev Shop" \
   --admin_user=admin --admin_password=change-me --admin_email[email protected]
wp plugin install woocommerce --activate

An empty shop hides bugs. Import realistic data: WooCommerce ships a sample products CSV inside its plugin folder (look for a sample-data directory), which you can load from Products > Import. Add a few hand-made cases that stress your code:

  • a simple product, a variable product with 10+ variations, and an out-of-stock product
  • products with sale prices that start and end on dates
  • a coupon of each type, and at least two shipping zones
  • customers in different countries, to exercise taxes

Keep the commands that build this data in a script so you can rebuild the shop from scratch whenever it gets messy.

WP-CLI for WooCommerce

WooCommerce registers a wp wc command group that talks to the same code as the REST API. All of these need a user, because the REST permission checks still apply:

Terminal
# Read-only examples
wp wc product list --user=admin --fields=id,name,price,stock_status
wp wc product create --user=admin --name="Test Mug" --type=simple --regular_price=12.50
wp wc shop_order list --user=admin --fields=id,status,total
wp wc tool run install_pages --user=admin     # recreate shop/cart/checkout pages
wp wc tool run clear_transients --user=admin

Run wp wc --help to see every resource your version supports, and wp help wc product create for the fields of one command. Plain wp commands remain useful too: wp option get woocommerce_currency, wp transient delete --all, wp cron event list, and wp eval 'var_dump( wc_get_product( 12 )->get_price() );' to try a snippet against the loaded site. See WP-CLI for the basics.

Debug constants

In wp-config.php of your development site:

PHP
<?php
// Read-only: development settings
define( 'WP_DEBUG', true );
define( 'WP_DEBUG_LOG', true );        // writes wp-content/debug.log
define( 'WP_DEBUG_DISPLAY', false );   // keep notices out of AJAX and JSON responses
define( 'SCRIPT_DEBUG', true );        // load unminified core scripts
define( 'SAVEQUERIES', true );         // lets tools list queries (slower, dev only)

Never enable these on a live shop. Keeping display off while logging on is deliberate: PHP notices printed into a REST or admin-ajax.php response corrupt the JSON and produce confusing failures.

Query Monitor

The free Query Monitor plugin adds a toolbar menu showing, for each request: database queries (with the calling function and time), PHP errors, hooks fired, HTTP API calls, enqueued scripts and the template files used. For WooCommerce work these panels pay off immediately:

  • Queries by component reveals which plugin runs slow or duplicate queries.
  • Hooks and actions shows what is attached to a hook such as woocommerce_before_calculate_totals, in priority order.
  • Template files tells you which template a page really used, which settles override questions.
  • HTTP API calls exposes a gateway or shipping carrier request that is slowing checkout.

The WooCommerce logger

Use WooCommerce's own logger rather than error_log() for extension events. Messages land in log files you can browse under WooCommerce > Status > Logs, grouped by a source name you choose:

PHP
<?php
// Read-only: log from an extension
$logger  = wc_get_logger();
$context = array( 'source' => 'acme-bulk-discount' );

$logger->info( 'Applied tier discount', $context + array( 'order_id' => 123 ) );
$logger->error( 'Rate lookup failed: ' . $e->getMessage(), $context );
$logger->debug( 'Cart snapshot: ' . wp_json_encode( $snapshot ), $context );

The levels follow the PSR-3 convention, from most to least severe: emergency, alert, critical, error, warning, notice, info, debug. WooCommerce can be told to drop anything below a threshold level (there is a documented constant for this; check the developer docs for your version before relying on its exact name), so debug calls cost little on a live shop. Two habits matter:

  • Never log secrets or personal data: API keys, card data, full customer addresses. Logs are plain files that support staff may paste into tickets.
  • Add a source so your lines can be found and filtered.
flowchart LR
    A["Your code<br/>logger-&gt;info()"] --> B{"Level at or above<br/>threshold?"}
    B -->|yes| C["Handler<br/>(file by default)"]
    B -->|no| D["Dropped"]
    C --> E["Status > Logs screen"]

A log call passes a threshold check before any handler writes it.

The status report

WooCommerce > Status shows the environment WooCommerce sees: PHP and database versions, memory limit, active plugins and their versions, the active theme, whether templates are outdated (see Template Overrides), HPOS state, scheduled actions, and cron health. When a bug only happens on a client's site, ask for the Get system report output. It answers most "what is different there?" questions at once. The Tools tab holds actions such as clearing transients and re-creating pages.

Coding standards and IDE support

  • PHP_CodeSniffer with the WordPress Coding Standards (Composer package wp-coding-standards/wpcs) checks naming, spacing, escaping and security patterns. The WooCommerce project also publishes its own sniffs; look in the developer docs for the current package name.
  • Stub packages for IDEs: community Composer packages provide function and class signatures for WordPress and WooCommerce as development dependencies (composer require --dev php-stubs/woocommerce-stubs is the widely used one). They give you auto-completion and static-analysis support (PHPStan, Psalm) without loading the real plugin. Add them to require-dev only, never ship them.
  • Version control and Composer: keep your extension in its own Git repository with composer.json for autoloading and dev tools. See Plugin Structure and Object-Oriented Plugins.

A stand-in logger with levels

This is a small PSR-3-style logger with a threshold and a source, writing to an in-memory handler so you can see which messages survive.

PHP A logger with severity levels and a threshold

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.

With a warning threshold the debug and info messages vanish, while errors always remain. That is the same trade-off real stores make: verbose logging on a dev site, quiet logging in production.

A stand-in secret scrubber

Because logs must not hold secrets, many teams wrap the logger in a scrubber that masks sensitive keys before writing. This second example is a stand-in for that habit.

PHP Masking secrets before they reach a log

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 email survives, since it is the order's context in this toy example, while keys, tokens and passwords are masked. Real policies are stricter: decide per project what counts as personal data, and prefer not logging whole request bodies at all.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Why set WP_DEBUG_DISPLAY to false while WP_DEBUG_LOG is true?

    Notices printed into REST or admin-ajax responses break the output. Logging them to wp-content/debug.log keeps responses clean.
  2. 2. What does the source in a WC_Logger context do?

    The source names the log file group, which makes it easy to filter your extension's messages in the Logs screen.
  3. 3. Which tool shows which template file a page actually used and what is attached to a hook?

    Query Monitor lists queries, hooks, template files, HTTP calls and errors for the current request.
  4. 4. Which is NOT a good thing to put in a log message?

    Secrets such as API keys must never be logged, because log files get shared and are rarely protected like a database.
  5. 5. Why add stub packages like php-stubs/woocommerce-stubs as dev dependencies?

    Stubs declare signatures for completion and analysis only. They are for development and are not shipped.

Summary

  • A realistic local shop (variable products, coupons, zones, several countries) finds bugs an empty shop hides.
  • wp wc commands drive WooCommerce through the same code as the REST API; use wp eval to test snippets.
  • Log errors to debug.log with display off, and use Query Monitor to see queries, hooks and templates.
  • Use wc_get_logger() with a source, pick the right level, and never log secrets.
  • The status report is the first thing to request from a client; stubs and coding standards improve code quality.

Next: Your First WooCommerce Extension