README

The ultimate PrestaShop developer tool to test and fix module source code to best fit the PrestaShop Online Module Validator standards.

Support

Built for PrestaShop 8.x & 9.x

Installation

1. Add as a Composer dev dependency

From your module root, run:

composer require --dev websenso/prestashop-module-devtools:^1

Or add it manually to your composer.json:

"require-dev": {
    "websenso/prestashop-module-devtools": "^1"
}

Then run composer install.

2. Run the setup command

After installation, run the setup command from your module root to:

• Create the validator-api config file and optionally save your API key
• Download and install the prestashop-module-development skill (via npx skills add if available, or a sparse git clone fallback from jeffsenso/prestashop-skills)
• Download the PrestaShop 9 core AI context into skills/<skill-path>/ps9-core-ai/ (sparse clone of the .ai/ folder from PrestaShop/PrestaShop@develop)
• Write .instructions.md (AI coding assistant instructions) to your project root, pointing to the installed skill path
• Copy .gitlab-ci.yml (example CI pipeline) to your project root

php vendor/bin/lotr --install

.instructions.md is always overwritten with the correct skill path. The skill and ps9-core-ai/ prompt to update if already present. All other files are only created if they do not already exist.

Re-run lotr --install at any time to update the skill and ps9-core-ai/ to the latest version.

3. Configure the licence header stamp

Edit vendor/websenso/prestashop-module-devtools/header-stamp/license_header.txt to set your licence header. Optionally edit license_header_phpDocs.txt as well.

4. Validator API key (online validation only)

If you skipped the API key during --install, edit: vendor/websenso/prestashop-module-devtools/validator-api/config/config.yaml

Get a free API key from https://validator.prestashop.com/.

5. GitLab pipeline

An example CI pipeline for PHP 8 / PrestaShop 8 is available at: vendor/websenso/prestashop-module-devtools/gitlab/.gitlab-ci.yml

It is automatically copied to your project root by --install.

Usage

Run from your module root:

php vendor/bin/lotr
php vendor/bin/lotr --dry-run

LOTR Options

Flag	Effect
(none)	Apply all fixes
--dry-run	Preview changes without writing anything
--install	Set up config and copy example files to project root
--release	Create a release ZIP after all tools pass
--validate-online	Submit the ZIP to validator.prestashop.com
--release --validate-online	Full release workflow

What LOTR Runs

1. AutoIndex

   vendor/bin/autoindex prestashop:add:index --exclude=vendor,tests,.devtools,_dev
   

2. Header Stamp

   php vendor/websenso/prestashop-module-devtools/header-stamp/bin/smart-header-stamp [--dry-run]
   

3. PS Version Checker

   php vendor/websenso/prestashop-module-devtools/psversion-checker/bin/psversion-checker fix [--dry-run]
   

4. PS Validator

   php vendor/websenso/prestashop-module-devtools/homemade-ps-validator/bin/homemade-ps-validator validate [--dry-run]
   

5. PHPStan

   _PS_ROOT_DIR_=<prestashop_root> vendor/bin/phpstan analyse --configuration=vendor/websenso/prestashop-module-devtools/phpstan/phpstan.neon
   

6. PHP-CS-Fixer

   vendor/bin/php-cs-fixer fix --config=vendor/websenso/prestashop-module-devtools/.php-cs-fixer.dist.php [--dry-run]
   

After all steps pass, optional post-processing runs:

1. Release ZIP creator (with --release)

   php vendor/websenso/prestashop-module-devtools/release-zip-creator/bin/create-release
   

2. Online validation (with --validate-online)

   php vendor/websenso/prestashop-module-devtools/validator-api/bin/validate-online
   

AI Assistant integration

Quick start — add your naming conventions: Edit vendor/websenso/prestashop-module-devtools/steering/frameworks/prestashop/custom-patterns.md to set your table prefix, admin tab group, and namespace. The AI assistant loads this file automatically on every task.

The package ships a steering layer (always available in vendor/) and --install downloads two more context layers. Together they write a .instructions.md to your project root that tells the AI assistant to load all three before starting any task.

Note: skills/ is intentionally empty in the Composer package. Skills are never bundled — they are always downloaded fresh by lotr --install.

Layer 0 — Steering (shipped with the package)

Included in the Composer package at vendor/websenso/prestashop-module-devtools/steering/. No download required.

