Commit 13050b0f66 for woocommerce
commit 13050b0f661a32ddf89af1ea5892b61bf7783009
Author: Michael Pretty <prettyboymp@users.noreply.github.com>
Date: Wed Dec 10 07:59:52 2025 -0500
Add AI skill documentation for PHPStan type annotations (#62309)
Add type-annotations.md to woocommerce-backend-dev skill with guidance on:
- When to use PHPStan-specific annotations
- Generic types with @template
- @phpstan-param vs @param usage
- Common patterns (factory methods, containers)
- Suppressing false positives
This helps AI tools generate code with proper type annotations that
support static analysis, following the patterns established in #62301.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
diff --git a/.ai/skills/woocommerce-backend-dev/SKILL.md b/.ai/skills/woocommerce-backend-dev/SKILL.md
index 0971156498..0b08593223 100644
--- a/.ai/skills/woocommerce-backend-dev/SKILL.md
+++ b/.ai/skills/woocommerce-backend-dev/SKILL.md
@@ -14,10 +14,11 @@ 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
+4. **Type annotations**: See [type-annotations.md](type-annotations.md) for PHPStan-aware PHPDoc annotations
+5. **Working with hooks**: See [hooks.md](hooks.md) for hook callback conventions and documentation
+6. **Dependency injection**: See [dependency-injection.md](dependency-injection.md) for DI container usage
+7. **Data integrity**: See [data-integrity.md](data-integrity.md) for ensuring data integrity when performing CRUD operations
+8. **Writing tests**: See [unit-tests.md](unit-tests.md) for unit testing conventions
## Key Principles
diff --git a/.ai/skills/woocommerce-backend-dev/type-annotations.md b/.ai/skills/woocommerce-backend-dev/type-annotations.md
new file mode 100644
index 0000000000..87c2302d4b
--- /dev/null
+++ b/.ai/skills/woocommerce-backend-dev/type-annotations.md
@@ -0,0 +1,161 @@
+# Type Annotations for Static Analysis
+
+## Table of Contents
+
+- [Overview](#overview)
+- [When to Use PHPStan Annotations](#when-to-use-phpstan-annotations)
+- [Generic Types with @template](#generic-types-with-template)
+- [PHPStan-Specific Annotations](#phpstan-specific-annotations)
+- [Common Patterns](#common-patterns)
+- [Suppressing False Positives](#suppressing-false-positives)
+
+## Overview
+
+WooCommerce uses PHPStan for static analysis. Beyond standard PHPDoc annotations (`@param`, `@return`, `@var`), use PHPStan-specific annotations to provide richer type information that enables better type inference.
+
+## When to Use PHPStan Annotations
+
+Use PHPStan annotations when:
+
+- A method returns a type based on its input (generic/template types)
+- Standard PHPDoc cannot express the type relationship
+- You need to provide type information that PHP's type system cannot express
+
+## Generic Types with @template
+
+Use `@template` to declare generic type parameters. This enables PHPStan to infer return types based on input types.
+
+### Basic Pattern
+
+```php
+/**
+ * Get an instance of a class from the container.
+ *
+ * @template T of object
+ * @param string $class_name Class name.
+ * @phpstan-param class-string<T> $class_name
+ *
+ * @return T The instance of the requested class.
+ */
+public function get( string $class_name ) {
+ // ...
+}
+```
+
+**How it works:**
+
+1. `@template T of object` - Declares a type variable `T` constrained to objects
+2. `@phpstan-param class-string<T> $class_name` - The input is a class name string for type `T`
+3. `@return T` - The return type is the same `T` that was passed in
+
+**Result:** PHPStan knows that `$container->get( MyService::class )` returns `MyService`.
+
+### Constraint Options
+
+```php
+// Any object type
+@template T of object
+
+// Specific base class or interface
+@template T of WC_Product
+
+// No constraint (can be any type including scalars)
+@template T
+```
+
+## PHPStan-Specific Annotations
+
+### @phpstan-param vs @param
+
+Use both when you need PHPStan-specific type info while keeping standard documentation:
+
+```php
+/**
+ * @param string $class_name Class name to instantiate.
+ * @phpstan-param class-string<T> $class_name
+ */
+```
+
+- `@param string` - Standard PHPDoc (for IDEs and documentation generators)
+- `@phpstan-param class-string<T>` - PHPStan-specific (richer type info)
+
+### @phpstan-return
+
+Use when the return type is more specific than the declared type:
+
+```php
+/**
+ * @return object
+ * @phpstan-return T
+ */
+```
+
+### @phpstan-var
+
+Use for inline type assertions:
+
+```php
+/** @phpstan-var array<string, WC_Product> $products */
+$products = get_transient( 'cached_products' );
+```
+
+## Common Patterns
+
+### Factory Methods
+
+```php
+/**
+ * Create a new instance of a data store.
+ *
+ * @template T of WC_Data_Store
+ * @param string $object_type Object type (e.g., 'product', 'order').
+ * @phpstan-param class-string<T> $object_type
+ *
+ * @return T The data store instance.
+ */
+public static function load( string $object_type ) {
+ // ...
+}
+```
+
+### Container/Service Locator
+
+```php
+/**
+ * @template T of object
+ * @param string $id Service identifier.
+ * @phpstan-param class-string<T> $id
+ *
+ * @return T Service instance.
+ */
+public function get( string $id );
+```
+
+### Collections with Known Types
+
+```php
+/**
+ * @param array<int, WC_Order_Item> $items Order items.
+ * @return array<string, float> Item totals keyed by item type.
+ */
+public function calculate_totals( array $items ): array {
+ // ...
+}
+```
+
+## Suppressing False Positives
+
+When PHPStan reports an error that is a false positive (the code is correct but PHPStan cannot verify it), use inline ignores with explanations:
+
+```php
+// @phpstan-ignore return.type (method uses reflection to return correct type at runtime)
+return $this->create_instance( $class_name );
+```
+
+Common ignore identifiers:
+
+- `return.type` - Return type mismatch
+- `argument.type` - Argument type mismatch
+- `method.nonObject` - Method call on potentially non-object
+
+**Important:** Only use ignores when the code is genuinely correct. Prefer fixing the type annotations or code when possible.