Doctrine\ORM\QueryBuilder 原始碼解析之 where

背景

最近有需求實現類似於 QueryBuilder 的謂詞語句，就去翻看了它的原始碼。先看兩個例子
例子1

$qb = $em->createQueryBuilder();
$qb->select('*')->from('User', 'u')->where('u.id = 1');
echo $qb->getDQL();

例子2

$qb = $em->createQueryBuilder();
$qb->select('*')
->from('User', 'u')
->where('u.id = 1')
->andWhere('u.score >= 90')
->orWhere('u.score <= 100');
echo $qb->getDQL();

是不是有點懵逼，希望看完我的文章，希望你有所收穫。
接下來會以例子2講解，分別解釋 where、andWhere、orWhere 方法，圖文並茂，一步步教你理解上述PHP程式碼轉換為sql語句的原理。

程式碼不難，建議大家配合原始碼食用。[相關原始碼在此]https://github.com/doctrine/orm/blob/master/lib/Doctrine/ORM/QueryBuilder.php(https://github.com/doctrine/orm/blob/master/lib/Doctrine/ORM/QueryBuilder.php
)

新增謂詞語句

先看 QueryBuilder::where 方法，生成了一個Andx謂詞物件 $predicates，

public function where($predicates)
{
if ( ! (func_num_args() == 1 && $predicates instanceof Expr\Composite)) {
$predicates = new Expr\Andx(func_get_args());
}

return $this->add('where', $predicates);
}

執行 var_export($predicates) 後檢視成員變數如下，separator 是 where 子句條件之間的連線符，有 AND 和 OR。parts 是由條件組成的陣列。

// var_export($predicates)的輸出
Doctrine\ORM\Query\Expr\Andx::__set_state(array(
'separator' => ' AND ',
'allowedClasses' => 
array (
0 => 'Doctrine\\ORM\\Query\\Expr\\Comparison',
1 => 'Doctrine\\ORM\\Query\\Expr\\Func',
2 => 'Doctrine\\ORM\\Query\\Expr\\Orx',
3 => 'Doctrine\\ORM\\Query\\Expr\\Andx',
),
'preSeparator' => '(',
'postSeparator' => ')',
'parts' => 
array (
0 => 'u.id = 1',
),
))

接下來執行的return $this->add('where', $predicates);函式很簡單，把謂詞物件作為QueryBuilder::_dqlParts中的key為where的value，列印QueryBuilder物件如下

// 此函式有刪減，完整請看官方原始碼
// QueryBuilder的add方法
public function add($dqlPartName, $dqlPart, $append = false)
{
$isMultiple = is_array($this->_dqlParts[$dqlPartName])
&& !($dqlPartName == 'join' && !$append);
// $isMultiple 這裡的值為 false
$this->_dqlParts[$dqlPartName] = ($isMultiple) ? [$dqlPart] : $dqlPart;
$this->_state = self::STATE_DIRTY;

return $this;
}

