{"record":{"id":"c49077abbd0a8f2c","repo":"laravel/framework","slug":"the-provided-class-must-extend-illuminate-support","errorCode":null,"errorMessage":"The provided class must extend [Illuminate\\Support\\Collection].","messagePattern":"The provided class must extend \\[Illuminate\\\\Support\\\\Collection\\]\\.","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"src/Illuminate/Database/Eloquent/Casts/AsCollection.php","lineNumber":41,"sourceCode":"        return new class($arguments) implements CastsAttributes\n        {\n            public function __construct(protected array $arguments)\n            {\n                $this->arguments = array_pad(array_values($this->arguments), 2, '');\n            }\n\n            public function get($model, $key, $value, $attributes)\n            {\n                if (! isset($attributes[$key])) {\n                    return;\n                }\n\n                $data = Json::decode($attributes[$key]);\n\n                $collectionClass = empty($this->arguments[0]) ? Collection::class : $this->arguments[0];\n\n                if (! is_a($collectionClass, Collection::class, true)) {\n                    throw new InvalidArgumentException('The provided class must extend ['.Collection::class.'].');\n                }\n\n                if (! is_array($data)) {\n                    return null;\n                }\n\n                $instance = new $collectionClass($data);\n\n                if (! isset($this->arguments[1]) || ! $this->arguments[1]) {\n                    return $instance;\n                }\n\n                if (is_string($this->arguments[1])) {\n                    $this->arguments[1] = Str::parseCallback($this->arguments[1]);\n                }\n\n                return is_callable($this->arguments[1])\n                    ? $instance->map($this->arguments[1])","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/laravel/framework/blob/e0f6eb3518ac29fbbca8529e97d0df7fc9f24481/src/Illuminate/Database/Eloquent/Casts/AsCollection.php#L23-L59","documentation":"Thrown by the AsCollection cast when the first argument (the custom collection class name) does not extend Illuminate\\Support\\Collection. The cast uses is_a() with allow_string=true to verify the class is a subclass before instantiating it; any class that is not a Collection descendant fails this check. This protects the cast from producing an object that lacks the Collection API the rest of Eloquent expects.","triggerScenarios":"Declaring a cast as AsCollection::class . ':' . SomeClass::class where SomeClass does not extend Illuminate\\Support\\Collection (e.g. a plain data object, a DTO, or a generic iterator). Also triggered by passing a fully-qualified class string that is misspelled or points to a non-Collection class. Reading the cast attribute (the get() method) runs the is_a() check.","commonSituations":"Using a custom collection class that was renamed or moved between Laravel versions; referencing a class whose namespace changed after an upgrade; passing an enum or interface name instead of a concrete Collection subclass; copy-pasting a cast from another project whose collection class does not exist here.","solutions":["Verify the class passed as the first argument extends Illuminate\\Support\\Collection (use is_subclass_of($class, \\Illuminate\\Support\\Collection::class)).","Add the correct `use` import for the collection class and confirm the fully-qualified name in the cast definition.","If you only need a base collection, drop the custom class argument and use AsCollection::class alone.","If you need a custom class, make it `class MyCollection extends \\Illuminate\\Support\\Collection`."],"exampleFix":"// before\nprotected $casts = [\n    'items' => AsCollection::class . ':' . App\\Support\\ItemBag::class, // ItemBag does not extend Collection\n];\n\n// after\nclass ItemBag extends \\Illuminate\\Support\\Collection {}\n\nprotected $casts = [\n    'items' => AsCollection::class . ':' . App\\Support\\ItemBag::class,\n];","handlingStrategy":"validation","validationCode":"use Illuminate\\Support\\Collection;\n\n$collectionClass = App\\Support\\MyCollection::class; // candidate\nif (! is_subclass_of($collectionClass, Collection::class)) {\n    throw new \\LogicException(\"{$collectionClass} must extend \\\\Illuminate\\\\Support\\\\Collection\");\n}\n// safe to reference in cast string: AsCollection::class . ':' . $collectionClass","typeGuard":"function isValidCollectionClass(string $class): bool\n{\n    return class_exists($class) && is_subclass_of($class, \\Illuminate\\Support\\Collection::class);\n}","tryCatchPattern":null,"preventionTips":["Always define custom collection classes as `extends \\Illuminate\\Support\\Collection`.","Use the ::class constant (not a literal string) to avoid typos in the cast definition.","Add a unit test asserting is_subclass_of($class, Collection::class) for every custom collection referenced in casts."],"tags":["eloquent","cast","collection","configuration"],"backgroundTag":null,"analyzedSha":"e0f6eb3518ac29fbbca8529e97d0df7fc9f24481","analyzedAt":"2026-08-11T20:52:37.562Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}