Best pattern to using one Data object for handling requests as well as responses

[denjaland]

Refactoring an existing codebase from using Laravel's FormRequest combined with JsonResponse to using this package's Data objects, I'm still struggling a lot finding the best way to do it, and I was wondering whether someone on here had some good pattern they use, trying to always ensure we have valid data.

Let's consider we have the following requirements.

In our RegisterUserController we are expecting UserData. The three fields that we require are email, first_name and last_name. Since we will send an email verification link, we do not need any more data at this point. So we started by building our Data model as follows:

class UserData extends Data 
{
  public function __construct(
    public string $email,
    public string $first_name,
    public string $last_name
  ) {
  }

  public static function rules() 
  {
    return [
      'email' => 'required|email|unique:users,email',
      'first_name' => 'required|min:1|max:50',
      'last_name' => 'required|min:1|max:50'
    ];
  }
}

So far so good: when using it in our controller to register our new user we can keep everything very tidy:

class RegisterUserController extends Controller
{
  public function __invoke(UserData $data, RegisterUserAction $action)
  {
    $user = $action($data);
  }
}

Our action returns a User model, so we now want to have our controller return the $user as a JsonResponse using our same UserData model. In our API, we have some rules on how we always structure our models, and basically we always want our models to have the following structure:

  {
    id: 'abcd-efgh',   // we use HashIds to not expose our internal integer ids to the outside world,
    meta: {
      created_at: '2022-12-26T09:38:06.000000Z',
      updated_at: '2022-12-26T09:38:06.000000Z',
      lock: 'azhgidhiuz',   // Each model has its lock we use to validate optimistic locking when we update models
      model: 'user', // The type of the model using laravel's morphMap
      tenant: 'xx' // Ownership information
    },
    // Other model attributes go here 
  }

Applying this to our UserData, we want to be able to return it as a JsonResponse and have the following payload:

  {
    id: 'abcd-efgh',   // we use HashIds to not expose our internal integer ids to the outside world,
    meta: {
      created_at: '2022-12-26T09:38:06.000000Z',
      updated_at: '2022-12-26T09:38:06.000000Z',
      lock: 'azhgidhiuz',   // Each model has its lock we use to validate optimistic locking when we update models
      model: 'user', // The type of the model using laravel's morphMap
      tenant: 'xx' // Ownership information
    },
    email: '[email protected]',
    first_name: 'Tarzan',
    last_name: 'Clayton'
  }

So it's clear we have to extend our UserData model. But since we want to still being able to use UserData for accepting an incomplete model when creating a new user, we need to make these new properties optional:

class UserData extends Data 
{
  public function __construct(
    public ?string $id,
    public ?ModelMetaData $meta,
    public string $email,
    public string $first_name,
    public string $last_name
  ) {
  }

  public static function rules() 
  {
    return [
      'email' => 'required|email|unique:users,email',
      'first_name' => 'required|min:1|max:50',
      'last_name' => 'required|min:1|max:50'
    ];
  }
}

As you can see, we introduced a new ModelMetaData allowing us to reuse the meta bit of any model in its own Data definition:

class ModelMetaData extends Data
{
  public function __construct(
    public Carbon $created_at,
    public Carbon $updated_at,
    public string $lock,
    public string $model,
    public TenantData $tenant
  ) {
  }
}

Okay. Last step, we need to add fromModel() method to our Data definitions allowing us to create the Data objects from our Model; we do it first on ModelMetaData:

class ModelMetaData extends Data
{
  public function __construct(
    public Carbon $created_at,
    public Carbon $updated_at,
    public string $lock,
    public string $model,
    public TenantData $tenant
  ) {
  }

  public static function fromModel(Model $model): self {
    return new self(
      created_at: $model->created_at,
      updated_at: $model->updated_at,
      lock: $model->original_lock,
      model: $model->getMorphClass(),
      tenant: Lazy::when(fn() => $model->isTenantAware(), fn() => $model->tenant) 
    );
  }
}

And of course we need to support fromModel on our actual UserData as well:

class UserData extends Data 
{
  public function __construct(
    public ?string $id,
    public ?ModelMetaData $meta,
    public string $email,
    public string $first_name,
    public string $last_name
  ) {
  }

  public static function rules() 
  {
    return [
      'email' => 'required|email|unique:users,email',
      'first_name' => 'required|min:1|max:50',
      'last_name' => 'required|min:1|max:50'
    ];
  }

  public static function fromModel(User $user): self {
    return new self(
      id: $model->hash_id,
      meta: ModelMetaData::fromModel($user),
      email: $model->email,
      first_name: $model->first_name,
      last_name: $model->last_name,
    );
  }
}

