Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Documenting and cleaning up

  • Loading branch information...
commit de1bf43070ca0f750a74d4464e6ac689a2fee042 1 parent e40c150
@lorenzo lorenzo authored
Showing with 39 additions and 20 deletions.
  1. +38 −19 src/ORM/EagerLoader.php
  2. +1 −1  src/ORM/Query.php
View
57 src/ORM/EagerLoader.php
@@ -21,7 +21,10 @@
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 {
@@ -31,7 +34,7 @@ class EagerLoader {
*
* @var array
*/
- protected $_containments;
+ protected $_containments = [];
/**
* Contains a nested array with the compiled containments tree
@@ -58,24 +61,40 @@ class EagerLoader {
];
/**
- * A list of associations that should be eagerly loaded
+ * A list of associations that should be loaded with a separate query
*
* @var array
*/
- protected $_loadEagerly = [];
+ protected $_loadExternal = [];
- public function contain($associations = null, $override = false) {
- if ($this->_containments === null || $override) {
- $this->_containments = [];
- $this->_normalized = null;
- }
-
- if ($associations === null) {
- return $this->_containments;
- }
+/**
+ * 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.
+ *
+ * @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
+ */
+ public function contain($associations = []) {
if (empty($associations)) {
- return;
+ return $this->_containments;
}
$associations = (array)$associations;
@@ -86,8 +105,8 @@ public function contain($associations = null, $override = false) {
}
$associations = $this->_reformatContain($associations, $this->_containments);
- $this->_containments = $associations;
$this->_normalized = null;
+ return $this->_containments = $associations;
}
public function matching($assoc, callable $builder = null) {
@@ -136,7 +155,7 @@ public function normalized(Table $repository) {
public function hasExternal(Table $repository) {
$this->normalized($repository);
- return !empty($this->_loadEagerly);
+ return !empty($this->_loadExternal);
}
/**
@@ -238,7 +257,7 @@ protected function _normalizeContain(Table $parent, $alias, $options) {
}
if (!$config['canBeJoined']) {
- $this->_loadEagerly[$alias] = $config;
+ $this->_loadExternal[$alias] = $config;
}
return $config;
@@ -278,7 +297,7 @@ public function eagerLoad($query, $statement) {
$driver = $query->connection()->driver();
list($collected, $statement) = $this->_collectKeys($query, $statement);
- foreach ($this->_loadEagerly as $meta) {
+ foreach ($this->_loadExternal as $meta) {
$contain = $meta['associations'];
$alias = $meta['instance']->source()->alias();
$keys = isset($collected[$alias]) ? $collected[$alias] : null;
@@ -301,7 +320,7 @@ public function eagerLoad($query, $statement) {
*/
protected function _collectKeys($query, $statement) {
$collectKeys = [];
- foreach ($this->_loadEagerly as $meta) {
+ foreach ($this->_loadExternal as $meta) {
$source = $meta['instance']->source();
if ($meta['instance']->requiresKeys($meta['config'])) {
$alias = $source->alias();
View
2  src/ORM/Query.php
@@ -302,7 +302,7 @@ public function contain($associations = null, $override = false) {
$this->_eagerLoader = null;
}
- $result = $this->eagerLoader()->contain($associations, $override);
+ $result = $this->eagerLoader()->contain($associations);
if ($associations !== null || $override) {
$this->_dirty();
}
Please sign in to comment.
Something went wrong with that request. Please try again.