// _dqlParts 結構
array (
...
'where' => 
Doctrine\ORM\Query\Expr\Andx::__set_state(array(
'separator' => ' AND ',
'allowedClasses' => 
array (
0 => 'Doctrine\\ORM\\Query\\Expr\\Comparison',
1 => 'Doctrine\\ORM\\Query\\Expr\\Func',
2 => 'Doctrine\\ORM\\Query\\Expr\\Orx',
3 => 'Doctrine\\ORM\\Query\\Expr\\Andx',
),
'preSeparator' => '(',
'postSeparator' => ')',
'parts' => 
array (
0 => 'u.id = 1',
),
))
...

接下來具體看 QueryBuilder::andWhere方法，
getDQLPart取出的是剛才設定的Andx物件，接著執行Andx的addMultiple方法，最終呼叫的是Andx::add方法，這個方法最終是把'u.score >= 90'加入到Andx::parts陣列中

// QueryBuilder
public function andWhere()
{
$args = func_get_args();
$where = $this->getDQLPart('where');

if ($where instanceof Expr\Andx) {
$where->addMultiple($args);
} else {
array_unshift($args, $where);
$where = new Expr\Andx($args);
}

return $this->add('where', $where);
}

// Andx
public function add($arg)
{
if ( $arg !== null && (!$arg instanceof self || $arg->count() > 0) ) {
// If we decide to keep Expr\Base instances, we can use this check
if ( ! is_string($arg)) {
$class = get_class($arg);

if ( ! in_array($class, $this->allowedClasses)) {
throw new \InvalidArgumentException("Expression of type '$class' not allowed in this context.");
}
}

$this->parts[] = $arg;
}

return $this;
}

所以此時Andx::parts陣列中有了兩個元素：'u.id = 1' 和 'u.score >= 90'

Doctrine\ORM\Query\Expr\Andx::__set_state(array(
'separator' => ' AND ',
'allowedClasses' => 
array (
0 => 'Doctrine\\ORM\\Query\\Expr\\Comparison',
1 => 'Doctrine\\ORM\\Query\\Expr\\Func',
2 => 'Doctrine\\ORM\\Query\\Expr\\Orx',
3 => 'Doctrine\\ORM\\Query\\Expr\\Andx',
),
'preSeparator' => '(',
'postSeparator' => ')',
'parts' => 
array (
0 => 'u.id = 1',
1 => 'u.score >= 90',
),
))

繼續看QueryBuilder::orWhere 方法，取出的 $where 是剛剛andWhere 執行後設定的 Andx 物件，執行 array_unshift($args, $where)語句後，形成的 $args 由一個 Andx 物件和一個字串 'u.score <= 100'組成。

public function orWhere()
{
$args = func_get_args();
$where = $this->getDQLPart('where');

if ($where instanceof Expr\Orx) {
$where->addMultiple($args);
} else {
array_unshift($args, $where);
$where = new Expr\Orx($args);
}

return $this->add('where', $where);
}

將包含 Andx 物件和字串 u.score <= 100的 $args 陣列作為 Orx 物件的構造方法，Orx 建構函式的內部實現是 addMultiple方法，最終呼叫 Orx::add 方法將 $args 中的元素全部都加到 Orx物件 的 $parts 物件中，最終 Orx 物件的 parts 內容的示意圖的階段 3 所示

我整理了一下新增邏輯如下所示

解析謂詞語句

謂詞物件轉換成謂詞語句其實就是一句話，

$queryPart = $this->getDQLPart($queryPartName);
echo $queryPart;

不要覺得奇怪，物件也可以當作字串用，引用PHP手冊上的原話

__toString() 方法用於一個類被當成字串時應怎樣回應。

謂詞物件的__toString的實現在Doctrine\ORM\Query\Expr\Composite，一起來看看

public function __toString()
{
if ($this->count() === 1) {
return (string) $this->parts[0];
}

$components = [];

foreach ($this->parts as $part) {
$components[] = $this->processQueryPart($part);
}

return implode($this->separator, $components);
}

private function processQueryPart($part)
{
$queryPart = (string) $part;

if (is_object($part) && $part instanceof self && $part->count() > 1) {
return $this->preSeparator . $queryPart . $this->postSeparator;
}

if (stripos($queryPart, ' OR ') !== false || stripos($queryPart, ' AND ') !== false) {
return $this->preSeparator . $queryPart . $this->postSeparator;
}

return $queryPart;
}

帶入之前組合好的 Orx 物件，一起來分析下。Orx 物件parts屬性的兩個元素分別會被帶入processQueryPart執行。
Andx 你先來，走到$queryPart = (string) $part，我們希望$part被當作字串處理,繼續回到__toString，這裡是個遞迴。
Andx物件parts屬性的兩個字串元素繼續帶入processQueryPart執行。這兩個字串經過處理會作為Andx物件的$components的元素，最終經過implode($this->separator, $components)返回字串 u.id=1 and u.score >= 90 ，此時的值會被返回到 $queryPart。

接下來執行到的是 return $this->preSeparator . $queryPart . $this->postSeparator; 到 Orx 物件的 $components的陣列中去。

// $part 是 Andx 物件
// Andx 物件 經過字串化後成了 u.id=1 and u.score >= 90，賦值給 $queryPart
$queryPart = (string) $part;

// 因為Andx物件有兩個條件，所以左右兩邊會被加上括號，最終返回 (u.id = 1 AND u.score >= 90)
if (is_object($part) && $part instanceof self && $part->count() > 1) {
return $this->preSeparator . $queryPart . $this->postSeparator;
}

Orx 物件parts屬性的第一個元素已經處理完畢，接下來是第二個元素u.score <= 100，字串就很簡單了，直接返回到 Orx 物件的 $components 中去！
現在來看看Orx 物件的 $components中間有啥了

array (
0 => '(u.id = 1 AND u.score >= 90)',
1 => 'u.score <= 100',
)

再用implode切割成字串 結果就是出來了(u.id = 1 AND u.score >= 90) OR u.score <= 100,解析完畢！看不懂的同學看我整理的流程圖。

總結

具體細節大家可以使用 phpStorm + xdebug 單步除錯研究。