Skip to content

jeffsenso/prestashop-skills / skills/prestashop-module-development

prestashop-module-development

Verified

Complete PrestaShop module development workflow using modern architecture and best practices. Use when: creating new PrestaShop modules, updating legacy modules to modern code, implementing hooks and actions, setting up module configuration pages, adding front office features, handling database operations, implementing security measures, managing translations, creating cart rules and vouchers, building Symfony console commands, or modernizing existing PrestaShop modules from legacy patterns to current standards.

FileKindSize
CHANGELOG.mdmarkdown12.9 KB
README.mdmarkdown3.5 KB
SKILL.mdskill md21.7 KB
ps9-core-ai/CONTEXT.mdmarkdown6.4 KB
ps9-core-ai/Component/BackOfficeHelp/CONTEXT.mdmarkdown1.0 KB
ps9-core-ai/Component/Behat/CONTEXT.mdmarkdown7.7 KB
ps9-core-ai/Component/CQRS/CONTEXT.mdmarkdown6.8 KB
ps9-core-ai/Component/Configuration/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Component/Console/CONTEXT.mdmarkdown1.1 KB
ps9-core-ai/Component/Context/CONTEXT.mdmarkdown1.8 KB
ps9-core-ai/Component/ContextStateManager/CONTEXT.mdmarkdown2.0 KB
ps9-core-ai/Component/Controller/CONTEXT.mdmarkdown4.7 KB
ps9-core-ai/Component/Cookie/CONTEXT.mdmarkdown1.3 KB
ps9-core-ai/Component/Database/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Component/Export/CONTEXT.mdmarkdown964 B
ps9-core-ai/Component/FacetedSearch/CONTEXT.mdmarkdown1.3 KB
ps9-core-ai/Component/Forms/CONTEXT.mdmarkdown6.1 KB
ps9-core-ai/Component/Grid/CONTEXT.mdmarkdown5.2 KB
ps9-core-ai/Component/Hook/CONTEXT.mdmarkdown1.1 KB
ps9-core-ai/Component/Import/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Component/Javascript/CONTEXT.mdmarkdown3.9 KB
ps9-core-ai/Component/Link/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Component/Locale/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Component/MailTemplate/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Component/Migration/CONTEXT.mdmarkdown10.6 KB
ps9-core-ai/Component/Playwright/CONTEXT.mdmarkdown6.4 KB
ps9-core-ai/Component/PositionUpdater/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Component/Router/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Component/Smarty/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Component/TinyMCE/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Component/Twig/CONTEXT.mdmarkdown3.9 KB
ps9-core-ai/Domain/Address/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/Alias/CONTEXT.mdmarkdown1.3 KB
ps9-core-ai/Domain/ApiClient/CONTEXT.mdmarkdown1.9 KB
ps9-core-ai/Domain/Attachment/CONTEXT.mdmarkdown1.2 KB
ps9-core-ai/Domain/AttributeGroup/CONTEXT.mdmarkdown1.9 KB
ps9-core-ai/Domain/Carrier/CONTEXT.mdmarkdown1.8 KB
ps9-core-ai/Domain/Cart/CONTEXT.mdmarkdown2.1 KB
ps9-core-ai/Domain/CartRule/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/CatalogPriceRule/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Category/CONTEXT.mdmarkdown1.8 KB
ps9-core-ai/Domain/CmsPage/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/CmsPageCategory/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Combination/CONTEXT.mdmarkdown2.4 KB
ps9-core-ai/Domain/Configuration/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Contact/CONTEXT.mdmarkdown1.2 KB
ps9-core-ai/Domain/Country/CONTEXT.mdmarkdown1.8 KB
ps9-core-ai/Domain/CreditSlip/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Domain/Currency/CONTEXT.mdmarkdown1.9 KB
ps9-core-ai/Domain/Customer/CONTEXT.mdmarkdown2.0 KB
ps9-core-ai/Domain/CustomerMessage/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/CustomerService/CONTEXT.mdmarkdown2.3 KB
ps9-core-ai/Domain/Discount/CONTEXT.mdmarkdown2.4 KB
ps9-core-ai/Domain/Employee/CONTEXT.mdmarkdown2.3 KB
ps9-core-ai/Domain/Feature/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/Hook/CONTEXT.mdmarkdown1.1 KB
ps9-core-ai/Domain/ImageSettings/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Language/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/MailTemplate/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Manufacturer/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Meta/CONTEXT.mdmarkdown1.9 KB
ps9-core-ai/Domain/Module/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/Notification/CONTEXT.mdmarkdown1.3 KB
ps9-core-ai/Domain/Order/CONTEXT.mdmarkdown2.6 KB
ps9-core-ai/Domain/OrderMessage/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/OrderReturn/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/OrderReturnState/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/OrderState/CONTEXT.mdmarkdown1.9 KB
ps9-core-ai/Domain/Position/CONTEXT.mdmarkdown996 B
ps9-core-ai/Domain/Product/CONTEXT.mdmarkdown2.7 KB
ps9-core-ai/Domain/Profile/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Search/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/SearchEngine/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Security/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Shipment/CONTEXT.mdmarkdown1.8 KB
ps9-core-ai/Domain/Shop/CONTEXT.mdmarkdown2.0 KB
ps9-core-ai/Domain/ShowcaseCard/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Domain/SqlManagement/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/State/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Store/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Supplier/CONTEXT.mdmarkdown2.1 KB
ps9-core-ai/Domain/Tab/CONTEXT.mdmarkdown1.5 KB
ps9-core-ai/Domain/Tag/CONTEXT.mdmarkdown1.4 KB
ps9-core-ai/Domain/Tax/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/TaxRulesGroup/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Theme/CONTEXT.mdmarkdown1.7 KB
ps9-core-ai/Domain/Title/CONTEXT.mdmarkdown1.6 KB
ps9-core-ai/Domain/Webservice/CONTEXT.mdmarkdown1.9 KB
ps9-core-ai/Domain/Zone/CONTEXT.mdmarkdown1.3 KB
ps9-core-ai/GOTCHAS.mdmarkdown3.9 KB
ps9-core-ai/MULTISTORE.mdmarkdown3.1 KB
ps9-core-ai/STRUCTURE.mdmarkdown11.1 KB
ps9-core-ai/bin/generate-ai-index.shscript17.9 KB
ps9-core-ai/generated/cqrs.mdmarkdown16.1 KB
ps9-core-ai/generated/entities.mdmarkdown2.7 KB
ps9-core-ai/generated/hooks.mdmarkdown3.7 KB
ps9-core-ai/generated/routes.mdmarkdown88.8 KB
references/cart-rules.mdmarkdown8.9 KB
references/configuration-management.mdmarkdown11.9 KB
references/configuration-page.mdmarkdown11.0 KB
references/database-and-entities.mdmarkdown5.7 KB
references/debugging.mdmarkdown5.9 KB
references/entity-doctrine.mdmarkdown12.5 KB
references/forms.mdmarkdown8.5 KB
references/grid-system.mdmarkdown41.0 KB
references/hooks-and-front-office.mdmarkdown8.2 KB
references/legacy-conversion.mdmarkdown3.5 KB
references/module-class-and-installer.mdmarkdown13.7 KB
references/module-structure.mdmarkdown3.4 KB
references/security.mdmarkdown2.4 KB
references/services-and-di.mdmarkdown20.8 KB
references/services-split.mdmarkdown6.0 KB
references/theme-template-injection.mdmarkdown7.4 KB
references/translations.mdmarkdown8.6 KB
references/validation.mdmarkdown2.5 KB
scripts/grid.bundle.jsscript4.4 KB
scripts/translatable-form.bundle.jsscript9.8 KB

