Skip to content

Clean phpdoc and arg names for relation traits #2587

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Aug 31, 2023
Merged

Clean phpdoc and arg names for relation traits #2587

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 10 additions & 10 deletions src/Eloquent/EmbedsRelations.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,11 +14,11 @@ trait EmbedsRelations
/**
* Define an embedded one-to-many relationship.
*
* @param string $related
* @param string $localKey
* @param string $foreignKey
* @param string $relation
* @return \MongoDB\Laravel\Relations\EmbedsMany
* @param class-string $related
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

TIL: https://psalm.dev/docs/annotating_code/type_syntax/scalar_types/#class-string-interface-string

* @param string|null $localKey
* @param string|null $foreignKey
* @param string|null $relation
* @return EmbedsMany
*/
protected function embedsMany($related, $localKey = null, $foreignKey = null, $relation = null)
{
Expand Down Expand Up @@ -47,11 +47,11 @@ protected function embedsMany($related, $localKey = null, $foreignKey = null, $r
/**
* Define an embedded one-to-many relationship.
*
* @param string $related
* @param string $localKey
* @param string $foreignKey
* @param string $relation
* @return \MongoDB\Laravel\Relations\EmbedsOne
* @param class-string $related
* @param string|null $localKey
* @param string|null $foreignKey
* @param string|null $relation
* @return EmbedsOne
*/
protected function embedsOne($related, $localKey = null, $foreignKey = null, $relation = null)
{
Expand Down
110 changes: 63 additions & 47 deletions src/Eloquent/HybridRelations.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,10 @@

namespace MongoDB\Laravel\Eloquent;

use Illuminate\Database\Eloquent\Concerns\HasRelationships;
use Illuminate\Database\Eloquent\Relations\MorphOne;
use Illuminate\Support\Str;
use MongoDB\Laravel\Eloquent\Model as MongoDBModel;
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Was this necessary? We're not referencing another Model class in this file and I don't recall seeing an alias used elsewhere (in previous PRs).

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

My idea was that it's more explicit that we need a MongoDB Model and not the Eloquent Base Model.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Got it. No argument if this was done for readability 👍

use MongoDB\Laravel\Helpers\EloquentBuilder;
use MongoDB\Laravel\Relations\BelongsTo;
use MongoDB\Laravel\Relations\BelongsToMany;
Expand All @@ -21,15 +23,17 @@ trait HybridRelations
/**
* Define a one-to-one relationship.
*
* @param string $related
* @param string $foreignKey
* @param string $localKey
* @param class-string $related
* @param string|null $foreignKey
* @param string|null $localKey
* @return \Illuminate\Database\Eloquent\Relations\HasOne
*
* @see HasRelationships::hasOne()
*/
public function hasOne($related, $foreignKey = null, $localKey = null)
{
// Check if it is a relation with an original model.
if (! is_subclass_of($related, \MongoDB\Laravel\Eloquent\Model::class)) {
if (! is_subclass_of($related, MongoDBModel::class)) {
return parent::hasOne($related, $foreignKey, $localKey);
}

Expand All @@ -45,17 +49,19 @@ public function hasOne($related, $foreignKey = null, $localKey = null)
/**
* Define a polymorphic one-to-one relationship.
*
* @param string $related
* @param class-string $related
* @param string $name
* @param string $type
* @param string $id
* @param string $localKey
* @param string|null $type
* @param string|null $id
* @param string|null $localKey
* @return \Illuminate\Database\Eloquent\Relations\MorphOne
*
* @see HasRelationships::morphOne()
*/
public function morphOne($related, $name, $type = null, $id = null, $localKey = null)
{
// Check if it is a relation with an original model.
if (! is_subclass_of($related, \MongoDB\Laravel\Eloquent\Model::class)) {
if (! is_subclass_of($related, MongoDBModel::class)) {
return parent::morphOne($related, $name, $type, $id, $localKey);
}

Expand All @@ -71,15 +77,17 @@ public function morphOne($related, $name, $type = null, $id = null, $localKey =
/**
* Define a one-to-many relationship.
*
* @param string $related
* @param string $foreignKey
* @param string $localKey
* @param class-string $related
* @param string|null $foreignKey
* @param string|null $localKey
* @return \Illuminate\Database\Eloquent\Relations\HasMany
*
* @see HasRelationships::hasMany()
*/
public function hasMany($related, $foreignKey = null, $localKey = null)
{
// Check if it is a relation with an original model.
if (! is_subclass_of($related, \MongoDB\Laravel\Eloquent\Model::class)) {
if (! is_subclass_of($related, MongoDBModel::class)) {
return parent::hasMany($related, $foreignKey, $localKey);
}

Expand All @@ -95,17 +103,19 @@ public function hasMany($related, $foreignKey = null, $localKey = null)
/**
* Define a polymorphic one-to-many relationship.
*
* @param string $related
* @param class-string $related
* @param string $name
* @param string $type
* @param string $id
* @param string $localKey
* @param string|null $type
* @param string|null $id
* @param string|null $localKey
* @return \Illuminate\Database\Eloquent\Relations\MorphMany
*
* @see HasRelationships::morphMany()
*/
public function morphMany($related, $name, $type = null, $id = null, $localKey = null)
{
// Check if it is a relation with an original model.
if (! is_subclass_of($related, \MongoDB\Laravel\Eloquent\Model::class)) {
if (! is_subclass_of($related, MongoDBModel::class)) {
return parent::morphMany($related, $name, $type, $id, $localKey);
}

Expand All @@ -126,13 +136,15 @@ public function morphMany($related, $name, $type = null, $id = null, $localKey =
/**
* Define an inverse one-to-one or many relationship.
*
* @param string $related
* @param string $foreignKey
* @param string $otherKey
* @param string $relation
* @param class-string $related
* @param string|null $foreignKey
* @param string|null $ownerKey
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is the variable change here done for consistency with a base Laravel class/trait?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes and for correctness.

* @param string|null $relation
* @return \Illuminate\Database\Eloquent\Relations\BelongsTo
*
* @see HasRelationships::belongsTo()
*/
public function belongsTo($related, $foreignKey = null, $otherKey = null, $relation = null)
public function belongsTo($related, $foreignKey = null, $ownerKey = null, $relation = null)
{
// If no relation name was given, we will use this debug backtrace to extract
// the calling method's name and use that as the relationship name as most
Expand All @@ -142,8 +154,8 @@ public function belongsTo($related, $foreignKey = null, $otherKey = null, $relat
}

// Check if it is a relation with an original model.
if (! is_subclass_of($related, \MongoDB\Laravel\Eloquent\Model::class)) {
return parent::belongsTo($related, $foreignKey, $otherKey, $relation);
if (! is_subclass_of($related, MongoDBModel::class)) {
return parent::belongsTo($related, $foreignKey, $ownerKey, $relation);
}

// If no foreign key was supplied, we can use a backtrace to guess the proper
Expand All @@ -160,19 +172,21 @@ public function belongsTo($related, $foreignKey = null, $otherKey = null, $relat
// actually be responsible for retrieving and hydrating every relations.
$query = $instance->newQuery();

$otherKey = $otherKey ?: $instance->getKeyName();
$ownerKey = $ownerKey ?: $instance->getKeyName();

return new BelongsTo($query, $this, $foreignKey, $otherKey, $relation);
return new BelongsTo($query, $this, $foreignKey, $ownerKey, $relation);
}

/**
* Define a polymorphic, inverse one-to-one or many relationship.
*
* @param string $name
* @param string $type
* @param string $id
* @param string $ownerKey
* @param string|null $type
* @param string|null $id
* @param string|null $ownerKey
* @return \Illuminate\Database\Eloquent\Relations\MorphTo
*
* @see HasRelationships::morphTo()
*/
public function morphTo($name = null, $type = null, $id = null, $ownerKey = null)
{
Expand Down Expand Up @@ -211,20 +225,22 @@ public function morphTo($name = null, $type = null, $id = null, $ownerKey = null
/**
* Define a many-to-many relationship.
*
* @param string $related
* @param string $collection
* @param string $foreignKey
* @param string $otherKey
* @param string $parentKey
* @param string $relatedKey
* @param string $relation
* @param class-string $related
* @param string|null $collection
* @param string|null $foreignPivotKey
* @param string|null $relatedPivotKey
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

$relatedPivotKey sounds much more descriptive than $otherKey. 👍

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That was the first motivation. I didn't understand the meaning of all this parameters.

* @param string|null $parentKey
* @param string|null $relatedKey
* @param string|null $relation
* @return \Illuminate\Database\Eloquent\Relations\BelongsToMany
*
* @see HasRelationships::belongsToMany()
*/
public function belongsToMany(
$related,
$collection = null,
$foreignKey = null,
$otherKey = null,
$foreignPivotKey = null,
$relatedPivotKey = null,
$parentKey = null,
$relatedKey = null,
$relation = null
Expand All @@ -237,12 +253,12 @@ public function belongsToMany(
}

// Check if it is a relation with an original model.
if (! is_subclass_of($related, \MongoDB\Laravel\Eloquent\Model::class)) {
if (! is_subclass_of($related, MongoDBModel::class)) {
return parent::belongsToMany(
$related,
$collection,
$foreignKey,
$otherKey,
$foreignPivotKey,
$relatedPivotKey,
$parentKey,
$relatedKey,
$relation
Expand All @@ -252,11 +268,11 @@ public function belongsToMany(
// First, we'll need to determine the foreign key and "other key" for the
// relationship. Once we have determined the keys we'll make the query
// instances as well as the relationship instances we need for this.
$foreignKey = $foreignKey ?: $this->getForeignKey().'s';
$foreignPivotKey = $foreignPivotKey ?: $this->getForeignKey().'s';

$instance = new $related;

$otherKey = $otherKey ?: $instance->getForeignKey().'s';
$relatedPivotKey = $relatedPivotKey ?: $instance->getForeignKey().'s';

// If no table name was provided, we can guess it by concatenating the two
// models using underscores in alphabetical order. The two model names
Expand All @@ -274,8 +290,8 @@ public function belongsToMany(
$query,
$this,
$collection,
$foreignKey,
$otherKey,
$foreignPivotKey,
$relatedPivotKey,
$parentKey ?: $this->getKeyName(),
$relatedKey ?: $instance->getKeyName(),
$relation
Expand All @@ -301,7 +317,7 @@ protected function guessBelongsToManyRelation()
*/
public function newEloquentBuilder($query)
{
if (is_subclass_of($this, \MongoDB\Laravel\Eloquent\Model::class)) {
if ($this instanceof MongoDBModel) {
return new Builder($query);
}

Expand Down
4 changes: 2 additions & 2 deletions src/Relations/EmbedsMany.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -277,10 +277,10 @@ protected function associateExisting($model)
}

/**
* @param null $perPage
* @param int|null $perPage
* @param array $columns
* @param string $pageName
* @param null $page
* @param int|null $page
* @return \Illuminate\Contracts\Pagination\LengthAwarePaginator
*/
public function paginate($perPage = null, $columns = ['*'], $pageName = 'page', $page = null)
Expand Down
2 changes: 1 addition & 1 deletion src/Relations/EmbedsOneOrMany.php
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ abstract class EmbedsOneOrMany extends Relation
* @param string $foreignKey
* @param string $relation
*/
public function __construct(Builder $query, Model $parent, Model $related, $localKey, $foreignKey, $relation)
public function __construct(Builder $query, Model $parent, Model $related, string $localKey, string $foreignKey, string $relation)
{
$this->query = $query;
$this->parent = $parent;
Expand Down