[11.x] Add CollectedBy attribute

[alsterholm]

This pull request adds a new CollectedBy attribute for specifying a custom Collection class for a model.

With this attribute added, one would only have to add the attribute rather than override the newCollection method on the Model class (or taking the undocumented route and setting the $collectionClass static property).

#[CollectedBy(PostCollection::class)]
class Post
{
    // ...
}

This also brings the approach closer in line with the new ObservedBy and ScopedBy attributes.

[taylorotwell]

May be worth memoizing the resolution from the attribute? Otherwise it's a lot of reflection operations each time this method is called.

[alsterholm]

May be worth memoizing the resolution from the attribute? Otherwise it's a lot of reflection operations each time this method is called.

Very good point! I've updated the PR and wrapped the logic in the resolveCollectionAttribute method in a once call.

[johanrosenson]

instead of once() this could also work, IMO easier to debug and troubleshoot.

static::$resolvedCollectionClass ??= $this->resolveCollectionAttribute() ?? static::$collectionClass;

return new static::$collectionClass($models);

required addition to Model.php

protected static $resolvedCollectionClass = null;

[taylorotwell]

I believe once may not be the best answer here because it is scoped to a particular object instance, whereas you probably want a truly static variable like @johanrosenson mentions.

[johanrosenson]

this should probably match the typehint in Database\Eloquent\Model#L228

@param class-string<\Illuminate\Database\Eloquent\Collection<*, *>> $collectionClass

[alsterholm]

@johanrosenson @taylorotwell But using a static variable like that wouldn't work as the resolved value would be shared across all models:

abstract class Model
{
    public static $resolvedCollectionClass = null;
}

class A extends Model
{
    public function resolveCollectionClass()
    {
        static::$resolvedCollectionClass = CustomCollection::class;
    }
}

class B extends Model {}

(new A)->resolveCollectionClass();

var_dump(B::$resolvedCollectionClass); // string(16) "CustomCollection"

I suppose an array in a static variable used as a lookup table, where the key is the model class name, could work?

[alsterholm]

I'm not entirely sure about this type. If a phpstan wizard would like to have a look at this, that would be awesome ☺️

[browner12]

Is this better than overriding the newCollection method, or just different?

[shaedrich]

@browner12 From a DX standpoint, it is primarily different; from a semantic standpoint, from a semantic(?) it gravitates more towards being declarative while newCollection() would be more imperative

[alsterholm]

@taylorotwell Do you want me to submit a PR to the docs documenting the attribute?

[shaedrich]

@alsterholm fyi, you might be interested in this: #53126