File	Topic
steering/resolver.md	Load order and conflict resolution rules
steering/frameworks/prestashop/architecture.md	Module layout, DI, Doctrine ORM, FixturesInstaller, theme template injection, translations, Grid gotchas
steering/frameworks/prestashop/coding-standards.md	PHPCS, Symfony patterns, SQL rules, forbidden list
steering/frameworks/prestashop/custom-patterns.md	Company-specific conventions: table prefix, admin tab group, namespace, validation, service guard patterns

custom-patterns.md ships with Websenso defaults. To apply your own team's naming conventions, edit the file directly at:

vendor/websenso/prestashop-module-devtools/steering/frameworks/prestashop/custom-patterns.md

For per-module overrides (e.g. a specific module that deviates from the team standard), use layer 4: create .ai/projects/<module-slug>/project-context.md at your project root. Rules defined there win over custom-patterns.md.

Layer 1 — prestashop-module-development skill

Downloaded from jeffsenso/prestashop-skills:

• Primary: npx skills add → installs to skills/.agents/skills/prestashop-module-development/
• Fallback: sparse git clone → installs to skills/prestashop-module-development/

The .instructions.md written to your project root is automatically updated to point to whichever path was used.

Layer 2 — PrestaShop 9 core AI context (ps9-core-ai/)

Sparse-cloned from PrestaShop/PrestaShop@develop (.ai/ sub-tree only). Placed at skills/<skill-path>/ps9-core-ai/. Provides domain and component contexts for the entire PS9 codebase (~50 domains: CQRS commands, Grid, Forms, Customer, Product, Order, …). Re-run lotr --install at any time to update it.

The installed skill (SKILL.md) is a lean index that delegates to topic-specific reference files under references/:

File	Topic
module-structure.md	Folder layout, namespace, autoloading
module-class-and-installer.md	Main class, hooks, installTabs() / uninstallTabs()
database-and-entities.md	ObjectModel vs Doctrine overview
entity-doctrine.md	Doctrine ORM pattern: entity naming, ws_ prefix, Repository, Manager
grid-system.md	Grid definition, QueryBuilder, filters, position
configuration-page.md	Symfony form-based config page
services-and-di.md	services.yml, common.yml, factory registration
translations.md	Trans domains, catalogue extraction
hooks-and-front-office.md	Hook registration, front-office rendering
security.md	CSRF, SQL injection, input validation
legacy-conversion.md	Migrating from ObjectModel / legacy controllers
debugging.md	PHPStan, cache clearing, Symfony debug tools
validation.md	lotr pipeline, PS validator rules

Key rules enforced by the skill

• No raw SQL outside Repository, Manager, or SqlQueries.php (CREATE/DROP only) — applies to FixturesInstaller, Installer, hooks, and widget methods too.
• Services split — config/common.yml for Doctrine-only dependencies (both kernels); config/admin/services.yml for admin-only services; config/front/services.yml for front-office services. Do NOT create a root-level config/services.yml.
• Service guard — admin: $this->has() ternary + early return; front-office: plain $this->get() + null check. Never use ContainerFinder.
• FixturesInstaller must use Db::getInstance() raw SQL — SymfonyContainer::getInstance() returns null in the pr:mo console context, making all Doctrine ORM calls silently no-ops. Db::getValue() appends LIMIT 1 internally — never add it manually.
• Theme template injection — PS8 does not support theme overrides from modules; use marker-based file patching. Two-class design: ThemeTemplateInjector (service) + ThemeTemplateInstaller (orchestrator). Never use Theme::getThemes() — use scandir(_PS_ALL_THEMES_DIR_) instead.
• No getTabs() in the main module class — manage tabs via Installer::installTabs() / uninstallTabs().
• Entity class name = table name without _DB_PREFIX_ — Doctrine derives the table name from the class name. Table prefix convention is defined in steering/frameworks/prestashop/custom-patterns.md.
• FrameworkBundleAdminController::trans() parameter order is ($id, $domain, $parameters) — NOT Symfony's standard order. Never pass [] as domain.

Contributing

Contributions are welcome! This project is a work in progress and new features, fixes, and improvements are continuously being added.

To report a bug, request a feature, or track ongoing work, please visit the issue tracker: https://gitlab.com/JeffWebsenso/ws-module-devtools/-/work_items