Okay great, so I can now use the UserData to also return it from my Controller:

class RegisterUserController extends Controller
{
  public function __invoke(UserData $data, RegisterUserAction $action): UserData
  {
    return UserData::fromModel($action($data));
  }
}

Now I'm not entirely happy with this yet, as for UserData returned from the controller, I'm not really validating that all the attributes that we set in the fromModel method are correct. $id and $meta are set only optionally here.

I know that this is supposed to be used by backend code only, so we should basically be able to trust it, and we'll cover it in our testing too, but I'm still struggling a bit with this. How do others do this? Do I have to live with this? Or is there a nice pattern that I could apply to ensure my data is always validated?

I realise I'm probably overthinking this, as we didn't validate the JsonResponses either when we were using them. But we just want to make the most of using this beautiful package from the start. Maybe I'm missing the obvious here. My main concern is living with the optional attributes.

Thanks!

[Slund]

You could exclude the optional fields from UserData and instead create an additional data object which extends UserData with the additional fields which are only present after persisting.

[denjaland]

The only drawback that I see is that you need to maintain more Data objects.
We now have RegisterUserData and UserData.

RegisterUserData only expects email, first name and last name. UserData maps the entire Usermodel, so our controllers look really neat like this:

class RegisterUserController extends Controller
{
  public function __invoke(RegisterUserData $data, RegisterUserAction $action): UserData
  {
    return UserData::fromModel($action($data));
  }
}

Request data is validated by the RegisterUserData object, but we return a completely mapped model using UserDatainstead.

Now imagine that we want to add a new attribute to our User model that needs to be provided by the user upon registering (e.g. the preferred communication locale), then we would have to remember to update both UserData as well as RegisterUserData which is in fact something we wanted to avoid by refactoring from our Illuminate FormRequests and JsonResource classes to these data objects.

Again: I think we'll just stick to it though, as it brings some clarity still, and as you say: after all, these Data objects have different contexts, and maybe shouldn't be forced into one Data object after all.

[Slund]

If you inherit (note I also wrote 'extend' initially) from RegisterUserData in UserData, then you would only have to add it in one place. I know inheritance might be a no-go for some, but here it would handle the concern.

[denjaland]

It also introduces another issue.

If you have inheritance, and you don't want to override the constructor on the UserData, it means you still need to add the attributes on CreateUserData (although optional), meaning it would still accept it from the request, so I could still set them, even though I might not be allowed to.

No: I think we'll stick to seperate Data objects so that we can keep our controllers and action classes clean (I now know that by expecting a RegisterUserData object, I'm only getting these fields that I want, so I can just do User::create($data->all());, knowing the data has been validated, and does not have fields that I do not expect.

[Slund]

Yea sure, it wouldn't make sense to use inheritance if you don't want to extend and call the parent constructor.
Totally fair you do opt for separate objects. I am curious though, as to what you see as the issue with overriding the base/parent constructor?

[denjaland]

If you override, you have to maintain the two Data objects nevertheless: add the new locale attribute on RegisterUserData, and also on UserData. So the inheritance doesn't solve the fact that I need to maintain it in both Data classes then.

[patrickomeara]

Sorry to dig up an old thread, but the issues mentioned in this discussion are very close to the initial pains I'm having moving from FormRequest and JsonResource

As mentioned in the original post, I also provide a unique id to hide the internal auto incrementing ids, initially I had this as optional public ?string $guid but this meant I had to exclude it when creating and updating which felt dirty.

When using Unique in the validation attributes with RouteParameterReference an exception was thrown as a list page doesn't have this parameter.

With the above two issues, it was clear I needed to have separate Data objects for Requests and Resources, which I refactored to.

I tried to use the Request Data object for both create and update, but now I have hit an issue where the update needs to ignore the route param, and create doesn't have a route param. Do we split the Data objects as well?

Should we have CreateModelData, UpdateModelData, and ModelData classes? and if so, should there be any inheritance? It seems pointless to use inheritance when the constructors are the main difference, but listing all the static function attributes() in a create and update Data class seems verbose.

Perhaps it's better to leave the complex (non-primitive) validation rules to the rules() method.

What are the best practices when implementing Laravel Data into a big code base? Are there any Open Source examples that we should follow?

I've read Laravel Beyond CRUD, and re-read after version 2 was released, but it only gives an intro to Laravel Data. The example repo attached to that course uses the now-deprecated DTO package.

Any guidance here would be much appreciated, as I'm keen to implement this powerful package, I just need to workout the tradeoffs before a huge refactor.

Thanks.