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/grid-system.md

View on GitHub
# PrestaShop Grid system

The PS Grid system renders CRUD list pages using `@PrestaShop/Admin/Common/Grid/grid_panel.html.twig`. It handles columns, filters, bulk actions, pagination, toggling, and drag-and-drop position — with a generic init script (`scripts/grid.bundle.js`) built on the core Grid JS components.

## File structure

```
src/Grid/
├── Definition/Factory/
│   └── MyEntityGridDefinitionFactory.php   # columns, filters, row actions
├── Filters/
│   └── MyEntityFilters.php                 # default sort/pagination
└── Query/
    └── MyEntityQueryBuilder.php            # Doctrine DBAL query
views/js/
└── mymodule.bundle.js                      # copy of scripts/grid.bundle.js (generic, no edit)
```

All `src/Grid/` subdirectories must have an `index.php` guard (lotr adds them automatically).

---

## GridDefinitionFactory

```php
namespace Vs\MyModule\Grid\Definition\Factory;

use PrestaShop\PrestaShop\Core\Grid\Action\GridActionCollection;
use PrestaShop\PrestaShop\Core\Grid\Action\GridActionCollectionInterface;
use PrestaShop\PrestaShop\Core\Grid\Action\Row\RowActionCollection;
use PrestaShop\PrestaShop\Core\Grid\Action\Row\Type\LinkRowAction;
use PrestaShop\PrestaShop\Core\Grid\Action\Row\Type\SubmitRowAction;
use PrestaShop\PrestaShop\Core\Grid\Action\Type\SimpleGridAction;
use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollection;
use PrestaShop\PrestaShop\Core\Grid\Column\ColumnCollectionInterface;
use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\ActionColumn;
use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\DataColumn;
use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\PositionColumn;
use PrestaShop\PrestaShop\Core\Grid\Column\Type\Common\ToggleColumn;
use PrestaShop\PrestaShop\Core\Grid\Definition\Factory\AbstractGridDefinitionFactory;
use PrestaShop\PrestaShop\Core\Grid\Filter\Filter;
use PrestaShop\PrestaShop\Core\Grid\Filter\FilterCollection;
use PrestaShop\PrestaShop\Core\Grid\Filter\FilterCollectionInterface;
use PrestaShopBundle\Form\Admin\Type\SearchAndResetType;
use Symfony\Component\Form\Extension\Core\Type\TextType;

class MyEntityGridDefinitionFactory extends AbstractGridDefinitionFactory
{
    public const GRID_ID = 'mymodule_myentity';

    protected function getId(): string { return self::GRID_ID; }
    protected function getName(): string { return $this->trans('My Entities', [], 'Modules.Mymodule.Admin'); }

    protected function getColumns(): ColumnCollectionInterface
    {
        return (new ColumnCollection())
            ->add((new DataColumn('id_myentity'))
                ->setName($this->trans('ID', [], 'Admin.Global'))
                ->setOptions(['field' => 'id_myentity'])
            )
            ->add((new DataColumn('name'))
                ->setName($this->trans('Name', [], 'Admin.Global'))
                ->setOptions(['field' => 'name'])
            )
            // Drag-and-drop position column
            ->add((new PositionColumn('position'))
                ->setName($this->trans('Position', [], 'Admin.Global'))
                ->setOptions([
                    'id_field' => 'id_myentity',
                    'position_field' => 'position',
                    'update_method' => 'POST',
                    'update_route' => 'mymodule_myentity_update_position',
                    'record_route_params' => ['id_myentity' => 'entityId'],
                ])
            )
            // Toggle active/inactive column
            ->add((new ToggleColumn('active'))
                ->setName($this->trans('Active', [], 'Admin.Global'))
                ->setOptions([
                    'field' => 'active',
                    'primary_field' => 'id_myentity',
                    'route' => 'mymodule_myentity_toggle_status',
                    'route_param_name' => 'entityId',  // controller must declare: int $entityId
                ])
            )
            ->add((new ActionColumn('actions'))
                ->setName($this->trans('Actions', [], 'Admin.Global'))
                ->setOptions(['actions' => (new RowActionCollection())
                    ->add((new LinkRowAction('edit'))
                        ->setName($this->trans('Edit', [], 'Admin.Actions'))
                        ->setIcon('edit')
                        ->setOptions([
                            'route' => 'mymodule_myentity_edit',
                            'route_param_name' => 'entityId',
                            'route_param_field' => 'id_myentity',
                            'clickable_row' => true,
                        ])
                    )
                    ->add((new SubmitRowAction('delete'))
                        ->setName($this->trans('Delete', [], 'Admin.Actions'))
                        ->setIcon('delete')
                        ->setOptions([
                            'method' => 'POST',
                            'route' => 'mymodule_myentity_delete',
                            'route_param_name' => 'entityId',
                            'route_param_field' => 'id_myentity',
                            'confirm_message' => $this->trans('Delete selected item?', [], 'Admin.Notifications.Warning'),
                        ])
                    ),
                ])
            );
    }

    // IMPORTANT: return FilterCollectionInterface (not FilterCollection) — PHPStan requirement
    protected function getFilters(): FilterCollectionInterface
    {
        return (new FilterCollection())
            ->add((new Filter('id_myentity', TextType::class))
                ->setTypeOptions(['required' => false])
                ->setAssociatedColumn('id_myentity')
            )
            ->add((new Filter('name', TextType::class))
                ->setTypeOptions(['required' => false])
                ->setAssociatedColumn('name')
            )
            // YesAndNoChoiceType — for ToggleColumn (active, showOnHp, etc.)
            // Renders a Yes/No dropdown filter. Use for any boolean/toggle column.
            ->add((new Filter('active', YesAndNoChoiceType::class))
                ->setTypeOptions(['required' => false])
                ->setAssociatedColumn('active')
            )
            // ReorderPositionsButtonType — for PositionColumn
            // Renders a "Rearrange" button in the filter row. Clicking it resets the grid
            // sort to 'position' ASC, which re-enables drag-and-drop (position_handle column
            // is only injected by GridPresenter when orderBy === 'position').
            // This is the proper UX fix for "drag disabled after sorting by another column".
            ->add((new Filter('position', ReorderPositionsButtonType::class))
                ->setAssociatedColumn('position')
            )
            ->add((new Filter('actions', SearchAndResetType::class))
                ->setTypeOptions([
                    'reset_route' => 'admin_common_reset_search_by_filter_id',
                    'reset_route_params' => ['filterId' => self::GRID_ID],
                    'redirect_route' => 'mymodule_myentity_index',
                ])
                ->setAssociatedColumn('actions')
            );
    }

    // IMPORTANT: return GridActionCollectionInterface (not GridActionCollection) — PHPStan requirement
    protected function getGridActions(): GridActionCollectionInterface
    {
        return (new GridActionCollection())
            ->add((new SimpleGridAction('common_refresh_list'))
                ->setName($this->trans('Refresh list', [], 'Admin.Advparameters.Feature'))
                ->setIcon('refresh')
            );
    }
}
```

