mirror of
https://github.com/Sylius/Sylius.git
synced 2026-07-14 17:10:53 +00:00
157 lines
6.5 KiB
Markdown
157 lines
6.5 KiB
Markdown
# 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/`
|