# AI Contribution Guidelines

Guidelines for AI assistants contributing to Sylius.

## Reference Files

When working on specific areas, check these files for patterns:

### Entities & Models
- Entity pattern: `src/Sylius/Component/Core/Model/Product.php`
- Interface pattern: `src/Sylius/Component/Core/Model/ProductInterface.php`
- Doctrine mapping: `src/Sylius/Bundle/CoreBundle/Resources/config/doctrine/model/`

### API Platform 4.x
- Resource definitions: `src/Sylius/Bundle/ApiBundle/Resources/config/api_platform/resources/`
- Properties/serialization: `src/Sylius/Bundle/ApiBundle/Resources/config/api_platform/properties/`
- Admin resources: `resources/admin/Product.xml`
- Shop resources: `resources/shop/Product.xml`

### Services & Configuration
- Service definitions: `src/Sylius/Bundle/CoreBundle/Resources/config/services.xml`
- Bundle config: `src/Sylius/Bundle/*/Resources/config/`

### Templates & Hooks
- Admin templates: `src/Sylius/Bundle/AdminBundle/templates/`
- Shop templates: `src/Sylius/Bundle/ShopBundle/templates/`
- Twig hooks: check existing hooks in templates for naming patterns

### Tests
- PHPUnit functional: `tests/Functional/`
- PHPUnit API: `tests/Api/`
- Behat contexts: `src/Sylius/Behat/Context/`

### Migrations
- Location: `src/Sylius/Bundle/CoreBundle/Migrations/`
- **ALWAYS create TWO migrations**: one for MySQL, one for PostgreSQL
- MySQL: extend `Sylius\Bundle\CoreBundle\Doctrine\Migrations\AbstractMigration`
- PostgreSQL: extend `Sylius\Bundle\CoreBundle\Doctrine\Migrations\AbstractPostgreSQLMigration`
- When reviewing PRs that touch migrations, verify both versions exist

## General Guidelines

### Project Structure & Design

- Sylius is an e-commerce framework built on **Symfony**
- Bundles and Components can be used independently
- Follow the Sylius Backward Compatibility (BC) policy
- When changing interfaces, always provide BC layer

### Compatibility & Security

- Ensure compatibility with **Symfony** and **PHP** versions defined in `composer.json`
- For API configuration, use **API Platform 4.x**
- Follow secure coding practices to prevent XSS, CSRF, injections, auth bypasses, etc.

### Coding Standards & Tooling

- Use **4 spaces** for indentation in all files (PHP, YAML, XML, Twig, etc.)
- Use **PHPUnit** for unit and functional testing
- Use **Behat** for behavior-driven scenarios
- Use **ECS** to ensure consistent code style
- Use **PHPStan** for static analysis
- Use **CI** to run all tests and checks automatically

## Commands

- Run `composer install` to install PHP dependencies
- Run `vendor/bin/ecs` to fix PHP code style issues
- Run `vendor/bin/phpstan analyse` to perform static analysis
- Run `vendor/bin/phpunit` to execute unit and functional tests
- Run `yarn install` to install JavaScript dependencies
- Run `yarn encore dev` to compile frontend assets

## PHP Code

- Use modern PHP 8.2+ syntax and features
- Declare `strict_types=1` in all PHP files
- Follow the **Sylius Coding Standard**
- Do not use deprecated features from PHP, Symfony, or Sylius
- Use `final` for all classes, except entities and repositories
- Use `readonly` for immutable services and value objects
- Add type declarations for all properties, arguments, and return values
- Use `camelCase` for variables and method names
- Use `SCREAMING_SNAKE_CASE` for constants
- Use `snake_case` for configuration keys, route names, and template variables
- Use **fast returns** instead of nesting logic unnecessarily
- Use trailing commas in multi-line arrays and argument lists
- Order array keys alphabetically where applicable
- Use PHPDoc only when necessary (e.g. `@var Collection<ProductInterface>`)
- Group class elements in this order: constants, properties, constructor, public methods, protected methods, private methods
- Group getter and setter methods for the same properties together
- Suffix interfaces with Interface, traits with Trait
- Use `use` statements for all non-global classes
- Sort `use` imports alphabetically and group by type (classes, functions, constants)

## Templates and Hooks

- Use modern HTML5 syntax
- Always use the most modern Twig syntax and features
- Icon names must be from the Tabler 1.x library
- Use `snake_case` for all template directory and file names
- Use `snake_case` for all variable names in Twig files
- Ensure the directory structure under `templates/` matches the structure of the corresponding Twig hooks
- Use translations for all strings in templates, never hardcode text

## API

- Define resources in `admin/` and `shop/` folders accordingly
- Define operations in the following order: `get collection`, `get item`, `post`, `put`, `patch`, `delete`
- Define resource serialization in the `serialization/` folder
- Use serialization groups for: `index`, `show`, `create`, `update`
- Use **PHPUnit** tests to validate API configuration and API responses

## PHPUnit

- Place unit tests in `tests/Unit/`
- Place functional tests in `tests/Functional/`
- Place API tests in `tests/Api/`
- Test class names must end with `Test` suffix
- Use `#[Covers]` attribute for unit tests
- For API tests, extend `ApiTestCase` and use `assertResponse*` methods
- Run specific test: `vendor/bin/phpunit --filter TestClassName`

## Behat

- Place feature files in `features/` directory
- Use existing contexts from `src/Sylius/Behat/Context/`
- Follow Given-When-Then pattern strictly
- Use `@ui` tag for UI tests, `@api` for API tests
- Page objects are in `src/Sylius/Behat/Page/`

## JavaScript

- Use TypeScript where possible
- Use Stimulus controllers for interactive components
- Place controllers in `assets/admin/controllers/` or `assets/shop/controllers/`
- Follow existing naming conventions for controller files

## CSS

- Use SCSS (`.scss`) syntax – plain CSS files are not allowed
- Use Bootstrap 5 utility classes where possible
- Keep component styles modular – 1 component = 1 partial
- Use variables from Sylius theme
- Place all theme variables in `_variables.scss`
- Avoid `!important` unless absolutely necessary
- Prefer `rem` over `px` for spacing, font size, etc.
- Use `mixins/` for reusable logic (e.g., `@include icon-size(24px)`)

## Common Mistakes to Avoid

- **BC breaks**: Never change method signatures in interfaces without deprecation layer
- **Missing Doctrine mapping**: New entity properties need XML mapping in `Resources/config/doctrine/`
- **Hardcoded strings**: Always use translation keys in templates
- **Missing serialization groups**: API properties need proper groups in `properties/*.xml`
- **Wrong namespace**: Components have no Symfony dependency, Bundles can
- **Forgetting tests**: API changes need PHPUnit tests in `tests/Api/`