HasOneOrMany.php
TLDR
This file defines the abstract class HasOneOrMany which is used for creating relationships of type "has one" or "has many" in Laravel Eloquent. It contains several methods for creating, updating, and querying related models.
Methods
__construct
This method is the constructor of the HasOneOrMany class. It initializes the foreign key and local key of the relationship.
make
This method creates and returns an instance of the related model without saving it to the database.
makeMany
This method creates and returns multiple instances of the related model without saving them to the database.
addConstraints
This method sets the base constraints on the relation query.
addEagerConstraints
This method sets the constraints for an eager load of the relation.
matchOne
This method matches the eagerly loaded results to their single parents.
matchMany
This method matches the eagerly loaded results to their many parents.
getRelationValue
This method gets the value of a relationship by one or many type.
buildDictionary
This method builds a model dictionary keyed by the relation's foreign key.
findOrNew
This method finds a model by its primary key or returns a new instance of the related model.
firstOrNew
This method gets the first related model record matching the attributes or instantiate it.
firstOrCreate
This method gets the first record matching the attributes. If the record is not found, it creates it.
createOrFirst
This method attempts to create the record. If a unique constraint violation occurs, it tries to find the matching record.
updateOrCreate
This method creates or updates a related record matching the attributes, and fills it with values.
save
This method attaches a model instance to the parent model.
saveQuietly
This method attaches a model instance without raising any events to the parent model.
saveMany
This method attaches a collection of models to the parent instance.
saveManyQuietly
This method attaches a collection of models to the parent instance without raising any events to the parent model.
create
This method creates a new instance of the related model and saves it to the database.
createQuietly
This method creates a new instance of the related model without raising any events to the parent model.
forceCreate
This method creates a new instance of the related model with mass assignment, including the foreign key.
forceCreateQuietly
This method creates a new instance of the related model with mass assignment without raising any events to the parent model.
createMany
This method creates a collection of new instances of the related model.
createManyQuietly
This method creates a collection of new instances of the related model without raising any events to the parent model.
setForeignAttributesForCreate
This method sets the foreign ID for creating a related model.
getRelationExistenceQuery
This method adds the constraints for a relationship query.
getRelationExistenceQueryForSelfRelation
This method adds the constraints for a relationship query on the same table.
getExistenceCompareKey
This method gets the key for comparing against the parent key in a "has" query.
getParentKey
This method gets the key value of the parent's local key.
getQualifiedParentKeyName
This method gets the fully qualified parent key name.
getForeignKeyName
This method gets the plain foreign key.
getQualifiedForeignKeyName
This method gets the foreign key for the relationship.
getLocalKeyName
This method gets the local key for the relationship.
END
<?php
namespace Illuminate\Database\Eloquent\Relations;
use Illuminate\Database\Eloquent\Builder;
use Illuminate\Database\Eloquent\Collection;
use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\Concerns\InteractsWithDictionary;
use Illuminate\Database\UniqueConstraintViolationException;
abstract class HasOneOrMany extends Relation
{
use InteractsWithDictionary;
/**
* The foreign key of the parent model.
*
* @var string
*/
protected $foreignKey;
/**
* The local key of the parent model.
*
* @var string
*/
protected $localKey;
/**
* Create a new has one or many relationship instance.
*
* @param \Illuminate\Database\Eloquent\Builder $query
* @param \Illuminate\Database\Eloquent\Model $parent
* @param string $foreignKey
* @param string $localKey
* @return void
*/
public function __construct(Builder $query, Model $parent, $foreignKey, $localKey)
{
$this->localKey = $localKey;
$this->foreignKey = $foreignKey;
parent::__construct($query, $parent);
}
/**
* Create and return an un-saved instance of the related model.
*
* @param array $attributes
* @return \Illuminate\Database\Eloquent\Model
*/
public function make(array $attributes = [])
{
return tap($this->related->newInstance($attributes), function ($instance) {
$this->setForeignAttributesForCreate($instance);
});
}
/**
* Create and return an un-saved instance of the related models.
*
* @param iterable $records
* @return \Illuminate\Database\Eloquent\Collection
*/
public function makeMany($records)
{
$instances = $this->related->newCollection();
foreach ($records as $record) {
$instances->push($this->make($record));
}
return $instances;
}
/**
* Set the base constraints on the relation query.
*
* @return void
*/
public function addConstraints()
{
if (static::$constraints) {
$query = $this->getRelationQuery();
$query->where($this->foreignKey, '=', $this->getParentKey());
$query->whereNotNull($this->foreignKey);
}
}
/**
* Set the constraints for an eager load of the relation.
*
* @param array $models
* @return void
*/
public function addEagerConstraints(array $models)
{
$whereIn = $this->whereInMethod($this->parent, $this->localKey);
$this->whereInEager(
$whereIn,
$this->foreignKey,
$this->getKeys($models, $this->localKey),
$this->getRelationQuery()
);
}
/**
* Match the eagerly loaded results to their single parents.
*
* @param array $models
* @param \Illuminate\Database\Eloquent\Collection $results
* @param string $relation
* @return array
*/
public function matchOne(array $models, Collection $results, $relation)
{
return $this->matchOneOrMany($models, $results, $relation, 'one');
}
/**
* Match the eagerly loaded results to their many parents.
*
* @param array $models
* @param \Illuminate\Database\Eloquent\Collection $results
* @param string $relation
* @return array
*/
public function matchMany(array $models, Collection $results, $relation)
{
return $this->matchOneOrMany($models, $results, $relation, 'many');
}
/**
* Match the eagerly loaded results to their many parents.
*
* @param array $models
* @param \Illuminate\Database\Eloquent\Collection $results
* @param string $relation
* @param string $type
* @return array
*/
protected function matchOneOrMany(array $models, Collection $results, $relation, $type)
{
$dictionary = $this->buildDictionary($results);
// Once we have the dictionary we can simply spin through the parent models to
// link them up with their children using the keyed dictionary to make the
// matching very convenient and easy work. Then we'll just return them.
foreach ($models as $model) {
if (isset($dictionary[$key = $this->getDictionaryKey($model->getAttribute($this->localKey))])) {
$model->setRelation(
$relation, $this->getRelationValue($dictionary, $key, $type)
);
}
}
return $models;
}
/**
* Get the value of a relationship by one or many type.
*
* @param array $dictionary
* @param string $key
* @param string $type
* @return mixed
*/
protected function getRelationValue(array $dictionary, $key, $type)
{
$value = $dictionary[$key];
return $type === 'one' ? reset($value) : $this->related->newCollection($value);
}
/**
* Build model dictionary keyed by the relation's foreign key.
*
* @param \Illuminate\Database\Eloquent\Collection $results
* @return array
*/
protected function buildDictionary(Collection $results)
{
$foreign = $this->getForeignKeyName();
return $results->mapToDictionary(function ($result) use ($foreign) {
return [$this->getDictionaryKey($result->{$foreign}) => $result];
})->all();
}
/**
* Find a model by its primary key or return a new instance of the related model.
*
* @param mixed $id
* @param array $columns
* @return \Illuminate\Support\Collection|\Illuminate\Database\Eloquent\Model
*/
public function findOrNew($id, $columns = ['*'])
{
if (is_null($instance = $this->find($id, $columns))) {
$instance = $this->related->newInstance();
$this->setForeignAttributesForCreate($instance);
}
return $instance;
}
/**
* Get the first related model record matching the attributes or instantiate it.
*
* @param array $attributes
* @param array $values
* @return \Illuminate\Database\Eloquent\Model
*/
public function firstOrNew(array $attributes = [], array $values = [])
{
if (is_null($instance = $this->where($attributes)->first())) {
$instance = $this->related->newInstance(array_merge($attributes, $values));
$this->setForeignAttributesForCreate($instance);
}
return $instance;
}
/**
* Get the first record matching the attributes. If the record is not found, create it.
*
* @param array $attributes
* @param array $values
* @return \Illuminate\Database\Eloquent\Model
*/
public function firstOrCreate(array $attributes = [], array $values = [])
{
if (is_null($instance = (clone $this)->where($attributes)->first())) {
$instance = $this->createOrFirst($attributes, $values);
}
return $instance;
}
/**
* Attempt to create the record. If a unique constraint violation occurs, attempt to find the matching record.
*
* @param array $attributes
* @param array $values
* @return \Illuminate\Database\Eloquent\Model
*/
public function createOrFirst(array $attributes = [], array $values = [])
{
try {
return $this->getQuery()->withSavepointIfNeeded(fn () => $this->create(array_merge($attributes, $values)));
} catch (UniqueConstraintViolationException $e) {
return $this->useWritePdo()->where($attributes)->first() ?? throw $e;
}
}
/**
* Create or update a related record matching the attributes, and fill it with values.
*
* @param array $attributes
* @param array $values
* @return \Illuminate\Database\Eloquent\Model
*/
public function updateOrCreate(array $attributes, array $values = [])
{
return tap($this->firstOrCreate($attributes, $values), function ($instance) use ($values) {
if (! $instance->wasRecentlyCreated) {
$instance->fill($values)->save();
}
});
}
/**
* Attach a model instance to the parent model.
*
* @param \Illuminate\Database\Eloquent\Model $model
* @return \Illuminate\Database\Eloquent\Model|false
*/
public function save(Model $model)
{
$this->setForeignAttributesForCreate($model);
return $model->save() ? $model : false;
}
/**
* Attach a model instance without raising any events to the parent model.
*
* @param \Illuminate\Database\Eloquent\Model $model
* @return \Illuminate\Database\Eloquent\Model|false
*/
public function saveQuietly(Model $model)
{
return Model::withoutEvents(function () use ($model) {
return $this->save($model);
});
}
/**
* Attach a collection of models to the parent instance.
*
* @param iterable $models
* @return iterable
*/
public function saveMany($models)
{
foreach ($models as $model) {
$this->save($model);
}
return $models;
}
/**
* Attach a collection of models to the parent instance without raising any events to the parent model.
*
* @param iterable $models
* @return iterable
*/
public function saveManyQuietly($models)
{
return Model::withoutEvents(function () use ($models) {
return $this->saveMany($models);
});
}
/**
* Create a new instance of the related model.
*
* @param array $attributes
* @return \Illuminate\Database\Eloquent\Model
*/
public function create(array $attributes = [])
{
return tap($this->related->newInstance($attributes), function ($instance) {
$this->setForeignAttributesForCreate($instance);
$instance->save();
});
}
/**
* Create a new instance of the related model without raising any events to the parent model.
*
* @param array $attributes
* @return \Illuminate\Database\Eloquent\Model
*/
public function createQuietly(array $attributes = [])
{
return Model::withoutEvents(fn () => $this->create($attributes));
}
/**
* Create a new instance of the related model. Allow mass-assignment.
*
* @param array $attributes
* @return \Illuminate\Database\Eloquent\Model
*/
public function forceCreate(array $attributes = [])
{
$attributes[$this->getForeignKeyName()] = $this->getParentKey();
return $this->related->forceCreate($attributes);
}
/**
* Create a new instance of the related model with mass assignment without raising model events.
*
* @param array $attributes
* @return \Illuminate\Database\Eloquent\Model
*/
public function forceCreateQuietly(array $attributes = [])
{
return Model::withoutEvents(fn () => $this->forceCreate($attributes));
}
/**
* Create a Collection of new instances of the related model.
*
* @param iterable $records
* @return \Illuminate\Database\Eloquent\Collection
*/
public function createMany(iterable $records)
{
$instances = $this->related->newCollection();
foreach ($records as $record) {
$instances->push($this->create($record));
}
return $instances;
}
/**
* Create a Collection of new instances of the related model without raising any events to the parent model.
*
* @param iterable $records
* @return \Illuminate\Database\Eloquent\Collection
*/
public function createManyQuietly(iterable $records)
{
return Model::withoutEvents(fn () => $this->createMany($records));
}
/**
* Set the foreign ID for creating a related model.
*
* @param \Illuminate\Database\Eloquent\Model $model
* @return void
*/
protected function setForeignAttributesForCreate(Model $model)
{
$model->setAttribute($this->getForeignKeyName(), $this->getParentKey());
}
/**
* Add the constraints for a relationship query.
*
* @param \Illuminate\Database\Eloquent\Builder $query
* @param \Illuminate\Database\Eloquent\Builder $parentQuery
* @param array|mixed $columns
* @return \Illuminate\Database\Eloquent\Builder
*/
public function getRelationExistenceQuery(Builder $query, Builder $parentQuery, $columns = ['*'])
{
if ($query->getQuery()->from == $parentQuery->getQuery()->from) {
return $this->getRelationExistenceQueryForSelfRelation($query, $parentQuery, $columns);
}
return parent::getRelationExistenceQuery($query, $parentQuery, $columns);
}
/**
* Add the constraints for a relationship query on the same table.
*
* @param \Illuminate\Database\Eloquent\Builder $query
* @param \Illuminate\Database\Eloquent\Builder $parentQuery
* @param array|mixed $columns
* @return \Illuminate\Database\Eloquent\Builder
*/
public function getRelationExistenceQueryForSelfRelation(Builder $query, Builder $parentQuery, $columns = ['*'])
{
$query->from($query->getModel()->getTable().' as '.$hash = $this->getRelationCountHash());
$query->getModel()->setTable($hash);
return $query->select($columns)->whereColumn(
$this->getQualifiedParentKeyName(), '=', $hash.'.'.$this->getForeignKeyName()
);
}
/**
* Get the key for comparing against the parent key in "has" query.
*
* @return string
*/
public function getExistenceCompareKey()
{
return $this->getQualifiedForeignKeyName();
}
/**
* Get the key value of the parent's local key.
*
* @return mixed
*/
public function getParentKey()
{
return $this->parent->getAttribute($this->localKey);
}
/**
* Get the fully qualified parent key name.
*
* @return string
*/
public function getQualifiedParentKeyName()
{
return $this->parent->qualifyColumn($this->localKey);
}
/**
* Get the plain foreign key.
*
* @return string
*/
public function getForeignKeyName()
{
$segments = explode('.', $this->getQualifiedForeignKeyName());
return end($segments);
}
/**
* Get the foreign key for the relationship.
*
* @return string
*/
public function getQualifiedForeignKeyName()
{
return $this->foreignKey;
}
/**
* Get the local key for the relationship.
*
* @return string
*/
public function getLocalKeyName()
{
return $this->localKey;
}
}