---

## QueryBuilder (Doctrine DBAL)

```php
namespace Vs\MyModule\Grid\Query;

use Doctrine\DBAL\Connection;
use Doctrine\DBAL\Query\QueryBuilder;
use PrestaShop\PrestaShop\Core\Grid\Query\AbstractDoctrineQueryBuilder;
use PrestaShop\PrestaShop\Core\Grid\Query\DoctrineSearchCriteriaApplicatorInterface;
use PrestaShop\PrestaShop\Core\Grid\Search\SearchCriteriaInterface;

class MyEntityQueryBuilder extends AbstractDoctrineQueryBuilder
{
    public function __construct(
        Connection $connection,
        string $dbPrefix,
        private DoctrineSearchCriteriaApplicatorInterface $searchCriteriaApplicator,
        private int $contextShopId,
        private int $contextIdLang
    ) {
        parent::__construct($connection, $dbPrefix);
    }

    public function getSearchQueryBuilder(SearchCriteriaInterface $searchCriteria): QueryBuilder
    {
        $qb = $this->getBaseQueryBuilder($searchCriteria->getFilters());
        $qb->select('e.id_myentity, e.position, e.active, el.name')
           ->groupBy('e.id_myentity');
        $this->searchCriteriaApplicator
            ->applySorting($searchCriteria, $qb)
            ->applyPagination($searchCriteria, $qb);
        return $qb;
    }

    public function getCountQueryBuilder(SearchCriteriaInterface $searchCriteria): QueryBuilder
    {
        return $this->getBaseQueryBuilder($searchCriteria->getFilters())
            ->select('COUNT(DISTINCT e.id_myentity)');
    }

    private function getBaseQueryBuilder(array $filters): QueryBuilder
    {
        // Use leftJoin (not innerJoin) so rows without lang/shop entries still appear.
        $qb = $this->connection->createQueryBuilder()
            ->from($this->dbPrefix . 'mymodule_myentity', 'e')
            ->leftJoin('e', $this->dbPrefix . 'mymodule_myentity_lang', 'el',
                'e.id_myentity = el.id_myentity AND el.id_lang = :id_lang')
            ->leftJoin('e', $this->dbPrefix . 'mymodule_myentity_shop', 'es',
                'e.id_myentity = es.id_myentity AND es.id_shop = :id_shop')
            ->setParameter('id_lang', $this->contextIdLang)
            ->setParameter('id_shop', $this->contextShopId);

        if (isset($filters['id_myentity'])) {
            $qb->andWhere('e.id_myentity = :id_myentity')
               ->setParameter('id_myentity', $filters['id_myentity']);
        }
        if (isset($filters['name'])) {
            $qb->andWhere('el.name LIKE :name')
               ->setParameter('name', '%' . $filters['name'] . '%');
        }

        return $qb;
    }
}
```

---

## Filters class

```php
namespace Vs\MyModule\Grid\Filters;

use PrestaShop\PrestaShop\Core\Search\Filters;
use Vs\MyModule\Grid\Definition\Factory\MyEntityGridDefinitionFactory;

class MyEntityFilters extends Filters
{
    protected $filterId = MyEntityGridDefinitionFactory::GRID_ID;

    public static function getDefaults(): array
    {
        return [
            'limit'     => 20,
            'offset'    => 0,
            'orderBy'   => 'position',
            'sortOrder' => 'asc',
            'filters'   => [],
        ];
    }
}
```

