jeffsenso/prestashop-skills / skills/prestashop-module-development
prestashop-module-development
VerifiedComplete 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.
references/entity-doctrine.md
View on GitHub# Doctrine Entity pattern (translatable entities)
## ObjectModel vs Doctrine ORM — differences and when to use each
| | **ObjectModel** (legacy) | **Doctrine ORM** (modern) |
|---|---|---|
| Definition | PHP class with a static `$definition` array | PHP class with `@ORM\` annotations |
| Multilang | `'multilang' => true` + `_lang` table via PS convention | Separate `*Lang` entity with `@ORM\ManyToOne` |
| Repository | Static methods or raw `Db::getInstance()` | Typed `EntityRepository`, injectable via DI |
| DI / testability | Not injectable — `new Entity($id)` | Repository + Manager injected via services.yml |
| Lifecycle hooks | `add()`, `update()`, `delete()` overrideable | `@ORM\PrePersist`, `@ORM\PreUpdate` |
| Shop association | Manual raw SQL | Manual via Manager (same approach, cleaner) |
| PS upgrade safety | Tightly coupled to PS ObjectModel internals | Decoupled — survives PS major version changes |
**Use Doctrine ORM when:**
- The entity is managed via the Grid system (CRUD list page)
- You want proper DI (repository + manager injected into services)
- The entity has translatable fields (`*Lang` table)
- You want lifecycle hooks (`dateAdd`, `dateUpd` auto-managed)
---
## Table naming convention — MANDATORY
Prefix every module table name with a consistent company or module prefix to group your tables together and avoid conflicts with PS core tables. Replace `prefix_` with your own prefix (e.g. your company abbreviation or module name).
- `prefix_mymodule_items` ✅
- `prefix_mymodule_items_lang` ✅
- `prefix_mymodule_items_shop` ✅
- `mymodule_items` ❌ (no prefix — risks collision with other modules)
---
## How the entity class name maps to the table name
**Do NOT use `MetadataListener` or Doctrine Event Listeners to set table names.**
PrestaShop's Doctrine integration automatically adds `_DB_PREFIX_` to all entity table names globally. The entity class name (lowercased by Doctrine) becomes the table name:
```
PHP class: Prefix_mymodule_items
→ Doctrine lowercases → prefix_mymodule_items
→ PS adds _DB_PREFIX_ → ps_prefix_mymodule_items (full DB table name)
```
So the naming convention is: **PHP class name = table name without `_DB_PREFIX_`**.
Use `@ORM\Table()` with **no `name=` parameter** — Doctrine derives it automatically.
The SQL in `SqlQueries.php` uses `_DB_PREFIX_ . 'ws_mymodule_items'` which produces the exact same table.
---
## Full Doctrine entity structure
```
src/
Entity/
├── Prefix_mymodule_items.php # class name = table name
└── Prefix_mymodule_items_lang.php # class name = lang table name
Repository/
└── MymoduleItemsRepository.php # extends EntityRepository
Manager/
└── MymoduleItemsManager.php # upsert logic, injects langRepository
config/
common.yml # repository factory
services.yml # manager + form chain
```
---
## `src/Entity/Prefix_mymodule_items.php`
```php
namespace Vendor\Mymodule\Entity;
use DateTime;
use Doctrine\Common\Collections\ArrayCollection;
use Doctrine\ORM\Mapping as ORM;
/**
* @ORM\Entity(repositoryClass="Vendor\Mymodule\Repository\MymoduleItemsRepository")
* @ORM\HasLifecycleCallbacks
* @ORM\Table()
*/
class Prefix_mymodule_items
{
/**
* @ORM\Id
* @ORM\Column(name="id_mymodule_items", type="integer")
* @ORM\GeneratedValue(strategy="AUTO")
*/
private int $id;
/**
* @ORM\OneToMany(
* targetEntity="Vendor\Mymodule\Entity\Prefix_mymodule_items_lang",
* cascade={"persist","remove"},
* mappedBy="prefix_mymodule_items"
* )
*/
private $langs;
/**
* @ORM\Column(name="active", type="boolean", options={"default": false})
*/
private bool $active = false;
/**
* @ORM\Column(name="position", type="integer")
*/
private int $position = 0;
/**
* @ORM\Column(name="date_add", type="datetime")
*/
private DateTime $dateAdd;
/**
* @ORM\Column(name="date_upd", type="datetime")
*/
private DateTime $dateUpd;
public function __construct()
{
$this->langs = new ArrayCollection();
}
public function getId(): int { return $this->id; }
public function isActive(): bool { return $this->active; }
public function setActive(bool $active): void { $this->active = $active; }
public function getPosition(): int { return $this->position; }
public function setPosition(int $position): self { $this->position = $position; return $this; }
public function getLangs() { return $this->langs; }
public function getLangByLangId(int $langId): ?Prefix_mymodule_items_lang
{
foreach ($this->langs as $lang) {
if ($langId === $lang->getLang()->getId()) {
return $lang;
}
}
return null;
}
public function addLang(Prefix_mymodule_items_lang $lang): self
{
$lang->setPrefix_mymodule_items($this);
$this->langs->add($lang);
return $this;
}
public function getAllFields(): array
{
$names = [];
foreach ($this->langs as $l) {
$names[$l->getLang()->getId()] = $l->getName();
}
return [
'name' => $names,
'active' => $this->active,
];
}
public function setFields(array $params): void
{
if (isset($params['active'])) {
$this->active = (bool) $params['active'];
}
if (isset($params['position'])) {
$this->position = (int) $params['position'];
}
}
/** @ORM\PrePersist */
public function setCreatedAt(): void
{
$this->dateAdd = new DateTime();
$this->dateUpd = new DateTime();
}
/** @ORM\PreUpdate */
public function setUpdatedAt(): void
{
$this->dateUpd = new DateTime();
}
}
```
---
## `src/Entity/Prefix_mymodule_items_lang.php`
```php
namespace Vendor\Mymodule\Entity;
use Doctrine\ORM\Mapping as ORM;
use PrestaShopBundle\Entity\Lang;
/**
* @ORM\Entity()
* @ORM\Table()
*/
class Prefix_mymodule_items_lang
{
/**
* @ORM\Id
* @ORM\ManyToOne(targetEntity="Vendor\Mymodule\Entity\Prefix_mymodule_items", inversedBy="langs")
* @ORM\JoinColumn(name="id_mymodule_items", referencedColumnName="id_mymodule_items", nullable=false)
*/
private Prefix_mymodule_items $prefix_mymodule_items;
/**
* @ORM\Id
* @ORM\ManyToOne(targetEntity="PrestaShopBundle\Entity\Lang")
* @ORM\JoinColumn(name="id_lang", referencedColumnName="id_lang", nullable=false, onDelete="CASCADE")
*/
private Lang $lang;
/**
* @ORM\Column(type="string", length=255, nullable=true)
*/
private ?string $name = null;
public function getPrefix_mymodule_items(): Prefix_mymodule_items { return $this->prefix_mymodule_items; }
public function setPrefix_mymodule_items(Prefix_mymodule_items $e): self { $this->prefix_mymodule_items = $e; return $this; }
public function getLang(): Lang { return $this->lang; }
public function setLang(Lang $l): self { $this->lang = $l; return $this; }
public function getName(): ?string { return $this->name; }
public function setName(?string $name): self { $this->name = $name; return $this; }
}
```
---
## `src/Repository/MymoduleItemsRepository.php`
```php
namespace Vendor\Mymodule\Repository;
use Doctrine\ORM\EntityRepository;
use Vendor\Mymodule\Entity\Prefix_mymodule_items;
class MymoduleItemsRepository extends EntityRepository
{
public function upsertEntity(Prefix_mymodule_items $entity): void
{
$em = $this->getEntityManager();
$em->persist($entity);
$em->flush();
}
public function deleteEntity(Prefix_mymodule_items $entity): void
{
$em = $this->getEntityManager();
$em->remove($entity);
$em->flush();
}
public function getNextPosition(): int
{
$max = $this->createQueryBuilder('e')
->select('MAX(e.position)')
->getQuery()
->getSingleScalarResult();
// IMPORTANT: PrestaShop positions are 0-based
// First item = position 0, second = 1, third = 2, etc.
// Grid displays them as 1, 2, 3... but DB stores 0, 1, 2...
return ($max !== null) ? ((int) $max + 1) : 0;
}
/** Used by Grid QueryBuilder — raw DBAL */
public function getByIdAndLang(?int $id, int $langId): array
{
$conn = $this->getEntityManager()->getConnection();
$prefix = _DB_PREFIX_;
$params = ['id_lang' => $langId];
$filter = '';
if ($id && $id > 0) {
$filter = ' AND e.id_mymodule_items = :id';
$params['id'] = $id;
}
$sql = "SELECT e.*, el.*
FROM {$prefix}prefix_mymodule_items e
LEFT JOIN {$prefix}prefix_mymodule_items_lang el
ON e.id_mymodule_items = el.id_mymodule_items AND el.id_lang = :id_lang
WHERE e.active = 1{$filter}
ORDER BY e.position ASC";
return $conn->prepare($sql)->executeQuery($params)->fetchAllAssociative();
}
}
```
---
## `src/Manager/MymoduleItemsManager.php`
```php
namespace Vendor\Mymodule\Manager;
use PrestaShopBundle\Entity\Repository\LangRepository;
use Vendor\Mymodule\Entity\Prefix_mymodule_items;
use Vendor\Mymodule\Entity\Prefix_mymodule_items_lang;
use Vendor\Mymodule\Repository\MymoduleItemsRepository;
class MymoduleItemsManager
{
public function __construct(
private readonly MymoduleItemsRepository $repository,
private readonly LangRepository $langRepository,
) {}
public function upsert(int $id, array $params): void
{
$entity = $this->repository->findOneBy(['id' => $id]);
if (!$entity) {
$entity = new Prefix_mymodule_items();
foreach ($params['name'] as $langId => $name) {
$lang = $this->langRepository->findOneBy(['id' => $langId]);
$langRow = new Prefix_mymodule_items_lang();
$langRow->setLang($lang);
$entity->addLang($langRow);
}
if (!isset($params['position'])) {
$params['position'] = $this->repository->getNextPosition();
}
}
foreach ($params['name'] as $langId => $value) {
$row = $entity->getLangByLangId((int) $langId);
if ($row !== null) {
$row->setName($value);
}
}
unset($params['name']);
$entity->setFields($params);
$this->repository->upsertEntity($entity);
}
public function delete(int $id): void
{
$entity = $this->repository->findOneBy(['id' => $id]);
if ($entity) {
$this->repository->deleteEntity($entity);
}
}
public function getActiveLanguages(): array
{
return $this->langRepository->findBy(['active' => true]);
}
}
```
---
## `config/common.yml` — repository factory
No MetadataListener. No special Doctrine event listener. Just the factory:
```yaml
services:
mymodule.repository.items_repository:
class: Vendor\Mymodule\Repository\MymoduleItemsRepository
public: true
factory: ["@doctrine.orm.default_entity_manager", getRepository]
arguments:
- Vendor\Mymodule\Entity\Prefix_mymodule_items
```
---
## `config/services.yml` additions — manager
```yaml
imports:
- { resource: common.yml }
services:
mymodule.manager.items_manager:
class: Vendor\Mymodule\Manager\MymoduleItemsManager
public: true
arguments:
- "@mymodule.repository.items_repository"
- "@prestashop.core.admin.lang.repository"
```
---
## Key rules summary
- Entity class name = table name without `_DB_PREFIX_` (PS handles the prefix globally)
- Always prefix tables with a consistent company or module prefix: e.g. `prefix_mymodule_*` — replace `prefix_` with your own
- `@ORM\Table()` — empty annotation, NO `name=` parameter
- Do NOT create `MetadataListener` or Doctrine event listeners for table naming
- Repository registered via factory: `["@doctrine.orm.default_entity_manager", getRepository]`
- Manager injects `@prestashop.core.admin.lang.repository` for translatable entities
- Both entity files (main + lang) have the `if (!defined('_PS_VERSION_')) { exit; }` guard
- **Position field MUST start at 0** (not 1) — Grid displays as 1, 2, 3... but DB stores 0, 1, 2...
- `getNextPosition()` should return `0` when no records exist (not `1`)
- FixturesInstaller should set first item position to `0` (not `1`)
- SQL `DEFAULT 0` is correct for position column
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |