[12.x] Added Automatic Relation Loading (Eager Loading) Feature

src/Illuminate/Database/Eloquent/Builder.php

@@ -854,9 +854,13 @@ public function get($columns = ['*'])
  $models = $builder->eagerLoadRelations($models);
  }
 
- return $this->applyAfterQueryCallbacks(
- $builder->getModel()->newCollection($models)
- );
+ $collection = $builder->getModel()->newCollection($models);
+
+ if (Model::isAutomaticallyEagerLoadingRelationships()) {
+ $collection->withRelationshipAutoloading();
+ }
+
+ return $this->applyAfterQueryCallbacks($collection);
  }
 
  /**

src/Illuminate/Database/Eloquent/Collection.php

@@ -248,6 +248,35 @@ public function loadMissing($relations)
  return $this;
  }
 
+ /**
+ * Load a relationship path for models of the given type if it is not already eager loaded.
+ *
+ * @param array<int, <string, class-string>> $tuples
+ * @return void
+ */
+ public function loadMissingRelationshipChain(array $tuples)
+ {
+ [$relation, $class] = array_shift($tuples);
+
+ $this->filter(function ($model) use ($relation, $class) {
+ return ! is_null($model) &&
+ ! $model->relationLoaded($relation) &&
+ $model::class === $class;
+ })->load($relation);
+
+ if (empty($tuples)) {
+ return;
+ }
+
+ $models = $this->pluck($relation)->whereNotNull();
+
+ if ($models->first() instanceof BaseCollection) {
+ $models = $models->collapse();
+ }
+
+ (new static($models))->loadMissingRelationshipChain($tuples);
+ }
+
  /**
  * Load a relationship path if it is not already eager loaded.
  *
@@ -721,6 +750,24 @@ protected function duplicateComparator($strict)
  return fn ($a, $b) => $a->is($b);
  }
 
+ /**
+ * Enable relationship autoloading for all models in this collection.
+ *
+ * @return $this
+ */
+ public function withRelationshipAutoloading()
+ {
+ $callback = fn ($tuples) => $this->loadMissingRelationshipChain($tuples);
+
+ foreach ($this as $model) {
+ if (! $model->hasRelationAutoloadCallback()) {
+ $model->autoloadRelationsUsing($callback);
+ }
+ }
+
+ return $this;
+ }
+
  /**
  * Get the type of the entities being queued.
  *

src/Illuminate/Database/Eloquent/Concerns/HasAttributes.php

@@ -551,6 +551,10 @@ public function getRelationValue($key)
  return;
  }
 
+ if ($this->attemptToAutoloadRelation($key)) {
+ return $this->relations[$key];
+ }
+
  if ($this->preventsLazyLoading) {
  $this->handleLazyLoadingViolation($key);
  }

src/Illuminate/Database/Eloquent/Concerns/HasRelationships.php

@@ -39,6 +39,13 @@ trait HasRelationships
  */
  protected $touches = [];
 
+ /**
+ * The relationship autoloader callback.
+ *
+ * @var \Closure|null
+ */
+ protected $relationAutoloadCallback = null;
+
  /**
  * The many to many relationship methods.
  *
@@ -92,6 +99,97 @@ public static function resolveRelationUsing($name, Closure $callback)
  );
  }
 
+ /**
+ * Determine if a relationship autoloader callback has been defined.
+ *
+ * @return bool
+ */
+ public function hasRelationAutoloadCallback()
+ {
+ return ! is_null($this->relationAutoloadCallback);
+ }
+
+ /**
+ * Define an automatic relationship autoloader callback for this model and its relations.
+ *
+ * @param \Closure $callback
+ * @param mixed $context
+ * @return $this
+ */
+ public function autoloadRelationsUsing(Closure $callback, $context = null)
+ {
+ $this->relationAutoloadCallback = $callback;
+
+ foreach ($this->relations as $key => $value) {
+ $this->propagateRelationAutoloadCallbackToRelation($key, $value, $context);
+ }
+
+ return $this;
+ }
+
+ /**
+ * Attempt to autoload the given relationship using the autoload callback.
+ *
+ * @param string $key
+ * @return bool
+ */
+ protected function attemptToAutoloadRelation($key)
+ {
+ if (! $this->hasRelationAutoloadCallback()) {
+ return false;
+ }
+
+ $this->invokeRelationAutoloadCallbackFor($key, []);
+
+ return $this->relationLoaded($key);
+ }
+
+ /**
+ * Invoke the relationship autoloader callback for the given relationships.
+ *
+ * @param string $key
+ * @param array $tuples
+ * @return void
+ */
+ protected function invokeRelationAutoloadCallbackFor($key, $tuples)
+ {
+ $tuples = array_merge([[$key, get_class($this)]], $tuples);
+
+ call_user_func($this->relationAutoloadCallback, $tuples);
+ }
+
+ /**
+ * Propagate the relationship autoloader callback to the given related models.
+ *
+ * @param string $key
+ * @param mixed $values
+ * @param mixed $context
+ * @return void
+ */
+ protected function propagateRelationAutoloadCallbackToRelation($key, $models, $context = null)
+ {
+ if (! $this->hasRelationAutoloadCallback() || ! $models) {
+ return;
+ }
+
+ if ($models instanceof Model) {
+ $models = [$models];
+ }
+
+ if (! is_iterable($models)) {
+ return;
+ }
+
+ $callback = fn (array $tuples) => $this->invokeRelationAutoloadCallbackFor($key, $tuples);
+
+ foreach ($models as $model) {
+ // Check if relation autoload contexts are different to avoid circular relation autoload...
+ if (is_null($context) || $context !== $model) {
+ $model->autoloadRelationsUsing($callback, $context);
+ }
+ }
+ }
+
  /**
  * Define a one-to-one relationship.
  *
@@ -988,6 +1086,8 @@ public function setRelation($relation, $value)
  {
  $this->relations[$relation] = $value;
 
+ $this->propagateRelationAutoloadCallbackToRelation($relation, $value, $this);
+
  return $this;
  }
 

src/Illuminate/Database/Eloquent/Model.php

@@ -178,6 +178,13 @@ abstract class Model implements Arrayable, ArrayAccess, CanBeEscapedWhenCastToSt
  */
  protected static $modelsShouldPreventLazyLoading = false;
 
+ /**
+ * Indicates whether relations should be automatically loaded on all models when they are accessed.
+ *
+ * @var bool
+ */
+ protected static $modelsShouldAutomaticallyEagerLoadRelationships = false;
+
  /**
  * The callback that is responsible for handling lazy loading violations.
  *
@@ -446,6 +453,17 @@ public static function preventLazyLoading($value = true)
  static::$modelsShouldPreventLazyLoading = $value;
  }
 
+ /**
+ * Determine if model relationships should be automatically eager loaded when accessed.
+ *
+ * @param bool $value
+ * @return void
+ */
+ public static function automaticallyEagerLoadRelationships($value = true)
+ {
+ static::$modelsShouldAutomaticallyEagerLoadRelationships = $value;
+ }
+
  /**
  * Register a callback that is responsible for handling lazy loading violations.
  *
@@ -2231,6 +2249,16 @@ public static function preventsLazyLoading()
  return static::$modelsShouldPreventLazyLoading;
  }
 
+ /**
+ * Determine if relationships are being automatically eager loaded when accessed.
+ *
+ * @return bool
+ */
+ public static function isAutomaticallyEagerLoadingRelationships()
+ {
+ return static::$modelsShouldAutomaticallyEagerLoadRelationships;
+ }
+
  /**
  * Determine if discarding guarded attribute fills is disabled.
  *

tests/Database/DatabaseEloquentBelongsToManyWithCastedAttributesTest.php

@@ -27,6 +27,7 @@ public function testModelsAreProperlyMatchedToParents()
  $model1->shouldReceive('getAttribute')->with('foo')->passthru();
  $model1->shouldReceive('hasGetMutator')->andReturn(false);
  $model1->shouldReceive('hasAttributeMutator')->andReturn(false);
+ $model1->shouldReceive('hasRelationAutoloadCallback')->andReturn(false);
  $model1->shouldReceive('getCasts')->andReturn([]);
  $model1->shouldReceive('getRelationValue', 'relationLoaded', 'relationResolver', 'setRelation', 'isRelation')->passthru();
 
@@ -36,6 +37,7 @@ public function testModelsAreProperlyMatchedToParents()
  $model2->shouldReceive('getAttribute')->with('foo')->passthru();
  $model2->shouldReceive('hasGetMutator')->andReturn(false);
  $model2->shouldReceive('hasAttributeMutator')->andReturn(false);
+ $model2->shouldReceive('hasRelationAutoloadCallback')->andReturn(false);
  $model2->shouldReceive('getCasts')->andReturn([]);
  $model2->shouldReceive('getRelationValue', 'relationLoaded', 'relationResolver', 'setRelation', 'isRelation')->passthru();