websenso/prestashop-module-devtools

Tools & script to automatically fix code for PrestaShop modules.

1.1.3 2026-04-29 14:44 UTC

Requires

• php: >=8
• friendsofphp/php-cs-fixer: ^3.94.2
• guzzlehttp/guzzle: ^7.0
• phpstan/phpstan: ^1.12.13
• prestashop/autoindex: ^2.1
• prestashop/header-stamp: ^2.3
• prestashop/php-dev-tools: 5.0
• spaze/phpstan-disallowed-calls: ^2.10.0
• squizlabs/php_codesniffer: 3.7.2
• stancer/php-stubs-prestashop: ^8.1
• symfony/console: ^4.4|^5.0|^6.0
• symfony/finder: ^4.4|^5.0|^6.0
• symfony/yaml: ^5.0|^6.0|^7.0

MIT

• Jeff Maurer

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
• Copy .instructions.md (AI coding assistant instructions) to your project root
• Copy .gitlab-ci.yml (example CI pipeline) to your project root

php vendor/bin/lotr --install

Each file is only created if it does not already exist — existing files are never overwritten.

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

Running --install copies a .instructions.md file to your project root. This file tells GitHub Copilot and compatible AI coding assistants to always load the PrestaShop module development skill bundled at: vendor/websenso/prestashop-module-devtools/skills/prestashop-module-development/SKILL.md

The skill is structured as a lean index (SKILL.md) that delegates to topic-specific reference files under skills/prestashop-module-development/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/services.yml or config/admin/services.yml for admin-only services (Manager, Grid, Forms, Controllers).
• Guard every $this->get() with $this->has() to avoid ServiceNotFoundException.
• FixturesInstaller must resolve core Symfony services and instantiate the Manager directly — module-own services are NOT in the compiled container at install time.
• No getTabs() in the main module class — manage tabs via Installer::installTabs() / uninstallTabs().
• Entity class name = table name without _DB_PREFIX_; all tables start with ws_.

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