|
| 1 | +# PrestaShop — AI Context (Root) |
| 2 | + |
| 3 | +> For folder structure and navigation, see [STRUCTURE.md](STRUCTURE.md). |
| 4 | +> For cross-domain naming traps and identity gotchas, see [GOTCHAS.md](GOTCHAS.md). |
| 5 | +> For multi-store scoping (ShopConstraint, AbstractMultistoreConfiguration), see [MULTISTORE.md](MULTISTORE.md). |
| 6 | +
|
| 7 | +## Project overview |
| 8 | + |
| 9 | +PrestaShop is an open-source e-commerce platform built on Symfony. It follows a progressive migration from a legacy architecture (ObjectModel, legacy controllers) toward a modern Domain-Driven Design approach (CQRS, Symfony controllers, Doctrine). |
| 10 | + |
| 11 | +## Architecture layers |
| 12 | + |
| 13 | +| Layer | Location | Role | |
| 14 | +|-------|----------|------| |
| 15 | +| Core Domain | `src/Core/Domain/` | Business logic: Commands, Queries, Handlers, ValueObjects, Exceptions | |
| 16 | +| Core Components | `src/Core/` (non-Domain) | Shared infrastructure: Grid, Form, Hook, Translation, etc. | |
| 17 | +| Adapter | `src/Adapter/` | Bridges between Core and legacy code or external systems | |
| 18 | +| PrestaShopBundle | `src/PrestaShopBundle/` | Symfony bundle: controllers, form types, Twig extensions, DI config | |
| 19 | +| Legacy | `classes/`, `controllers/` | Legacy ObjectModel classes and controllers — do not extend, migrate instead | |
| 20 | +| Admin front-end | `admin-dev/themes/new-theme/` | Back-office UI: Vue.js components, JavaScript, SCSS | |
| 21 | +| Front-office themes | `themes/` | Customer-facing Smarty templates | |
| 22 | +| Modules | `modules/` | Native and third-party modules | |
| 23 | +| Tests | `tests/` | PHPUnit (unit/integration), Behat (behavior), Playwright (UI) | |
| 24 | + |
| 25 | +## Coding standards |
| 26 | + |
| 27 | +- Every PHP file: `declare(strict_types=1);` |
| 28 | +- Classes `final` by default; all parameters, return types, and properties must be typed |
| 29 | +- No ObjectModel in new code — use Doctrine entities or CQRS commands |
| 30 | +- All services defined in YAML; no `new` in controllers |
| 31 | +- No `Db::getInstance()` in new code — use Doctrine repositories |
| 32 | +- No business logic in controllers — delegate to Handlers |
| 33 | +- Catch specific domain exceptions, not generic `\Exception` |
| 34 | + |
| 35 | +## CQRS pattern |
| 36 | + |
| 37 | +- **Commands** — write intentions dispatched via `CommandBus` |
| 38 | +- **Queries** — read intentions dispatched via `QueryBus` |
| 39 | +- **Handlers** — implement logic; never call other handlers (compose at controller level) |
| 40 | +- Handler interfaces in `src/Core/Domain/{Domain}/CommandHandler|QueryHandler/` |
| 41 | +- Concrete implementations in `src/Adapter/{Domain}/CommandHandler|QueryHandler/` |
| 42 | + |
| 43 | +## Testing |
| 44 | + |
| 45 | +| Type | Framework | Location | |
| 46 | +|------|-----------|----------| |
| 47 | +| Unit | PHPUnit | `tests/Unit/` | |
| 48 | +| Integration | PHPUnit | `tests/Integration/` | |
| 49 | +| Behavior | Behat | `tests/Integration/Behaviour/` | |
| 50 | +| UI | Playwright | `tests/UI/` | |
| 51 | + |
| 52 | +## Skills |
| 53 | + |
| 54 | +| Skill | Path | Trigger | |
| 55 | +|-------|------|---------| |
| 56 | +| `create-skill` | [skills/create-skill/SKILL.md](skills/create-skill/SKILL.md) | "create a skill for …" | |
| 57 | +| `domain-context-generator` | [skills/domain-context-generator/SKILL.md](skills/domain-context-generator/SKILL.md) | "generate context for [Domain]" | |
| 58 | +| `component-context-generator` | [skills/component-context-generator/SKILL.md](skills/component-context-generator/SKILL.md) | "generate context for [Component]" | |
| 59 | +| `create-form` | [skills/create-form/SKILL.md](skills/create-form/SKILL.md) | "create a form for [Entity]" | |
| 60 | + |
| 61 | +## Domain contexts |
| 62 | + |
| 63 | +All 57 domains under `src/Core/Domain/` have a context file. Read the relevant one before working in a domain. |
| 64 | + |
| 65 | +| Domain | Context | |
| 66 | +|--------|---------| |
| 67 | +| Address | [Domain/Address/CONTEXT.md](Domain/Address/CONTEXT.md) | |
| 68 | +| Alias | [Domain/Alias/CONTEXT.md](Domain/Alias/CONTEXT.md) | |
| 69 | +| ApiClient | [Domain/ApiClient/CONTEXT.md](Domain/ApiClient/CONTEXT.md) | |
| 70 | +| Attachment | [Domain/Attachment/CONTEXT.md](Domain/Attachment/CONTEXT.md) | |
| 71 | +| AttributeGroup | [Domain/AttributeGroup/CONTEXT.md](Domain/AttributeGroup/CONTEXT.md) | |
| 72 | +| Carrier | [Domain/Carrier/CONTEXT.md](Domain/Carrier/CONTEXT.md) | |
| 73 | +| Cart | [Domain/Cart/CONTEXT.md](Domain/Cart/CONTEXT.md) | |
| 74 | +| CartRule | [Domain/CartRule/CONTEXT.md](Domain/CartRule/CONTEXT.md) | |
| 75 | +| CatalogPriceRule | [Domain/CatalogPriceRule/CONTEXT.md](Domain/CatalogPriceRule/CONTEXT.md) | |
| 76 | +| Category | [Domain/Category/CONTEXT.md](Domain/Category/CONTEXT.md) | |
| 77 | +| CmsPage | [Domain/CmsPage/CONTEXT.md](Domain/CmsPage/CONTEXT.md) | |
| 78 | +| CmsPageCategory | [Domain/CmsPageCategory/CONTEXT.md](Domain/CmsPageCategory/CONTEXT.md) | |
| 79 | +| Combination | [Domain/Combination/CONTEXT.md](Domain/Combination/CONTEXT.md) — code lives under `src/Core/Domain/Product/Combination/`, not a standalone domain | |
| 80 | +| Configuration | [Domain/Configuration/CONTEXT.md](Domain/Configuration/CONTEXT.md) | |
| 81 | +| Contact | [Domain/Contact/CONTEXT.md](Domain/Contact/CONTEXT.md) | |
| 82 | +| Country | [Domain/Country/CONTEXT.md](Domain/Country/CONTEXT.md) | |
| 83 | +| CreditSlip | [Domain/CreditSlip/CONTEXT.md](Domain/CreditSlip/CONTEXT.md) | |
| 84 | +| Currency | [Domain/Currency/CONTEXT.md](Domain/Currency/CONTEXT.md) | |
| 85 | +| Customer | [Domain/Customer/CONTEXT.md](Domain/Customer/CONTEXT.md) | |
| 86 | +| CustomerMessage | [Domain/CustomerMessage/CONTEXT.md](Domain/CustomerMessage/CONTEXT.md) | |
| 87 | +| CustomerService | [Domain/CustomerService/CONTEXT.md](Domain/CustomerService/CONTEXT.md) | |
| 88 | +| Discount | [Domain/Discount/CONTEXT.md](Domain/Discount/CONTEXT.md) | |
| 89 | +| Employee | [Domain/Employee/CONTEXT.md](Domain/Employee/CONTEXT.md) | |
| 90 | +| Feature | [Domain/Feature/CONTEXT.md](Domain/Feature/CONTEXT.md) | |
| 91 | +| Hook | [Domain/Hook/CONTEXT.md](Domain/Hook/CONTEXT.md) | |
| 92 | +| ImageSettings | [Domain/ImageSettings/CONTEXT.md](Domain/ImageSettings/CONTEXT.md) | |
| 93 | +| Language | [Domain/Language/CONTEXT.md](Domain/Language/CONTEXT.md) | |
| 94 | +| MailTemplate | [Domain/MailTemplate/CONTEXT.md](Domain/MailTemplate/CONTEXT.md) | |
| 95 | +| Manufacturer | [Domain/Manufacturer/CONTEXT.md](Domain/Manufacturer/CONTEXT.md) | |
| 96 | +| Meta | [Domain/Meta/CONTEXT.md](Domain/Meta/CONTEXT.md) | |
| 97 | +| Module | [Domain/Module/CONTEXT.md](Domain/Module/CONTEXT.md) | |
| 98 | +| Notification | [Domain/Notification/CONTEXT.md](Domain/Notification/CONTEXT.md) | |
| 99 | +| Order | [Domain/Order/CONTEXT.md](Domain/Order/CONTEXT.md) | |
| 100 | +| OrderMessage | [Domain/OrderMessage/CONTEXT.md](Domain/OrderMessage/CONTEXT.md) | |
| 101 | +| OrderReturn | [Domain/OrderReturn/CONTEXT.md](Domain/OrderReturn/CONTEXT.md) | |
| 102 | +| OrderReturnState | [Domain/OrderReturnState/CONTEXT.md](Domain/OrderReturnState/CONTEXT.md) | |
| 103 | +| OrderState | [Domain/OrderState/CONTEXT.md](Domain/OrderState/CONTEXT.md) | |
| 104 | +| Position | [Domain/Position/CONTEXT.md](Domain/Position/CONTEXT.md) | |
| 105 | +| Product | [Domain/Product/CONTEXT.md](Domain/Product/CONTEXT.md) | |
| 106 | +| Profile | [Domain/Profile/CONTEXT.md](Domain/Profile/CONTEXT.md) | |
| 107 | +| Search | [Domain/Search/CONTEXT.md](Domain/Search/CONTEXT.md) | |
| 108 | +| SearchEngine | [Domain/SearchEngine/CONTEXT.md](Domain/SearchEngine/CONTEXT.md) | |
| 109 | +| Security | [Domain/Security/CONTEXT.md](Domain/Security/CONTEXT.md) | |
| 110 | +| Shipment | [Domain/Shipment/CONTEXT.md](Domain/Shipment/CONTEXT.md) | |
| 111 | +| Shop | [Domain/Shop/CONTEXT.md](Domain/Shop/CONTEXT.md) | |
| 112 | +| ShowcaseCard | [Domain/ShowcaseCard/CONTEXT.md](Domain/ShowcaseCard/CONTEXT.md) | |
| 113 | +| SqlManagement | [Domain/SqlManagement/CONTEXT.md](Domain/SqlManagement/CONTEXT.md) | |
| 114 | +| State | [Domain/State/CONTEXT.md](Domain/State/CONTEXT.md) | |
| 115 | +| Store | [Domain/Store/CONTEXT.md](Domain/Store/CONTEXT.md) | |
| 116 | +| Supplier | [Domain/Supplier/CONTEXT.md](Domain/Supplier/CONTEXT.md) | |
| 117 | +| Tab | [Domain/Tab/CONTEXT.md](Domain/Tab/CONTEXT.md) | |
| 118 | +| Tag | [Domain/Tag/CONTEXT.md](Domain/Tag/CONTEXT.md) | |
| 119 | +| Tax | [Domain/Tax/CONTEXT.md](Domain/Tax/CONTEXT.md) | |
| 120 | +| TaxRulesGroup | [Domain/TaxRulesGroup/CONTEXT.md](Domain/TaxRulesGroup/CONTEXT.md) | |
| 121 | +| Theme | [Domain/Theme/CONTEXT.md](Domain/Theme/CONTEXT.md) | |
| 122 | +| Title | [Domain/Title/CONTEXT.md](Domain/Title/CONTEXT.md) | |
| 123 | +| Webservice | [Domain/Webservice/CONTEXT.md](Domain/Webservice/CONTEXT.md) | |
| 124 | +| Zone | [Domain/Zone/CONTEXT.md](Domain/Zone/CONTEXT.md) | |
| 125 | + |
| 126 | +## Component contexts |
| 127 | + |
| 128 | +All 22 shared infrastructure components have a context file. |
| 129 | + |
| 130 | +| Component | Context | |
| 131 | +|-----------|---------| |
| 132 | +| BackOfficeHelp | [Component/BackOfficeHelp/CONTEXT.md](Component/BackOfficeHelp/CONTEXT.md) | |
| 133 | +| Configuration | [Component/Configuration/CONTEXT.md](Component/Configuration/CONTEXT.md) | |
| 134 | +| Console | [Component/Console/CONTEXT.md](Component/Console/CONTEXT.md) | |
| 135 | +| Context | [Component/Context/CONTEXT.md](Component/Context/CONTEXT.md) | |
| 136 | +| Cookie | [Component/Cookie/CONTEXT.md](Component/Cookie/CONTEXT.md) | |
| 137 | +| CQRS | [Component/CQRS/CONTEXT.md](Component/CQRS/CONTEXT.md) | |
| 138 | +| Database | [Component/Database/CONTEXT.md](Component/Database/CONTEXT.md) | |
| 139 | +| Export | [Component/Export/CONTEXT.md](Component/Export/CONTEXT.md) | |
| 140 | +| FacetedSearch | [Component/FacetedSearch/CONTEXT.md](Component/FacetedSearch/CONTEXT.md) | |
| 141 | +| Forms | [Component/Forms/CONTEXT.md](Component/Forms/CONTEXT.md) | |
| 142 | +| GlobalJS | [Component/GlobalJS/CONTEXT.md](Component/GlobalJS/CONTEXT.md) | |
| 143 | +| Grid | [Component/Grid/CONTEXT.md](Component/Grid/CONTEXT.md) | |
| 144 | +| Hook | [Component/Hook/CONTEXT.md](Component/Hook/CONTEXT.md) | |
| 145 | +| Import | [Component/Import/CONTEXT.md](Component/Import/CONTEXT.md) | |
| 146 | +| Link | [Component/Link/CONTEXT.md](Component/Link/CONTEXT.md) | |
| 147 | +| Locale | [Component/Locale/CONTEXT.md](Component/Locale/CONTEXT.md) | |
| 148 | +| MailTemplate | [Component/MailTemplate/CONTEXT.md](Component/MailTemplate/CONTEXT.md) | |
| 149 | +| PositionUpdater | [Component/PositionUpdater/CONTEXT.md](Component/PositionUpdater/CONTEXT.md) | |
| 150 | +| Router | [Component/Router/CONTEXT.md](Component/Router/CONTEXT.md) | |
| 151 | +| Smarty | [Component/Smarty/CONTEXT.md](Component/Smarty/CONTEXT.md) | |
| 152 | +| TinyMCE | [Component/TinyMCE/CONTEXT.md](Component/TinyMCE/CONTEXT.md) | |
| 153 | +| Twig | [Component/Twig/CONTEXT.md](Component/Twig/CONTEXT.md) | |
| 154 | + |
| 155 | +## Generated indexes |
| 156 | + |
| 157 | +Regenerate with `bash bin/generate-ai-index.sh`. **Read these before grepping** — they are pre-built snapshots faster than filesystem searches. **Regenerate after:** adding Commands/Queries, adding routes, adding hooks, or merging domain changes. |
| 158 | + |
| 159 | +| File | Contents | When to use | |
| 160 | +|------|----------|-------------| |
| 161 | +| [generated/cqrs.md](generated/cqrs.md) | All Commands + Queries grouped by domain | Before adding a Command/Query — check it doesn't already exist | |
| 162 | +| [generated/routes.md](generated/routes.md) | Symfony admin/API routes | Before adding a route or looking up a controller action | |
| 163 | +| [generated/entities.md](generated/entities.md) | Doctrine entity columns and relations | Before writing a query or migration | |
| 164 | +| [generated/hooks.md](generated/hooks.md) | Hook names discovered in source | Before dispatching or listening to a hook | |
0 commit comments