references/debugging.md

View on GitHub
# Debugging & failure modes

## Module installation issues

| Symptom | Likely cause | Fix |
|---|---|---|
| `Attempted to load class … Did you forget a use statement?` | Missing `require_once __DIR__ . '/vendor/autoload.php';` | Add it right after the `_PS_VERSION_` guard |
| `Call to undefined method` | Wrong namespace / missing `use` | Check namespace in `composer.json` and class files |
| DB error during install | Bad SQL in `Installer` or `ConfigurationInstaller` | Review `install()` SQL, ensure tables don't already exist |
| Hook not triggered | Hook not registered in `Installer` | Add to `$hooks` array, run `pr:mo install` again |

## Configuration page problems

| Symptom | Likely cause | Fix |
|---|---|---|
| Blank page / 500 on config route | Missing service definition | Check `config/services.yml`, run `cache:clear` |
| Form not saving | `DataConfiguration::updateConfiguration()` has a bug | Add error logging; check `validateConfiguration()` |
| Redirect loop | `getContent()` returning HTML instead of redirecting | Use `Tools::redirectAdmin($router->generate(...))` |
| "Unknown filter string" Twig error | `\|string` does not exist in Twig | Use `~ ''` string concatenation trick instead |

## Form field issues

| Symptom | Likely cause | Fix |
|---|---|---|
| `Expected a numeric` on `IntegerType` | Empty string from database or empty field | See [forms.md](forms.md#%EF%B8%8F-integertype-with-optionalempty-values) — use `0` instead of `''` |
| `Argument #2 must be of type array, string given` in FormType | Wrong `trans()` signature | Use `trans($key, $domain)` NOT `trans($key, [], $domain)` — see [translations.md](translations.md#%EF%B8%8F-critical-prestashop-custom-trans-signatures) |
| `Argument #3 must be of type array, string given` in Controller | Wrong `trans()` signature | Use `trans($key, $domain, [])` with empty array as 3rd param — see [translations.md](translations.md#%EF%B8%8F-critical-prestashop-custom-trans-signatures) |
| Boolean toggle renders as plain radio | Using `RadioType` instead of `SwitchType` | Use `SwitchType` — see [forms.md](forms.md#boolean--toggle-fields--always-use-switchtype-never-radiotype) |
| Constraint validation message not translated | Using `trans()` in constraint message | Use plain string in constraint; Symfony handles translation separately |

## Grid system issues

| Symptom | Likely cause | Fix |
|---|---|---|
| "Service not found" on Grid factory | Service not defined in `services.yml` | Add all 5 Grid services (factory, query, data, grid, position) |
| Toggle AJAX fails | Route param mismatch | `route_param_name` in `ToggleColumn` must match controller param name exactly |
| Sort / reset / row click / drag-and-drop do nothing | Grid script not loaded, or grid not initialised | Network: `{modulename}.bundle.js` must be 200; console: `#{GRID_ID}_grid` must have `data-grid-initialized="1"`; the script must come after `{{ parent() }}` in `{% block javascripts %}` |
| Reset clicked, no `admin_common_reset_search_by_filter_id` in `var/logs/dev-*.log` | Grid initialised on `DOMContentLoaded`, before the admin theme creates `window.prestashop.component` | Initialise in a jQuery ready callback (`window.jQuery(function () {...})`), as `scripts/grid.bundle.js` does |
| Toggle/position silently broken (404 on the grid script) | Module folder name typo in asset path | Asset path must be `../modules/{exact-folder-name}/views/js/{modulename}.bundle.js`; a single character difference (e.g. underscore) causes a silent 404 |
| Toggle reverts / DB unchanged although the UI says success | Two toggle handlers on the same switch | Grid script loaded twice, or `ColumnTogglingExtension` added next to `AsyncToggleColumnExtension` — keep one script and `AsyncToggleColumnExtension` only |
| Delete row / reset / refresh / show SQL do nothing, sort works | Module ships an old minified webpack bundle (`new o.a("…")`) copied from the previous template (truncated, bootstrap never runs) | Overwrite `views/js/*.bundle.js` with `scripts/grid.bundle.js` — file name and `<script>` tag unchanged |
| PHPStan: `getFilters()` return type | Returning concrete `FilterCollection` | Change return type to `FilterCollectionInterface` |
| PHPStan: `getGridActions()` return type | Returning concrete `GridActionCollection` | Change return type to `GridActionCollectionInterface` |

## InputBag issues (Symfony HTTP Foundation)

| Symptom | Likely cause | Fix |
|---|---|---|
| `Unexpected value for parameter … default must be scalar` | `$request->request->get('key', [])` — non-scalar default | Use `$request->request->all()` (no argument), then extract key manually |
| `Unexpected value for parameter` with `all('key')` | Value is not actually an array | Use `$request->request->all()` with no key, then `$data['key'] ?? null` |

## ImageManager::validateUpload issues

Pass the full `$_FILES`-compatible array including `type`, `size`, `error` — not just `tmp_name` and `name`:

```php
$fileData = [
    'name'     => $_FILES['photo']['name'],
    'tmp_name' => $_FILES['photo']['tmp_name'],
    'type'     => mime_content_type($_FILES['photo']['tmp_name']) ?: 'application/octet-stream',
    'size'     => $_FILES['photo']['size'],
    'error'    => $_FILES['photo']['error'],
];
```

## Performance problems

- Avoid loading CSS/JS on every back-office page — check `Tools::getValue('controller')` first.
- Use `_PS_USE_SQL_SLAVE_` for SELECT queries.
- Use `$this->isCached()` pattern for widget templates.
- Avoid N+1 queries in loops — fetch related data in bulk.

## lotr step failures

| lotr step | Common failure | Fix |
|---|---|---|
| autoindex | Missing `index.php` in a subdirectory | lotr auto-adds them; re-run |
| PS validator | Copyright year mismatch (2007-2019 vs 2007-2026) | `sed -i 's/2007-2019/2007-2026/g' views/js/myfile.bundle.js` |
| PHPStan | Return type errors, missing `use` imports | Fix reported types, add missing imports |
| PHP-CS-Fixer | Code style violations | lotr auto-fixes most; review diffs |
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall