How to Make Eloquent Relationship Attributes Truly Lazy in Spatie Laravel Data?

[faytecCD]

Let’s start by defining some classes:

use Illuminate\Database\Eloquent\Casts\Attribute;

class User extends \Illuminate\Database\Eloquent\Model {

    public array $fillable = ['name'];
    public function avatar() {
        return $this->hasOne(Attachment::class);
    }
    
    protected function avatarUrl(): Attribute {
        return Attribute::get(fn() => $this->loadMissing('avatar')->avatar?->url);
    }
}

class VUserData extends Spatie\LaravelData\Data
{
    public function __construct(
        public readonly int $id,
        public readonly string $name,
        public Spatie\LaravelData\Lazy|string|null $avatarUrl,
    ) {}
}

Now, the following code will silently auto-load the avatar relation:

$user = App\Models\User::firstOrFail();
$vud = VUserData::from($user);
dump($vud);

This happens because avatarUrl is not a real attribute—it’s computed from a model relation.

class VUserData extends Spatie\LaravelData\Data
{
    public function __construct(
        public readonly int $id,
        public readonly string $name,
        #[\Spatie\LaravelData\Attributes\AutoLazy]
        public Spatie\LaravelData\Lazy|string|null $avatarUrl,
    ) {}
}

Now, after adding the #[AutoLazy] attribute, avatarUrl becomes lazy as expected.
However, it still triggers an automatic relationship load, occurring in NormalizedModel::fetchNewProperty.

So, how can we make avatarUrl truly lazy (i.e., avoid querying the relation unless it’s actually accessed)?

I’ve thought of one solution: use a custom from method.

class VUserData extends Spatie\LaravelData\Data
{
    public function __construct(
        public readonly int $id,
        public readonly string $name,
        #[\Spatie\LaravelData\Attributes\AutoLazy]
        public Spatie\LaravelData\Lazy|string|null $avatarUrl,
    ) {}
    
    public static function fromUserModel(User $user): self
    {
        return new self(
            id: $user->id,
            name: $user->name,
            avatarUrl: Lazy::whenLoaded('avatar', $user, fn () => $user->avatar_url),
        );
    }
}

Amazing! It works exactly as expected.
But this raises another issue: good practice in database querying says we should only select the fields we need—never use wildcards.

So let’s modify the query:

// AppServiceProvider
Model::shouldBeStrict(app()->isLocal());

// ----

$user = App\Models\User::firstOrFail(['id']);
$vud = VUserData::from($user)->only('id', 'avatarUrl'); // We only need these two fields
dump($vud);

Now $user only has the id, yet it can still access the avatarUrl through the hasOne relation.
However, this code doesn’t behave well:

• In local mode, it throws an exception saying the name field doesn’t exist.
• In production, it doesn’t throw but name becomes null, which causes a type error since name is non-nullable.

So should we just make the field nullable? That would avoid the error, and since we used only, name won’t appear in the final output anyway.

---

I also came up with another approach:

<?php

declare(strict_types=1);

namespace App\Utils;

use Illuminate\Database\Eloquent\Model;
use Spatie\LaravelData\Lazy;

/**
 * @template TModel of Model
 *
 * @mixin TModel
 */
class ModelProxy
{
    public function __construct(
        private readonly Model $model,
    ) {}

    /**
     * @param model-property<TModel> $attribute
     *
     * @return \Spatie\LaravelData\Support\Lazy\ConditionalLazy
     */
    public function __get(string $attribute)
    {
        return $this->lazy($attribute);
    }

    /**
     * @param model-property<TModel> $attribute
     */
    public function getOr(string $attribute, mixed $default): mixed
    {
        return $this->model->hasAttribute($attribute) ? $this->model->getAttribute($attribute) : value($default);
    }
    
    public function optional(string $attribute) {
        return $this->getOr($attribute, new Optional);
    }
    
    public function lazy(string $attribute) {
        return Lazy::when(fn () => $this->model->hasAttribute($attribute), fn () => $this->model->getAttribute($attribute));
    }
}

Then:

class VUserData extends Spatie\LaravelData\Data
{
    public function __construct(
        public readonly Lazy|int $id,
        public readonly Lazy|string $name,
        #[\Spatie\LaravelData\Attributes\AutoLazy]
        public Spatie\LaravelData\Lazy|string|null $avatarUrl,
    ) {}
    
    public static function fromUserModel(User $user): self
    {
        /** @var ModelProxy<User> $proxy */
        $proxy = new ModelProxy($user);
        
        return new self(
            id: $proxy->id,
            name: $proxy->name,
            avatarUrl: Lazy::whenLoaded('avatar', $user, fn () => $user->avatarUrl),
        );
    }
}

This seems to reduce boilerplate nicely.

Or？

• A long list properties are repeated in fromModel #378

public static function fromModel(Member $user): static
{
   return static::from(array_merge(
          $user->toArray(),
         [
              'avatarUrl' => Lazy::whenLoaded('avatar', $user, fn () => $user->avatarUrl)
         ]
   ));
}

So—am I missing something here? Is there a better approach? Thanks.

---

Relation: #1071 #378