---

## `config/services.yml` registration

```yaml
  # Grid definition factory
  mymodule.grid.definition.factory.myentity:
    class: 'Vs\MyModule\Grid\Definition\Factory\MyEntityGridDefinitionFactory'
    parent: 'prestashop.core.grid.definition.factory.abstract_grid_definition'

  # Query builder
  mymodule.grid.query.myentity:
    class: 'Vs\MyModule\Grid\Query\MyEntityQueryBuilder'
    parent: 'prestashop.core.grid.abstract_query_builder'
    arguments:
      - '@prestashop.core.query.doctrine_search_criteria_applicator'
      - "@=service('prestashop.adapter.shop.context').getContextListShopID()[0]"
      - "@=service('prestashop.adapter.legacy.context').getContext().language.id"

  # DoctrineGridDataFactory — 4th arg must match GRID_ID
  mymodule.grid.data.factory.myentity:
    class: 'PrestaShop\PrestaShop\Core\Grid\Data\Factory\DoctrineGridDataFactory'
    arguments:
      - '@mymodule.grid.query.myentity'
      - '@prestashop.core.hook.dispatcher'
      - '@prestashop.core.grid.query.doctrine_query_parser'
      - 'mymodule_myentity'

  # GridFactory — injected into the controller
  mymodule.grid.factory.myentity:
    class: 'PrestaShop\PrestaShop\Core\Grid\GridFactory'
    arguments:
      - '@mymodule.grid.definition.factory.myentity'
      - '@mymodule.grid.data.factory.myentity'
      - '@prestashop.core.grid.filter.form_factory'
      - '@prestashop.core.hook.dispatcher'

  # PositionDefinition — used by updatePositionAction
  # IMPORTANT: $table must be the table name WITHOUT the DB prefix.
  # DoctrinePositionUpdateHandler prepends $dbPrefix automatically at runtime.
  # e.g. for table `9sxtm_prefix_mymodule_items`, use $table: 'prefix_mymodule_items'
  mymodule.grid.position_definition:
    class: 'PrestaShop\PrestaShop\Core\Grid\Position\PositionDefinition'
    arguments:
      $table: 'mymodule_myentity'   # WITHOUT _DB_PREFIX_ — handler adds it
      $idField: 'id_myentity'       # actual DB column name of the PK
      $positionField: 'position'
```

---

## `config/routes.yml` — required routes

```yaml
# CRITICAL: Do NOT start paths with /modules/
# PS's YamlModuleLoader (src/PrestaShopBundle/Routing/YamlModuleLoader.php) automatically
# prepends /modules to every route path. Starting your path with /modules/ results in
# /modules/modules/mymodule/... which causes 405 Method Not Allowed on all actions.

mymodule_myentity_index:
  path: /mymodule/entities          # becomes /modules/mymodule/entities after PS prefix
  methods: [GET]
  defaults:
    _controller: 'Vs\MyModule\Controller\Admin\MyEntityController::indexAction'
    _legacy_controller: AdminMymoduleMyentity
    _legacy_link: AdminMymoduleMyentity

# Search uses SAME path as index, just POST method.
# The Grid search form POSTs to the current URL (index URL) — it MUST match here.
mymodule_myentity_search:
  path: /mymodule/entities          # same as index — PS Grid POSTs to the same URL
  methods: [POST]
  defaults:
    _controller: 'Vs\MyModule\Controller\Admin\MyEntityController::searchAction'
    _legacy_controller: AdminMymoduleMyentity
    _legacy_link: AdminMymoduleMyentity:search

# Toggle route — entityId comes from ToggleColumn's route_param_name
mymodule_myentity_toggle_status:
  path: /mymodule/entities/{entityId}/toggle-status
  methods: [POST]
  defaults:
    _controller: 'Vs\MyModule\Controller\Admin\MyEntityController::toggleStatus'
    _legacy_controller: AdminMymoduleMyentity
    _legacy_link: AdminMymoduleMyentity:togglestatus
  requirements:
    entityId: '\d+'

# Position update POSTed by the core PositionExtension (drag-and-drop)
mymodule_myentity_update_position:
  path: /mymodule/entities/update-position
  methods: [POST]
  defaults:
    _controller: 'Vs\MyModule\Controller\Admin\MyEntityController::updatePositionAction'
    _legacy_controller: AdminMymoduleMyentity
    _legacy_link: AdminMymoduleMyentity:updateposition
```

---

## Controller actions

