[8.x] Add firstOr() function to BelongsToMany relation

[r-kujawa]

What does this PR do?

• It adds the firstOr() function to the BelongsToMany::class relationship.
• Adds tests to support this addition ☝🏼.

Why do we need this?

Before this PR

The 'firstOr()' function was being executed via the __call() method of the BelongsToMany::class which forwarded the call to the Eloquent\Builder::class. When the firstOr() function found a first() record it returned the relationship instance, but didn't add the necessary select columns ($this->shouldSelect($columns)) to the query builder object.

SELECT * 
FROM `posts` 
INNER JOIN `users_posts` ON `posts`.`uuid` = `users_posts`.`post_uuid` 
WHERE `users_posts`.`user_uuid` = ? 
ORDER BY RAND() 
LIMIT 1;

With this PR

By adding the firstOr() function to the BelongsToMany::class itself, the get() that executes the select query statement is now the one that lives in the BelongsToMany::class and defines the columns that should be selected.

SELECT `posts`.*, `users_posts`.`user_uuid` AS `pivot_user_uuid`, `users_posts`.`post_uuid` AS `pivot_post_uuid`, `users_posts`.`is_draft` AS `pivot_is_draft`, `users_posts`.`created_at` AS `pivot_created_at`, `users_posts`.`updated_at` AS `pivot_updated_at` 
FROM `posts` 
INNER JOIN `users_posts` ON `posts`.`uuid` = `users_posts`.`post_uuid` 
WHERE `users_posts`.`user_uuid` = ? 
ORDER BY RAND() 
LIMIT 1;

Thanks to the get() function being executed directly on the BelongsToMany::class's relation, it adds the select columns, and prevents the Post::class's model from inheriting the wrong id and/or any other pivot table (users_posts) column with the same name as any of the columns in the posts table.

[driesvints]

Please send this to 9.x

[r-kujawa]

Please send this to 9.x

I could do that, but won't 8.x be receiving bug fixes anymore?

[driesvints]

@r-kujawa this is a new feature, not a bug fix?

[r-kujawa]

@driesvints I believe it is a bug fix, because if you call the firstOr() method on a belongsToMany() relation it will not return exactly what is expected if the pivot table has a column of the same name as the requested relations column.

e.g. If the users_posts table has an id column (or timestamps() columns) when retrieving the first() record of the database, the model retrieved will inherit the values from the pivot table columns instead of the actual models value. You may reference the test I wrote in this PR to validate this.

$post = $user->posts()->firstOr(function () {
    // return default post...
});

If the pivot table in the above query has an id of 101, but the first() post being retrieved has an id of 49, it will return the actual post, but the id will be 101 instead of the expected 49. This is because of the INNER JOIN statement without specifying the columns to be selected from the query.

[r-kujawa]

Here is a reference from somebody else experiencing this issue, hope it helps.

[driesvints]

@r-kujawa you're correct! Sorry about that.

[r-kujawa]

@r-kujawa you're correct! Sorry about that.

No worries, always happy to help 😄

[taylorotwell]

This was actually already on 9.x back in September.