manual/new/docs/en/dql-doctrine-query-language.txt

@@ -3,6 +3,7 @@
 ++ UPDATE queries
 ++ DELETE queries
 ++ FROM clause
+++ JOIN syntax
 ++ WHERE clause
 ++ Conditional expressions
 ++ Functional Expressions
@@ -11,4 +12,4 @@
 ++ ORDER BY clause
 ++ LIMIT and OFFSET clauses
 ++ Examples
-++ BNF
+++ BNF

manual/new/docs/en/dql-doctrine-query-language/from-clause.txt

@@ -8,14 +8,6 @@ The {{FROM}} clause indicates the component or components from which to retrieve
 
 * The default join type is {{LEFT JOIN}}. This join can be indicated by the use of either {{LEFT JOIN}} clause or simply '{{,}}', hence the following queries are equal:
 
-<code>
-SELECT u.*, p.* FROM User u LEFT JOIN u.Phonenumber
 
-SELECT u.*, p.* FROM User u, u.Phonenumber p
-</code>
 
-* {{INNER JOIN}} produces an intersection between two specified components (that is, each and every record in the first component is joined to each and every record in the second component). So basically {{INNER JOIN}} can be used when you want to efficiently fetch for example all users which have one or more phonenumbers.
 
-<code>
-SELECT u.*, p.* FROM User u INNER JOIN u.Phonenumber p
-</code>

manual/new/docs/en/dql-doctrine-query-language/join-syntax.txt

@@ -0,0 +1,63 @@
+Syntax:
+
+<code>
+[[LEFT | INNER] JOIN <component_reference1>] [ON | WITH] <join_condition>, 
+[[LEFT | INNER] JOIN <component_reference2>] [ON | WITH] <join_condition>,
+... 
+[[LEFT | INNER] JOIN <component_referenceN>] [ON | WITH] <join_condition>
+</code>
+
+DQL supports two kinds of joins INNER JOINs and LEFT JOINs. For each joined component, you can optionally specify an alias.
+
+* The default join type is {{LEFT JOIN}}. This join can be indicated by the use of either {{LEFT JOIN}} clause or simply '{{,}}', hence the following queries are equal:
+
+<code>
+SELECT u.*, p.* FROM User u LEFT JOIN u.Phonenumber
+
+SELECT u.*, p.* FROM User u, u.Phonenumber p
+</code>
+
+The recommended form is the first one.
+
+* {{INNER JOIN}} produces an intersection between two specified components (that is, each and every record in the first component is joined to each and every record in the second component). So basically {{INNER JOIN}} can be used when you want to efficiently fetch for example all users which have one or more phonenumbers.
+
+<code>
+SELECT u.*, p.* FROM User u INNER JOIN u.Phonenumber p
+</code>
+
+By default DQL auto-adds the primary key join condition, so for DQL query:
+
+<code>
+SELECT u.id, p.id FROM User u LEFT JOIN u.Phonenumber
+</code>
+
+Would have a SQL equivalent:
+
+<code>
+SELECT u.id AS u__id, p.id AS p__id FROM User u LEFT JOIN Phonenumber p ON u.id = p.user_id
+</code>
+
+If you want to override this behaviour and add your own custom join condition you can do it with the {{ON}} keyword. Consider the following DQL query:
+
+<code>
+SELECT u.id, p.id FROM User u LEFT JOIN u.Phonenumber ON u.id = 2
+</code>
+
+This query would be converted into SQL:
+
+<code>
+SELECT u.id AS u__id, p.id AS p__id FROM User u LEFT JOIN Phonenumber p ON u.id = 2
+</code>
+
+Most of the time you don't need to override the primary join condition, rather you may want to add some custom conditions. This can be achieved with the {{WITH}} keyword.
+
+DQL:
+<code>
+SELECT u.id, p.id FROM User u LEFT JOIN u.Phonenumber WITH u.id = 2
+</code>
+
+SQL:
+<code>
+SELECT u.id AS u__id, p.id AS p__id FROM User u LEFT JOIN Phonenumber p ON u.id = p.user_id AND u.id = 2
+</code>
+