```php
use PrestaShop\PrestaShop\Core\Exception\TranslatableCoreException;
use PrestaShop\PrestaShop\Core\Grid\Position\GridPositionUpdaterInterface;
use PrestaShop\PrestaShop\Core\Grid\Position\PositionUpdateFactoryInterface;
use Symfony\Component\HttpFoundation\RedirectResponse;

// PS resolves MyEntityFilters via its Filters resolver (injected automatically)
public function indexAction(MyEntityFilters $filters): Response
{
    $gridFactory = $this->get('mymodule.grid.factory.myentity');
    return $this->render('@Modules/mymodule/views/templates/admin/myentity/index.html.twig', [
        'enableSidebar' => true,
        'layoutTitle' => $this->trans('My Entities', [], 'Modules.Mymodule.Admin'),
        'layoutHeaderToolbarBtn' => [
            'add' => [
                'desc' => $this->trans('Add new entity', [], 'Modules.Mymodule.Admin'),
                'icon' => 'add_circle_outline',
                'href' => $this->generateUrl('mymodule_myentity_create'),
            ],
        ],
        'grid' => $this->presentGrid($gridFactory->getGrid($filters)),
    ]);
}

public function searchAction(Request $request): RedirectResponse
{
    $definitionFactory = $this->get('mymodule.grid.definition.factory.myentity');
    $responseBuilder   = $this->get('prestashop.bundle.grid.response_builder');
    return $responseBuilder->buildSearchResponse(
        $definitionFactory,
        $request,
        MyEntityGridDefinitionFactory::GRID_ID,
        'mymodule_myentity_index'
    );
}

// entityId comes from route parameter (ToggleColumn sets route_param_name)
public function toggleStatus(Request $request, int $entityId): Response
{
    // load entity, toggle ->active, save, return JSON
    return $this->json(['status' => true, 'message' => $this->trans('Status updated.', [], 'Admin.Notifications.Success')]);
}

public function updatePositionAction(Request $request): RedirectResponse
{
    // IMPORTANT: use request->all()['positions'] NOT request->get('positions')
    // Symfony InputBag::get() throws BadRequestException on array values.
    $positionsData      = ['positions' => $request->request->all()['positions'] ?? []];
    $positionDefinition = $this->get('mymodule.grid.position_definition');
    $positionUpdateFactory = $this->get(PositionUpdateFactoryInterface::class);

    try {
        $positionUpdate = $positionUpdateFactory->buildPositionUpdate($positionsData, $positionDefinition);
        $this->get(GridPositionUpdaterInterface::class)->update($positionUpdate);
        $this->addFlash('success', $this->trans('Successful update.', [], 'Admin.Notifications.Success'));
    } catch (TranslatableCoreException $e) {
        $this->flashErrors([$e->toArray()]);
    } catch (\Exception $e) {
        $this->flashErrors([$e->getMessage()]);
    }

    return $this->redirectToRoute('mymodule_myentity_index');
}
```

---

## Twig template (`index.html.twig`)

```twig
{% extends '@PrestaShop/Admin/layout.html.twig' %}

{% block content %}
    <div class="row">
        <div class="col">
            {% include '@PrestaShop/Admin/Common/Grid/grid_panel.html.twig' with {'grid': grid} %}
        </div>
    </div>
{% endblock %}

{% block javascripts %}
    {{ parent() }}
    {# Load the grid script ONLY here, AFTER parent() — never also in hookDisplayBackOfficeHeader #}
    <script src="{{ asset('../modules/mymodule/views/js/mymodule.bundle.js') }}"></script>
    <script src="{{ asset('themes/default/js/bundle/pagination.js') }}"></script>
{% endblock %}
```

> **CRITICAL — load the grid script ONLY in the Twig `{% block javascripts %}`, after `{{ parent() }}`, NEVER also in `hookDisplayBackOfficeHeader`.**
> Loading it twice binds every extension twice: each toggle click fires two AJAX calls that cancel each other out — the DB ends up unchanged while the UI shows success. (`scripts/grid.bundle.js` guards against a double inclusion with `data-grid-initialized`, but a second copy under another file name is not detected.)

> ⚠️ **Asset path pitfall**: the path `../modules/mymodule/views/js/mymodule.bundle.js` must use the **exact module folder name** (i.e. `$this->name`). A typo here (e.g. `ws_mymodule` instead of `wsmymodule`) causes a silent 404 — no extension is bound: sort, reset, row links, toggle and drag-and-drop silently do nothing.

---

## Grid JS setup

Copy the generic init script — **no edit needed** (no grid ID to replace, no `sed`):

```bash
cp vendor/websenso/prestashop-module-devtools/skills/.agents/skills/prestashop-module-development/scripts/grid.bundle.js \
   views/js/{modulename}.bundle.js
```

Despite its historical `.bundle.js` name, it is **not** a webpack bundle any more: it is a short readable script
using the core Grid component and its extensions, exposed on `window.prestashop.component` by the back office
theme bundle (PrestaShop **8.0+ and 9.x** — same API in 8.0.0, 8.1.0, 8.2.0 and 9.0.0). For every
`.js-grid[data-grid-id]` container of the page (rendered by `@PrestaShop/Admin/Common/Grid/grid.html.twig`) it
creates `new window.prestashop.component.Grid(gridId)` and adds:

| Extension | Handles |
|---|---|
| `FiltersResetExtension` | Reset button (`.js-reset-search`): POST to `data-url`, then redirect to `data-redirect` |
| `FiltersSubmitButtonEnablerExtension` | Enables the Search button when a filter changes |
| `SortingExtension` | Column header click (`.ps-sortable-column`) → reload with `{gridId}[orderBy]`/`[sortOrder]` |
| `ReloadListExtension` | "Refresh list" grid action |
| `ExportToSqlManagerExtension` | "Show SQL query" and "Export to SQL Manager" grid actions |
| `SubmitGridActionExtension` | Grid actions submitting a form (`.js-grid-action-submit-btn`) |
| `LinkRowActionExtension` | `LinkRowAction` links + `clickable_row` |
| `SubmitRowActionExtension` | `SubmitRowAction` (delete…), with `confirm_message` |
| `BulkActionCheckboxExtension`, `SubmitBulkActionExtension` | Bulk action checkboxes and submit buttons |
| `AsyncToggleColumnExtension` | `ToggleColumn` switch → AJAX POST, controller returns JSON `{status, message}` |
| `PositionExtension(grid)` | `PositionColumn` drag-and-drop + "Rearrange" button (8.2+) — added only when the grid has one |

