OpenParable
Skip to content
← Back to skills

Create Grid Query Builder

Development
create-grid-query-builder

Create Grid Query Builder is an Agent Skill for development published in the PrestaShop/PrestaShop repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Create the Doctrine DBAL QueryBuilder that fetches grid rows, and optionally a GridDataFactory decorator for post-processing. The column aliases must exactly match the column IDs in the Grid Definition. Trigger: "create grid query builder for {Domain}".

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/PrestaShop/PrestaShop/blob/HEAD/.ai/Component/Grid/skills/create-grid-query-builder/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/create-grid-query-builder, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

create-grid-query-builder

Read @.ai/Component/Grid/CONTEXT.md for the factory trilogy and GridDataFactory decoration pattern.

1. Query Builder

Create src/Adapter/{Domain}/Grid/Query/{Domain}QueryBuilder.php implementing DoctrineQueryBuilderInterface or extending AbstractDoctrineQueryBuilder:

Two required methods:

  • getSearchQueryBuilder(SearchCriteriaInterface $searchCriteria): QueryBuilder — returns rows for the current page
  • getCountQueryBuilder(SearchCriteriaInterface $searchCriteria): QueryBuilder — returns total count (no LIMIT/OFFSET)

Building the query

  1. Base query: SELECT c.id_{domain}, c.name, c.active FROM ps_{domain} c
  2. For each filter in $searchCriteria->getFilters(), add a WHERE clause with parameterized values
  3. Apply sorting: map $searchCriteria->getOrderBy() to actual column expressions
  4. Apply pagination: ->setFirstResult($offset)->setMaxResults($limit) (search query only, not count)
  5. For multilingual columns: LEFT JOIN the _lang table with the current language ID

Reference: src/Core/Grid/Query/LanguageQueryBuilder.php (simple), src/Adapter/Manufacturer/QueryBuilder/ManufacturerQueryBuilder.php (with joins)

2. GridDataFactory (standard)

For most grids, the standard DoctrineGridDataFactory is sufficient — it calls the query builder automatically. Just wire it in DI:

prestashop.core.grid.data.factory.{domain}:
    class: 'PrestaShop\PrestaShop\Core\Grid\Data\Factory\DoctrineGridDataFactory'
    arguments:
        - '@prestashop.core.admin.{domain}.query_builder'
        # ... hook dispatcher, query parser, etc.

3. GridDataFactory decorator (if post-processing needed)

When grid data needs transformation after query execution (e.g. resolving image URLs from IDs, formatting computed columns), create a decorator:

  • Create a class implementing GridDataFactoryInterface
  • Inject the original GridDataFactory
  • In getData(SearchCriteriaInterface $searchCriteria): call the wrapped factory, then modify the RecordCollection
  • Register with decorates: in DI YAML
class {Domain}GridDataFactory implements GridDataFactoryInterface
{
    public function __construct(
        private readonly GridDataFactoryInterface $dataFactory,
    ) {}

    public function getData(SearchCriteriaInterface $searchCriteria): GridData
    {
        $gridData = $this->dataFactory->getData($searchCriteria);
        $modifiedRecords = $this->applyModifications($gridData->getRecords());
        return new GridData($modifiedRecords, $gridData->getRecordsTotal(), $gridData->getQuery());
    }
}

Reference: Check existing *GridDataFactory decorators in src/Adapter/ for examples.

Rules

Conventions (column alias matching, parameterized queries, PK aliasing, count query rules, decoration preference) are in Grid/CONTEXT.md.