DDC-2795: the queryBuider Expr\Join class has a ON type but unsupported by the parser

Jira issue originally created by user stof:

The Doctrine\ORM\Query\Expr\Join class has 2 cosntants for the condition types: WITH and ON.

None of them are documented. The only place where WITH appear is the EBNF, which is outdated in the doc as it does not show arbitrary joins (added in 2.3) but only association joins.

and when looking at the EBNF in the code, I find 2 different ones (none of them matching the one given in the doc):

in Doctrine\ORM\query\Parser::Join:

Join ::= ["LEFT" ["OUTER"] ]( "INNER") "JOIN"
         (JoinAssociationDeclaration | RangeVariableDeclaration)
         ["WITH" ConditionalExpression]

This is matching the implementation and ON is not supported.

in Doctrine\ORM\Query\AST\Join:

Join ::= ["LEFT" ["OUTER"] ]( "INNER") "JOIN" JoinAssociationPathExpression
         ["AS"] AliasIdentificationVariable [("ON" ]( "WITH") ConditionalExpression)

This one is missing 2 features also missing in the doc (INDEX BY for associations, and arbitrary joins) and adds the support of ON which is not implemented.

What is the reason to have this ON constant in the query builder ? It is confusing to get a DQL parse exception when using it if it is there.

On a side note, what is the canonical source for the EBNF ? There is 2 different locations in the code (the phpdoc of parser methods and the phpdoc of AST nodes created by the parser), plus the doc. Shouldn't we try to limit the duplication and have a way to check the consistency of the doc ?

doctrine / orm

DDC-2795: the queryBuider Expr\Join class has a ON type but unsupported by the parser #3544