Extensions bound to markup that a grid does not render are harmless, so the same file serves every grid, and
pages with several grids work without any change.

**Init timing — jQuery ready, never `DOMContentLoaded`.** The admin theme (`new-theme/js/theme.ts`) creates
`window.prestashop.component` inside `$(() => { initPrestashopComponents(); … })`, and jQuery 3 runs ready
callbacks **after** `DOMContentLoaded`. A script initialising on `DOMContentLoaded` finds no component and binds
nothing (symptom: Reset never sends its POST). `scripts/grid.bundle.js` runs in `window.jQuery(function () {...})`:
being loaded after the theme bundle, its callback is queued after the theme's one.

**Never add `ColumnTogglingExtension`** next to `AsyncToggleColumnExtension`: both bind the same
`.ps-togglable-row` switch (the first submits a full-page form, the second an AJAX call), so one click sends
two toggle requests that cancel each other. The skill's toggle controllers return JSON → `AsyncToggleColumnExtension`.

Need a custom extension or a different setup for one grid? Keep the generic file and add a small page script
that runs after it (also in a jQuery ready callback), or replace the file by an explicit init for that module —
but always with the core `window.prestashop.component` classes, never a copied webpack bundle.

**Upgrading a module that ships an old copied webpack bundle** (a huge minified line with `new o.a("…")` and
`e(e.s = 13)`): overwrite its `views/js/*.bundle.js` file(s) with `scripts/grid.bundle.js`. The file name and
the Twig `<script>` tag stay the same. The old template was broken (only 20 of its 22 webpack modules: shifted
positional indexes, so its private bootstrap never ran — delete row, reset, refresh, show SQL, row links and bulk
actions silently did nothing while sort still worked), and even repaired copies freeze an old PrestaShop build and
need the grid ID edited by hand.

> **Do NOT** use `addJqueryUI('ui.sortable')` + custom admin.js for position management. Use the PS Grid PositionColumn + `PositionExtension` — it is fully handled by the framework.

---

## How sort, search and reset actually work (and how they silently break)

All three rely on the grid container `#{GRID_ID}_grid` rendered by `grid.html.twig` and on the extensions
added by `views/js/{modulename}.bundle.js` (see "Grid JS setup").

- **Sort** — `SortingExtension` binds a click on each `.ps-sortable-column` header: it reads
  `data-sort-col-name` / `data-sort-prefix` / `data-sort-direction`, builds a URL with
  `{prefix}[orderBy]` and `{prefix}[sortOrder]` and does a full `window.location =` navigation (no AJAX).
  The index action resolves the filters from that URL (type-hinted `Filters` argument).
- **Reset** — `FiltersResetExtension` binds `.js-reset-search` (rendered by `SearchAndResetType` only when a
  filter is set): it POSTs to `data-url` (`admin_common_reset_search_by_filter_id`, which removes the stored
  filters of this `filterId` for the employee and shop in `ps_admin_filter`), then `window.location.assign(data-redirect)`.
- **Search** — a **plain HTML form POST**, not AJAX: the Search button submits `grid.filter_form` to the
  current URL (the index route). This means:
  - The **search route MUST share the same path as the index route**, only `methods: [POST]` differs
    (see routes.yml section above) — otherwise 405.
  - `searchAction()`'s **third argument to `buildSearchResponse()` must be the literal `GRID_ID` string**
    (e.g. `YourFactory::GRID_ID`), **never** a `Filters::class` name — otherwise the filters are silently not applied.

### Quick diagnosis checklist when sort/reset/search "does nothing"

1. **Is the script loaded?** Browser dev tools → Network: `{modulename}.bundle.js` must return 200 (folder
   name typo in the asset path = silent 404, nothing is bound).
2. **Is it the current script?** If the file is a huge minified webpack line (`new o.a("…")`), it is an old
   copied bundle: overwrite it with `scripts/grid.bundle.js` (see "Grid JS setup") before debugging anything else.
3. **Is the grid initialised?** Console: `document.querySelector('#{GRID_ID}_grid').dataset.gridInitialized`
   must be `"1"`. If not:
   - a console error "Grid: window.prestashop.component.Grid is not available" means the script ran before the
     theme components: it must be in `{% block javascripts %}` after `{{ parent() }}`, and initialise in a
     jQuery ready callback (never `DOMContentLoaded`);
   - otherwise check that the page renders `grid.html.twig` (the `.js-grid[data-grid-id]` container).
4. **Reset clicked but nothing happens?** Check `var/logs/dev-*.log` for `Matched route "admin_common_reset_search_by_filter_id"`:
   absent = the click handler is not bound (go back to 1–3); present = check the `filterId` (`reset_route_params`)
   equals the `Filters::$filterId` / `GRID_ID`.
