playbooks

home / skills / secondsky / claude-skills / woocommerce-backend-dev

woocommerce-backend-dev skill

/plugins/woocommerce-backend-dev/skills/woocommerce-backend-dev

This skill guides backend WooCommerce PHP development, ensuring code follows project conventions, naming, hooks, tests, and WordPress standards.

npx playbooks add skill secondsky/claude-skills --skill woocommerce-backend-dev

Review the files below or copy the command above to add this skill to your agents.

Files (1)
SKILL.md
2.1 KB
---
name: woocommerce-backend-dev
description: Add or modify WooCommerce backend PHP code following project conventions. Use when creating new classes, methods, hooks, or modifying existing backend code in WooCommerce projects.
---

# WooCommerce Backend Development

This skill provides guidance for developing WooCommerce backend PHP code according to project standards and conventions.

## Instructions

Follow WooCommerce project conventions when adding or modifying backend PHP code:

1. **Creating new code structures**: See [file-entities.md](file-entities.md) for conventions on creating classes and organizing files (but for new unit test files see [unit-tests.md](unit-tests.md)).
2. **Naming conventions**: See [code-entities.md](code-entities.md) for naming methods, variables, and parameters
3. **Coding style**: See [coding-conventions.md](coding-conventions.md) for general coding standards and best practices
4. **Working with hooks**: See [hooks.md](hooks.md) for hook callback conventions and documentation
5. **Dependency injection**: See [dependency-injection.md](dependency-injection.md) for DI container usage
6. **Data integrity**: See [data-integrity.md](data-integrity.md) for ensuring data integrity when performing CRUD operations
7. **Writing tests**: See [unit-tests.md](unit-tests.md) for unit testing conventions

## Key Principles

- Always follow WordPress Coding Standards
- Use class methods instead of standalone functions
- Place new internal classes in `src/Internal/` by default
- Use PSR-4 autoloading with `Automattic\WooCommerce` namespace
- Write comprehensive unit tests for new functionality
- Run linting and tests before committing changes
- Prefer bun over npm/bunx for Node.js package management when applicable

## Version Information

To determine the next WooCommerce version number for `@since` annotations:

- Read the `$version` property in `includes/class-woocommerce.php` **on the trunk branch**
- Remove the `-dev` suffix if present
- Example: If trunk shows `10.4.0-dev`, use `@since 10.4.0`
- Note: When reviewing PRs against trunk, the version in trunk is correct even if it seems "future" relative to released versions

Overview

This skill guides developers to add or modify WooCommerce backend PHP code following the project conventions and standards. It focuses on class-based development, PSR-4 autoloading, dependency injection, and unit testing to ensure maintainable and production-ready backend changes.

How this skill works

The skill inspects the requested backend change and maps it to the project conventions: file placement, naming, hook usage, and test requirements. It enforces class-based implementations under the Automattic\WooCommerce namespace, recommends placing new internal classes in src/Internal, and provides steps for dependency injection and data integrity checks. It also explains how to determine correct @since version annotations from the trunk version.

When to use it

  • Creating new backend classes, services, or controllers for WooCommerce functionality.
  • Adding or modifying hook callbacks, filters, or actions in backend code.
  • Refactoring existing backend functions into class methods following project conventions.
  • Implementing or updating dependency injection registrations and container usage.
  • Adding or updating unit tests for backend logic and data integrity checks.

Best practices

  • Follow WordPress Coding Standards and PSR-4 autoloading with Automattic\WooCommerce namespace.
  • Prefer class methods over standalone functions and place new internals in src/Internal.
  • Use dependency injection via the project DI container for testable, decoupled code.
  • Ensure data integrity for CRUD operations by following project data-integrity patterns.
  • Write comprehensive unit tests and run linting and test suites before committing.

Example use cases

  • Add a new payment gateway backend class, register it with DI, and write unit tests validating behavior.
  • Refactor a procedural order validation function into a namespaced class with proper @since annotation.
  • Implement a new admin hook that modifies order metadata using class methods and documented callbacks.
  • Create a service to sync product data with external APIs, placed in src/Internal and covered by unit tests.

FAQ

How do I determine the @since version for a new class or method?

Read the $version property in includes/class-woocommerce.php on the trunk branch, remove any -dev suffix, and use that value for @since annotations.

Where should I put new internal classes?

Place new internal classes in src/Internal/ by default and use the Automattic\WooCommerce namespace with PSR-4 autoloading.

Are standalone functions allowed?

Prefer class methods instead of standalone functions; use standalone functions only when project conventions explicitly permit them.