Add hints to QueryBuilder

[pmaasz]

Context

Doctrine offers with the Query class to add hints to the query which open the door to some more features regarding customizing queries. Currently hints can only be set on the query itself which covers 99% of cases to utilize that feature but in some cases only the QueryBuilder is available.

The problem

When working with a custom SqlOutputWalker a hint needs to be set on the query to trigger the walker and apply the logic to the query. In some instances that is impossible like e.g. when working with Symfony Form Extensions where only the QueryBuilder is available and yes you could also call get query but prebuilding the query is not always an option because of a lot of side effects and other sql manipulation.
Other devs also mentioned this option as a nice to have in #11849 or symfony #37582.

Possible solution

In this PR I explore the implementation of a hint param in the QueryBuilder to hold hints that should be applied to the query when it is created.

I am unsure what I could possibly break and hope that this suggestion at least opens up the discussion to widen the possibilities of hints.

[greg0ire]

There was also an attempt to contribute this before: #6359

[greg0ire]

Looks fine, although maybe you should contribute docs to https://github.com/doctrine/orm/blob/3.5.x/docs/en/reference/query-builder.rst explaining use cases for this method.

[pmaasz]

I did not see the previous PR. I will have a look and try to add documentation, thanks for the hint.

[pmaasz]

I am sorry to bother again but I showed this PR to my colleagues and they also did an internal review. One suggestion was to mirror the functionalities of the Query class and also provide the hasHint() and getHint() functions for convenience and the second was to rename addHint() to setHint() as it is strictly speaking a setter and not an adder. Before spamming commits, would this be something you align with if so I can implement that also. I do see the benefit for our application.

[greg0ire]

I agree with the renaming. Regarding hasHint and getHint, what would be the benefit?

[pmaasz]

The hasHint and getHint would firstly create feature parity with the Query for this feature and add the convience of not having to use getHints and see if the hints contain what I want to know. Example:

        //geHint example
        $hint = null;
        // $qb instanceof QueryBuilder
        $hints = $qb->getHints();
        if (array_key_exists('name', $hints)) {
            $hint = $hints['name'];
        }
        //vs
        $hint = $qb->getHint('name');


        //hasHint example
        $hints = $qb->getHints();
        if (!array_key_exists('name', $hints)) {
            $qb->setHint('name', 'value');
        }
        //vs
        if (!$qb->hasHint('name')) {
            $qb->setHint('name', 'value');
        }

[greg0ire]

Ok, but what is the benefit for your application specifically?

[pmaasz]

Our very specific case is that we built an adapter to have multiple custom SqlOutputWalkers for e.g. permissions and translations. In combination with multiple Form Extensions where we only have the QueryBuilder available we want to check if a certain hint was already set and act accordingly.

[pmaasz]

I rebased my branch to the current 3.6.x version but the pipeline fail looked unrelated to my changes.

[greg0ire]

Thanks @pmaasz !