5. **Search**: `searchAction()` third param must be the `GRID_ID` string, and search/index routes must share the path.
6. **Reset button missing**: normal when no filter is set (`SearchAndResetType` shows it only with active filters).
7. Column `sortable` option **defaults to `true`** in `AbstractColumn::configureOptions()` — not the cause.

---

## Key gotchas

- `getFilters()` return type must be **`FilterCollectionInterface`** (not `FilterCollection`) — PHPStan enforces this.
- `getGridActions()` return type must be **`GridActionCollectionInterface`** (not `GridActionCollection`) — same rule.
- **The grid script must be loaded ONLY in the Twig `{% block javascripts %}`, after `{{ parent() }}`** — never also in `hookDisplayBackOfficeHeader`. Loading it twice (under two file names) binds every extension twice: each toggle click fires two AJAX calls that cancel each other out, leaving the DB unchanged while the UI shows success.
- **`SortingExtension` is mandatory when using `PositionColumn` with `ReorderPositionsButtonType`** — `PositionExtension` toggles reorder-mode by simulating a `.click()` on the `.ps-sortable-column` header. Without `SortingExtension`, no click handler exists on those headers and the click is a no-op. Symptom: "Done/Rearrange" button appears to do nothing when clicked. `scripts/grid.bundle.js` always adds it.
- **`FiltersResetExtension` is mandatory for the reset search button** — the reset button has `type="reset"` (clears the HTML form) but also needs a POST to the reset route via `data-url` to remove the stored filters (`ps_admin_filter`). Without it, Reset only clears the form fields in the browser and the filters come back on the next page load. `scripts/grid.bundle.js` always adds it.
- `ToggleColumn` fires AJAX POST with the route param from `route_param_name` — the controller method **must accept that param by the same name** (e.g. `int $entityId`).
- `PositionColumn` POSTs a `positions[]` array to `update_route` — the controller **must** read it via `$request->request->all()['positions'] ?? []`, NOT `$request->request->get('positions')`. Symfony's `InputBag::get()` throws `BadRequestException: Input value "positions" contains a non-scalar value.` when the value is an array.
- `DoctrineGridDataFactory` 4th argument is a **string hook identifier** matching your GRID_ID value — not a service reference.
- `getContextListShopID()[0]` in services.yml gets the single current shop ID (integer) required by the query builder.
- `index.php` guards must exist in **all** Grid subdirectories — lotr adds them automatically.
- **NEVER start module route paths with `/modules/`** — `YamlModuleLoader` always prepends `/modules` automatically. Path `/modules/mymodule/...` becomes `/modules/modules/mymodule/...`, causing 404/405 on every action. Use `/mymodule/...` instead.
- **Index (GET) and search (POST) MUST share the same path** — the Grid search form POSTs to the current page URL (the index URL). If the search route has a different path (e.g. `/entities/search`), the POST hits the index route which only accepts GET → 405 Method Not Allowed.
- **`searchAction()`'s 3rd arg to `buildSearchResponse()` must be the `GRID_ID` string, not `YourFilters::class`** — passing the Filters class name instead of the grid ID string makes search silently do nothing (page just reloads, no filters applied).
- **Grid JS must initialise in a jQuery ready callback, never on `DOMContentLoaded`** — `window.prestashop.component` is created by the admin theme in its own `$(() => initPrestashopComponents())`, which jQuery 3 runs after `DOMContentLoaded`. On `DOMContentLoaded` the components do not exist: nothing is bound, no JS error unless you log it (`scripts/grid.bundle.js` logs one).
- **Never copy a compiled webpack bundle into a module for the Grid** — use `scripts/grid.bundle.js` (core `window.prestashop.component` classes, PS 8.0+ / 9.x). A copied bundle is frozen against an old PrestaShop build, cannot be reviewed, needs the grid ID edited by hand, and the previous webpack template was itself broken (truncated module list: its bootstrap never ran).
- **One toggle extension only**: `AsyncToggleColumnExtension` (JSON controller). Adding `ColumnTogglingExtension` too makes every toggle click send two requests that cancel each other.
- **Column `sortable` option already defaults to `true`** (`AbstractColumn::configureOptions()`) — do not waste time explicitly setting `'sortable' => true` on `DataColumn`s when debugging broken sort; check that the grid script is loaded and the grid initialised (see the diagnosis checklist).
- **`ImageColumn` always renders `<img src="...">` unconditionally** — if the `src_field` value is empty/null the browser shows a broken image icon. Fix: (1) make the SQL return `NULL` (not empty string) when there is no image using `IF(photo IS NOT NULL AND photo != '', CONCAT(base_url, photo), NULL)`; (2) create a custom Twig template that guards with `{% if record[...] is not empty %}`; (3) register the module views dir under the `@PrestaShop` Twig namespace in `services.yml` and name the template `{gridId}_{columnId}_{columnType}.html.twig` — `GridExtension::getTemplatePath` checks that path first. See the "ImageColumn custom template" section below.
- **`ToggleColumn` for boolean grid columns** — always pair with a `YesAndNoChoiceType` filter. Use `ToggleColumn` (not `DataColumn`) for any `active`/boolean field. Add `YesAndNoChoiceType` filter with `setTypeOptions(['required' => false])`. The controller toggle action returns JSON `{status: bool, message: string}`. The `primary_field` option must point to the PK field name in the SELECT result. See the "ToggleColumn and boolean filters" section below.

