shipmonk/doctrine-hint-driven-sql-walker

Doctrine's SqlWalker that allows hooking multiple handlers via ->setHint() while each can edit produced SQL or its part.

2.0.2 2024-10-29 12:57 UTC

Requires

• php: ^8.1
• doctrine/orm: ^3.3.0

Requires (Dev)

• doctrine/dbal: ^4.0
• doctrine/event-manager: ^2.0
• editorconfig-checker/editorconfig-checker: 10.6.0
• ergebnis/composer-normalize: 2.44.0
• phpstan/phpstan: 1.12.6
• phpstan/phpstan-phpunit: 1.4.0
• phpstan/phpstan-strict-rules: 1.6.1
• phpunit/phpunit: 10.5.36
• shipmonk/composer-dependency-analyser: 1.7.0
• shipmonk/phpstan-rules: 3.2.1
• slevomat/coding-standard: 8.15.0
• symfony/cache: ^6.4.13
• symfony/cache-contracts: ^3.5.0

MIT

README

Since Doctrine's SqlWalker serves as a translator from DQL AST to SQL, it becomes problematic when you want to alter resulting SQL within multiple libraries by such approach. There just can be only single SqlWalker.

This library solves this issue, by providing HintHandler base class which is designed for SQL modification and can be used multiple times in $queryBuilder->setHint().

Installation:

composer require shipmonk/doctrine-hint-driven-sql-walker

Usage:

$queryBuilder
    ->setHint(Query::HINT_CUSTOM_OUTPUT_WALKER, HintDrivenSqlWalker::class)
    ->setHint(MaxExecutionTimeHintHandler::class, 1000)

Where MaxExecutionTimeHintHandler just extends our HintHandler and picks some SqlNode to hook to and alters appropriate SQL part:

class MaxExecutionTimeSqlWalker extends HintHandler
{

    public function getNodes(): array
    {
        return [SqlNode::SelectClause];
    }

    public function processNode(
        SqlNode $sqlNode,
        string $sql,
    ): string
    {
        // grab the 1000 passed to ->setHint()
        $milliseconds = $this->getHintValue();

        // edit SQL as needed
        return preg_replace(
            '~^SELECT (.*?)~',
            "SELECT /*+ MAX_EXECUTION_TIME($milliseconds) */ \\1 ",
            $sql
        );
    }

SqlNode is an enum of all walkXxx methods in Doctrine's SqlWalker, so you are able to intercept any part of AST processing the SqlWalker does.

Limitations

• Please note that since doctrine/orm 3.3.0, the produced SQL gets finalized with LIMIT / OFFSET / FOR UPDATE after SqlWalker processing is done.
  • Thus, implementors should be aware that those SQL parts can be appended to the SQL after HintHandler processing.
  • This means that e.g. placing a comment at the end of the SQL breaks LIMIT functionality completely

Implementors

• shipmonk/doctrine-mysql-optimizer-hints (since v2)
• shipmonk/doctrine-mysql-index-hints (since v3)

Compatibility