Imported from sayan08880/WORDPRESS-PROJECT (ECOMMERCE/wp-content/plugins/woocommerce-gateway-stripe/includes/AGENTS.md). Install upstream with npx skills add sayan08880/WORDPRESS-PROJECT --skill includes. Copyright stays with the author.

includes/AGENTS.md

Scope: applies to all PHP code under includes/.

For repository-wide rules, always read the root AGENTS.md first.

CRITICAL Rules

• CRITICAL: Keep WooCommerce and WordPress L-2 compatibility in mind for new PHP features.
• CRITICAL: Do not silently change option keys, action names, or filter names used externally.
• CRITICAL: If behavior changes, update or add PHPUnit coverage in tests/phpunit/.
• CRITICAL: Treat WordPress/WooCommerce and hook-derived values as untrusted (null|false|mixed) until validated.
• CRITICAL: Prefer focused changes in existing classes over large cross-cutting refactors.

Structure and Ownership

Core bootstrap and service wiring:

• includes/class-wc-stripe.php
• includes/class-wc-stripe-api.php
• includes/class-wc-stripe-intent-controller.php
• includes/class-wc-stripe-webhook-handler.php

Admin REST and settings:

• includes/admin/

Payment method implementations:

• includes/payment-methods/
• includes/payment-tokens/
• includes/constants/class-wc-stripe-payment-methods.php

Compatibility layers (subscriptions, pre-orders, other integrations):

• includes/compat/

Agentic Commerce feed integration:

• includes/agentic-commerce/

Task-to-Command Matrix

Backend Conventions

• Follow existing class naming/file naming conventions (class-wc-stripe-*.php, trait-wc-stripe-*.php).
• Use strict typing patterns that already exist in touched files.
• Keep translation wrappers and escaping patterns consistent with neighboring code.
• Keep hooks and side effects explicit. If adding hooks, ensure lifecycle placement is intentional.
• Use data providers for parameterized PHPUnit coverage.
• Define failure contracts for token/intent creation paths and handle failure explicitly at call sites.
• For amount conversion paths, round before integer casting and test edge precision cases.

Common Pitfalls

• Adding a payment method class without updating method registration/constants.
• Updating only one layer of a flow (for example gateway logic without webhook/intent handling).
• Treating PHPStan baseline updates as the first option instead of the last option.
• Changing compatibility behavior (subscriptions/pre-orders) without targeted tests.
• Calling methods on potential null/false token, order, or payment objects.
• In recurring-payment capable methods, missing subscriptions/pre-orders initialization or regression coverage.

Test Mapping

• General backend tests: tests/phpunit/
• Admin controller tests: tests/phpunit/Admin/
• Payment method tests: tests/phpunit/PaymentMethods/
• Payment token tests: tests/phpunit/PaymentTokens/

When adding a new backend class, add or update the closest mirrored test file.