---

## Position column and drag-and-drop — complete reference

### How it works end-to-end

1. `PositionColumn` is defined in `GridDefinitionFactory` with type `'position'`.
2. `GridPresenter::getColumns()` checks `searchCriteria->getOrderBy()`. **Only when the grid is currently sorted by `position`** does it prepend a synthetic `position_handle` column (type `'position_handle'`) at the start of the column list.
3. The `position_handle` Twig template (`@PrestaShop/Admin/Common/Grid/Columns/Content/position_handle.html.twig`) renders a `<div class="position-drag-handle js-{GRID_ID}-position">` with data attributes for ID, position, update URL and method.
4. `PositionExtension` (added by `views/js/{modulename}.bundle.js` when the grid has a position column) calls `tableDnD` on the grid table using `.js-drag-handle` as the drag handle. On drop it reads each row's data, computes old/new positions, and POSTs `positions[i][rowId]`, `positions[i][oldPosition]`, `positions[i][newPosition]` to the `update_route`.
5. `updatePositionAction` reads these via `$request->request->all()['positions']` and delegates to `GridPositionUpdaterInterface`.

### CSS: drag handle is only visible when sorted by position

```css
/* From PS theme.css — drag handle hidden by default, shown on hover only when grid-ordering-column class is present */
table.grid-ordering-column tr:hover .position-drag-handle { visibility: visible }
```

The `grid-ordering-column` class is added to the `<table>` by the Twig template only when `is_ordering_column(grid)` returns true — which itself checks that the current `orderBy` equals the `PositionColumn`'s id. **If the grid is sorted by any other column, the class is absent and no drag handle appears.**

### CRITICAL: drag-and-drop breaks when sorted or filtered by a non-position column

Drag-and-drop works in two situations:
1. **Initial state** — no sort in the URL. `Filters::getDefaults()` sets `'orderBy' => 'position'`, so `GridPresenter` sees `orderBy === 'position'` and injects the `position_handle` column.
2. **Explicitly sorted by Position** — user clicked the Position column header.

Drag-and-drop is **disabled** (the `position_handle` column is not rendered at all) when:
- The user clicks any other column header (e.g. Name, Active…), adding an `[orderBy]=name` param to the URL.
- The user applies a text filter on another column — the resulting redirect also carries a non-position `orderBy`.

URL when sorted by name (drag disabled):
```
?wsfaq_question%5BorderBy%5D=name&wsfaq_question%5BsortOrder%5D=asc
```

To re-enable drag-and-drop: click the **"Position"** column header to return to position sort. You can also tell the user: **"Drag-and-drop only works when the list is not sorted by another column. Click the Position column header (or reset filters) to re-enable it."**

**The proper UX solution:** add a `ReorderPositionsButtonType` filter for the `position` column. This renders a **"Rearrange"** button in the filter row. Clicking it resets the sort to `position` ASC and makes drag-and-drop available again immediately — no need for the user to click the column header.

```php
use PrestaShopBundle\Form\Admin\Type\ReorderPositionsButtonType;

->add((new Filter('position', ReorderPositionsButtonType::class))
    ->setAssociatedColumn('position')
)
```

This filter takes no `setTypeOptions()` — just the class and `setAssociatedColumn('position')`. Always include it whenever you declare a `PositionColumn`.

### Filters::getDefaults() — must default to `'orderBy' => 'position'`

```php
public static function getDefaults(): array
{
    return [
        'limit'     => 20,
        'offset'    => 0,
        'orderBy'   => 'position',   // REQUIRED — enables drag-and-drop on first load
        'sortOrder' => 'asc',
        'filters'   => [],
    ];
}
```

### PositionColumn options

```php
(new PositionColumn('position'))           // column ID must be 'position'
    ->setName($this->trans('Position', [], 'Admin.Global'))
    ->setOptions([
        'id_field'             => 'id_myentity',   // PK field name in the SELECT result
        'position_field'       => 'position',       // position field name in SELECT result
        'update_method'        => 'POST',
        'update_route'         => 'mymodule_myentity_update_position',
        'record_route_params'  => [
            'id_myentity' => 'entityId',  // maps SELECT field → route param name
        ],
    ])
```

### QueryBuilder must SELECT position

The `position` field must be in the `SELECT`. The `position_handle` template reads `record[column.options.position_field]`, so if `position` is absent from the query result the drag handle will render with empty data attributes and the drop handler will break silently.

```php
$qb->select(
    'e.id_myentity',
    'e.position',      // REQUIRED — used by position_handle template
    'e.active',
    'el.name'
);
```

### PositionDefinition in services.yml

```yaml
mymodule.grid.position_definition:
  class: 'PrestaShop\PrestaShop\Core\Grid\Position\PositionDefinition'
  arguments:
    $table:         'prefix_mymodule_items'   # WITHOUT DB prefix — handler adds it at runtime
    $idField:       'id_myentity'
    $positionField: 'position'
```

