/
EagerLoader.php
623 lines (561 loc) · 19 KB
/
EagerLoader.php
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
<?php
/**
* CakePHP(tm) : Rapid Development Framework (http://cakephp.org)
* Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
*
* Licensed under The MIT License
* For full copyright and license information, please see the LICENSE.txt
* Redistributions of files must retain the above copyright notice.
*
* @copyright Copyright (c) Cake Software Foundation, Inc. (http://cakefoundation.org)
* @link http://cakephp.org CakePHP(tm) Project
* @since 3.0.0
* @license http://www.opensource.org/licenses/mit-license.php MIT License
*/
namespace Cake\ORM;
use Cake\Database\Statement\BufferedStatement;
use Cake\Database\Statement\CallbackStatement;
use Cake\ORM\Association;
use Cake\ORM\Query;
use Cake\ORM\Table;
use Closure;
/**
* Exposes the methods for storing the associations that should be eager loaded
* for a table once a query is provided and delegates the job of creating the
* required joins and decorating the results so that those associations can be
* part of the result set.
*/
class EagerLoader {
/**
* Nested array describing the association to be fetched
* and the options to apply for each of them, if any
*
* @var array
*/
protected $_containments = [];
/**
* Contains a nested array with the compiled containments tree
* This is a normalized version of the user provided containments array.
*
* @var array
*/
protected $_normalized;
/**
* List of options accepted by associations in contain()
* index by key for faster access
*
* @var array
*/
protected $_containOptions = [
'associations' => 1,
'foreignKey' => 1,
'conditions' => 1,
'fields' => 1,
'sort' => 1,
'matching' => 1,
'queryBuilder' => 1,
'finder' => 1,
'joinType' => 1,
'strategy' => 1
];
/**
* A list of associations that should be loaded with a separate query
*
* @var array
*/
protected $_loadExternal = [];
/**
* Contains a list of the association names that are to be eagerly loaded
*
* @var array
*/
protected $_aliasList = [];
/**
* Another EagerLoader instance that will be used for 'matching' associations.
*
* @var \Cake\ORM\EagerLoader
*/
protected $_matching;
/**
* A map of table aliases pointing to the association objects they represent
* for the query.
*
* @var array
*/
protected $_joinsMap = [];
/**
* Sets the list of associations that should be eagerly loaded along for a
* specific table using when a query is provided. The list of associated tables
* passed to this method must have been previously set as associations using the
* Table API.
*
* Associations can be arbitrarily nested using dot notation or nested arrays,
* this allows this object to calculate joins or any additional queries that
* must be executed to bring the required associated data.
*
* Accepted options per passed association:
*
* - foreignKey: Used to set a different field to match both tables, if set to false
* no join conditions will be generated automatically
* - fields: An array with the fields that should be fetched from the association
* - queryBuilder: Equivalent to passing a callable instead of an options array
* - matching: Whether to inform the association class that it should filter the
* main query by the results fetched by that class.
* - joinType: For joinable associations, the SQL join type to use.
*
* @param array|string $associations list of table aliases to be queried.
* When this method is called multiple times it will merge previous list with
* the new one.
* @return array Containments.
*/
public function contain($associations = []) {
if (empty($associations)) {
return $this->_containments;
}
$associations = (array)$associations;
$associations = $this->_reformatContain($associations, $this->_containments);
$this->_normalized = $this->_loadExternal = null;
$this->_aliasList = [];
return $this->_containments = $associations;
}
/**
* Adds a new association to the list that will be used to filter the results of
* any given query based on the results of finding records for that association.
* You can pass a dot separated path of associations to this method as its first
* parameter, this will translate in setting all those associations with the
* `matching` option.
*
* @param string $assoc A single association or a dot separated path of associations.
* @param callable|null $builder the callback function to be used for setting extra
* options to the filtering query
* @return array The resulting containments array
*/
public function matching($assoc = null, callable $builder = null) {
if ($this->_matching === null) {
$this->_matching = new self();
}
if ($assoc === null) {
return $this->_matching->contain();
}
$assocs = explode('.', $assoc);
$last = array_pop($assocs);
$containments = [];
$pointer =& $containments;
foreach ($assocs as $name) {
$pointer[$name] = ['matching' => true];
$pointer =& $pointer[$name];
}
$pointer[$last] = ['queryBuilder' => $builder, 'matching' => true];
return $this->_matching->contain($containments);
}
/**
* Returns the fully normalized array of associations that should be eagerly
* loaded for a table. The normalized array will restructure the original array
* by sorting all associations under one key and special options under another.
*
* Additionally it will set an 'instance' key per association containing the
* association instance from the corresponding source table
*
* @param \Cake\ORM\Table $repository The table containing the association that
* will be normalized
* @return array
*/
public function normalized(Table $repository) {
if ($this->_normalized !== null || empty($this->_containments)) {
return (array)$this->_normalized;
}
$contain = [];
foreach ($this->_containments as $alias => $options) {
if (!empty($options['instance'])) {
$contain = (array)$this->_containments;
break;
}
$contain[$alias] =& $this->_normalizeContain(
$repository,
$alias,
$options,
['root' => null]
);
}
$this->_fixStrategies();
return $this->_normalized = $contain;
}
/**
* Formats the containments array so that associations are always set as keys
* in the array. This function merges the original associations array with
* the new associations provided
*
* @param array $associations user provided containments array
* @param array $original The original containments array to merge
* with the new one
* @return array
*/
protected function _reformatContain($associations, $original) {
$result = $original;
foreach ((array)$associations as $table => $options) {
$pointer =& $result;
if (is_int($table)) {
$table = $options;
$options = [];
}
if (isset($this->_containOptions[$table])) {
$pointer[$table] = $options;
continue;
}
if (strpos($table, '.')) {
$path = explode('.', $table);
$table = array_pop($path);
foreach ($path as $t) {
$pointer += [$t => []];
$pointer =& $pointer[$t];
}
}
if (is_array($options)) {
$options = isset($options['config']) ?
$options['config'] + $options['associations'] :
$options;
$options = $this->_reformatContain($options, []);
}
if ($options instanceof Closure) {
$options = ['queryBuilder' => $options];
}
$pointer += [$table => []];
$pointer[$table] = $options + $pointer[$table];
}
return $result;
}
/**
* Modifies the passed query to apply joins or any other transformation required
* in order to eager load the associations described in the `contain` array.
* This method will not modify the query for loading external associations, i.e.
* those that cannot be loaded without executing a separate query.
*
* @param \Cake\ORM\Query $query The query to be modified
* @param \Cake\ORM\Table $repository The repository containing the associations
* @param bool $includeFields whether to append all fields from the associations
* to the passed query. This can be overridden according to the settings defined
* per association in the containments array
* @return void
*/
public function attachAssociations(Query $query, Table $repository, $includeFields) {
if (empty($this->_containments) && $this->_matching === null) {
return;
}
foreach ($this->attachableAssociations($repository) as $options) {
$config = $options['config'] + [
'aliasPath' => $options['aliasPath'],
'propertyPath' => $options['propertyPath'],
'includeFields' => $includeFields
];
$options['instance']->attachTo($query, $config);
}
}
/**
* Returns an array with the associations that can be fetched using a single query,
* the array keys are the association aliases and the values will contain an array
* with the following keys:
*
* - instance: the association object instance
* - config: the options set for fetching such association
*
* @param \Cake\ORM\Table $repository The table containing the associations to be
* attached
* @return array
*/
public function attachableAssociations(Table $repository) {
$contain = $this->normalized($repository);
$matching = $this->_matching ? $this->_matching->normalized($repository) : [];
return $this->_resolveJoins($contain, $matching);
}
/**
* Returns an array with the associations that need to be fetched using a
* separate query, each array value will contain the following keys:
*
* - instance: the association object instance
* - config: the options set for fetching such association
*
* @param \Cake\ORM\Table $repository The table containing the associations
* to be loaded
* @return array
*/
public function externalAssociations(Table $repository) {
if ($this->_loadExternal) {
return $this->_loadExternal;
}
$contain = $this->normalized($repository);
$this->_resolveJoins($contain, []);
return $this->_loadExternal;
}
/**
* Auxiliary function responsible for fully normalizing deep associations defined
* using `contain()`
*
* @param Table $parent owning side of the association
* @param string $alias name of the association to be loaded
* @param array $options list of extra options to use for this association
* @param array $paths An array with two values, the first one is a list of dot
* separated strings representing associations that lead to this `$alias` in the
* chain of associations to be loaded. The second value is the path to follow in
* entities' properties to fetch a record of the corresponding association.
* @return array normalized associations
* @throws \InvalidArgumentException When containments refer to associations that do not exist.
*/
protected function &_normalizeContain(Table $parent, $alias, $options, $paths) {
$defaults = $this->_containOptions;
$instance = $parent->association($alias);
if (!$instance) {
throw new \InvalidArgumentException(
sprintf('%s is not associated with %s', $parent->alias(), $alias)
);
}
$paths += ['aliasPath' => '', 'propertyPath' => '', 'root' => $alias];
$paths['aliasPath'] .= '.' . $alias;
$paths['propertyPath'] .= '.' . $instance->property();
$table = $instance->target();
$extra = array_diff_key($options, $defaults);
$config = [
'associations' => [],
'instance' => $instance,
'config' => array_diff_key($options, $extra),
'aliasPath' => trim($paths['aliasPath'], '.'),
'propertyPath' => trim($paths['propertyPath'], '.')
];
$config['canBeJoined'] = $instance->canBeJoined($config['config']);
if ($config['canBeJoined']) {
$this->_aliasList[$paths['root']][$alias][] =& $config;
} else {
$paths['root'] = $config['aliasPath'];
}
foreach ($extra as $t => $assoc) {
$config['associations'][$t] =& $this->_normalizeContain($table, $t, $assoc, $paths);
}
return $config;
}
/**
* Iterates over the joinable aliases list and corrects the fetching strategies
* in order to avoid aliases collision in the generated queries.
*
* This function operates on the array references that were generated by the
* _normalizeContain() function.
*
* @return void
*/
protected function _fixStrategies() {
foreach ($this->_aliasList as &$aliases) {
foreach ($aliases as $alias => &$configs) {
if (count($configs) < 2) {
continue;
}
foreach ($configs as &$config) {
if (strpos($config['aliasPath'], '.')) {
$this->_correctStrategy($config, $alias);
}
}
}
}
}
/**
* Changes the association fetching strategy if required because of duplicate
* under the same direct associations chain
*
* This function modifies the $config variable
*
* @param array &$config The association config
* @param string $alias the name of the association to evaluate
* @return void
* @throws \RuntimeException if a duplicate association in the same chain is detected
* but is not possible to change the strategy due to conflicting settings
*/
protected function _correctStrategy(&$config, $alias) {
$currentStrategy = isset($config['config']['strategy']) ?
$config['config']['strategy'] :
'join';
if (!$config['canBeJoined'] || $currentStrategy !== 'join') {
return $config;
}
$config['canBeJoined'] = false;
$config['config']['strategy'] = $config['instance']::STRATEGY_SELECT;
}
/**
* Helper function used to compile a list of all associations that can be
* joined in the query.
*
* @param array $associations list of associations for $source
* @return array
*/
protected function _resolveJoins($associations, $matching = []) {
$result = [];
foreach ($matching as $table => $options) {
$result[$table] = $options;
$result += $this->_resolveJoins($options['associations'], []);
}
foreach ($associations as $table => $options) {
$inMatching = isset($matching[$table]);
if (!$inMatching && $options['canBeJoined']) {
$result[$table] = $options;
$result += $this->_resolveJoins($options['associations'], $inMatching ? $mathching[$table] : []);
} else {
$options['canBeJoined'] = false;
$this->_loadExternal[] = $options;
}
}
return $result;
}
/**
* Decorates the passed statement object in order to inject data from associations
* that cannot be joined directly.
*
* @param \Cake\ORM\Query $query The query for which to eager load external
* associations
* @param \Cake\Database\StatementInterface $statement The statement created after executing the $query
* @return CallbackStatement statement modified statement with extra loaders
*/
public function loadExternal($query, $statement) {
$external = $this->externalAssociations($query->repository());
if (empty($external)) {
return $statement;
}
$driver = $query->connection()->driver();
list($collected, $statement) = $this->_collectKeys($external, $query, $statement);
foreach ($external as $meta) {
$contain = $meta['associations'];
$alias = $meta['instance']->source()->alias();
$requiresKeys = $meta['instance']->requiresKeys($meta['config']);
if ($requiresKeys && empty($collected[$alias])) {
continue;
}
$keys = isset($collected[$alias]) ? $collected[$alias] : null;
$f = $meta['instance']->eagerLoader(
$meta['config'] + [
'query' => $query,
'contain' => $contain,
'keys' => $keys,
'nestKey' => $meta['aliasPath']
]
);
$statement = new CallbackStatement($statement, $driver, $f);
}
return $statement;
}
/**
* Returns an array having as keys a dotted path of associations that participate
* in this eager loader. The values of the array will contain the following keys
*
* - alias: The association alias
* - instance: The association instance
* - canBeJoined: Whether or not the association will be loaded using a JOIN
* - entityClass: The entity that should be used for hydrating the results
* - nestKey: A dotted path that can be used to inserting the data in the correct nesting.
*
* @param \Cake\ORM\Table $repository The table containing the association that
* will be normalized
* @return array
*/
public function associationsMap($table) {
$map = [];
if (!$this->matching() && !$this->contain() && empty($this->_joinsMap)) {
return $map;
}
$visitor = function ($level, $matching = false) use (&$visitor, &$map) {
foreach ($level as $assoc => $meta) {
$map[$meta['aliasPath']] = [
'alias' => $assoc,
'instance' => $meta['instance'],
'canBeJoined' => $meta['canBeJoined'],
'entityClass' => $meta['instance']->target()->entityClass(),
'nestKey' => $meta['canBeJoined'] ? $assoc : $meta['aliasPath'],
'matching' => $matching
];
if ($meta['canBeJoined'] && !empty($meta['associations'])) {
$visitor($meta['associations'], $matching);
}
}
};
$visitor($this->_matching->normalized($table), true);
$visitor($this->normalized($table));
$visitor($this->_joinsMap);
return $map;
}
/**
* Registers a table alias, typically loaded as a join in a query, as belonging to
* an association. This helps hydrators know what to do with the columns coming
* from such joined table.
*
* @param string $alias The table alias as it appears in the query.
* @param \Cake\ORM\Association $assoc The association object the alias represents.
* will be normalized
* @return void
*/
public function addToJoinsMap($alias, Association $assoc) {
$this->_joinsMap[$alias] = [
'aliasPath' => $alias,
'instance' => $assoc,
'canBeJoined' => true,
'associations' => []
];
}
/**
* Helper function used to return the keys from the query records that will be used
* to eagerly load associations.
*
* @param array $external the list of external associations to be loaded
* @param \Cake\ORM\Query $query The query from which the results where generated
* @param BufferedStatement $statement The statement to work on
* @return array
*/
protected function _collectKeys($external, $query, $statement) {
$collectKeys = [];
foreach ($external as $meta) {
if (!$meta['instance']->requiresKeys($meta['config'])) {
continue;
}
$source = $meta['instance']->source();
$keys = $meta['instance']->type() === $meta['instance']::MANY_TO_ONE ?
(array)$meta['instance']->foreignKey() :
(array)$source->primaryKey();
$alias = $source->alias();
$pkFields = [];
foreach ($keys as $key) {
$pkFields[] = key($query->aliasField($key, $alias));
}
$collectKeys[$alias] = [$alias, $pkFields, count($pkFields) === 1];
}
if (empty($collectKeys)) {
return [[], $statement];
}
if (!($statement instanceof BufferedStatement)) {
$statement = new BufferedStatement($statement, $query->connection()->driver());
}
return [$this->_groupKeys($statement, $collectKeys), $statement];
}
/**
* Helper function used to iterate a statement and extract the columns
* defined in $collectKeys
*
* @param \Cake\Database\StatementInterface $statement The statement to read from.
* @param array $collectKeys The keys to collect
* @return array
*/
protected function _groupKeys($statement, $collectKeys) {
$keys = [];
while ($result = $statement->fetch('assoc')) {
foreach ($collectKeys as $parts) {
// Missed joins will have null in the results.
if ($parts[2] && !isset($result[$parts[1][0]])) {
continue;
}
if ($parts[2]) {
$keys[$parts[0]][] = $result[$parts[1][0]];
continue;
}
$collected = [];
foreach ($parts[1] as $key) {
$collected[] = $result[$key];
}
$keys[$parts[0]][] = $collected;
}
}
$statement->rewind();
return $keys;
}
}