### updatePositionAction — read positions array correctly

```php
// CORRECT — InputBag::get() throws BadRequestException on array values
$positionsData = ['positions' => $request->request->all()['positions'] ?? []];

// WRONG — throws: Input value "positions" contains a non-scalar value
$positionsData = ['positions' => $request->request->get('positions')];
```

### Replying to users about drag not working

If a user reports that drag-and-drop stopped working or the drag handle is missing:

1. **Check the URL** — if `%5BorderBy%5D=name` (or any column other than `position`) is present in the URL, the grid is sorted by that column and drag is intentionally disabled by PS.
2. **Fix**: click the "Position" column header to sort by position → drag-and-drop reactivates.
3. **Check disk quota** — if `var/cache/` cannot be written (errno=122, Disk quota exceeded), the Twig cache is stale. Clean `var/cache/dev/` to free space, then reinstall the module so the cache rebuilds.
4. **Check the grid script** — `views/js/{modulename}.bundle.js` must be loaded (no 404), be the current
   `scripts/grid.bundle.js` (not an old minified webpack copy), and the grid must be initialised
   (`#{GRID_ID}_grid` has `data-grid-initialized="1"`). `PositionExtension` is only added when the grid renders
   the "Rearrange" button (`ReorderPositionsButtonType` filter, PS 8.2+) or drag handles.

---

## ImageColumn custom template — no broken image when src is null

`ImageColumn` uses the PS core template `@PrestaShop/Admin/Common/Grid/Columns/Content/image.html.twig` which renders `<img src="...">` unconditionally — if the value is empty/null the browser shows a broken image icon.

**Full fix (3 steps):**

**Step 1 — SQL returns NULL when no image:**
```php
// BAD: always produces a URL even with empty photo
"CONCAT('" . __PS_BASE_URI__ . "modules/mymodule/upload/', COALESCE(photo, '')) AS photo_src"

// GOOD: NULL when no photo
"IF(photo IS NOT NULL AND photo != '', CONCAT('" . __PS_BASE_URI__ . "modules/mymodule/upload/', photo), NULL) AS photo_src"
```

**Step 2 — Custom Twig template with null guard:**

Create `views/PrestaShop/Admin/Common/Grid/Columns/Content/{gridId}_{columnId}_image.html.twig`:
```twig
{% if record[column.options.src_field] is not empty %}
    <img src="{{ record[column.options.src_field] }}" style="max-height:40px;" />
{% endif %}
```
Filename pattern: `{GRID_ID}_{column_id}_image.html.twig` (e.g. `wsfaq_question_photo_src_image.html.twig`).

**Step 3 — Register module views dir under `@PrestaShop` Twig namespace in `services.yml`:**
```yaml
twig.loader.filesystem:
  calls:
    - [addPath, ['%kernel.project_dir%/modules/mymodule/views/PrestaShop', 'PrestaShop']]
```

`GridExtension::getTemplatePath` checks templates in this order:
1. `@PrestaShop/.../{gridId}_{columnId}_{type}.html.twig` ← **custom template found here first**
2. `@PrestaShop/.../{gridId}_{type}.html.twig`
3. `@PrestaShop/.../{type}.html.twig` ← core fallback

This override is grid+column specific — no other PS grid is affected.

**NEVER** put uploads inside `views/` — the `views/` folder is for Twig templates only. User-uploaded files must go in a dedicated directory at module root (e.g. `upload/`, `images/`, `files/`) with a proper `.htaccess`. The `views/PrestaShop/` subtree added above is only for template overrides, not for file storage.

---

## ToggleColumn and boolean filters — complete pattern

### ToggleColumn declaration

```php
(new ToggleColumn('active'))
    ->setName($this->trans('Active', [], 'Admin.Global'))
    ->setOptions([
        'field'           => 'active',        // field name in SELECT result
        'primary_field'   => 'id_myentity',   // PK field name in SELECT result
        'route'           => 'mymodule_myentity_toggle_status',
        'route_param_name' => 'entityId',     // name used in route + controller arg
    ])
```

### YesAndNoChoiceType filter (always pair with ToggleColumn)

```php
use PrestaShopBundle\Form\Admin\Type\YesAndNoChoiceType;

->add((new Filter('active', YesAndNoChoiceType::class))
    ->setTypeOptions(['required' => false])
    ->setAssociatedColumn('active')
)
```

- No `attr` / `placeholder` needed — `YesAndNoChoiceType` renders a native `<select>` with "---", "Yes", "No".
- The `setAssociatedColumn` value must match the column ID **and** the field name used in `getFilters()` of the `QueryBuilder`.

### Toggle controller action

```php
public function toggleStatus(Request $request, int $entityId): Response
{
    // load entity by $entityId, flip ->active, save
    return $this->json([
        'status'  => true,
        'message' => $this->trans('The status has been successfully updated.', 'Admin.Notifications.Success', []),
    ]);
}
```

The route param name (`entityId` here) **must match** both `route_param_name` in `ToggleColumn` options and the controller method argument name.

### QueryBuilder: filter active by boolean value

```php
if (isset($filters['active']) && $filters['active'] !== '') {
    $qb->andWhere('e.active = :active')
       ->setParameter('active', (int) $filters['active']);
}
```
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