Sandulat

Announcing Kitwind

Sun, 17 May 2020 00:00:00 GMT

I’m very excited to announce, that we’re halfway of releasing our brand-new project - Kitwind, which will include 200+ fully responsive, multi-purpose sections, built with Tailwind CSS, to help you bootstrap your next website.

Kitwind isn’t only about quantity. We’re carefully crafting all the sections, one by one, paying attention to small details, accessibility, clean code, beautiful interactions, and most importantly, designing charming and unique sections.

During the years, we’ve noticed that a lot of UI kits and website builders are giving birth to websites with a very similar look and feel. Keeping that in mind, one of our goals is to ship a diversified collection of sections, which can be combined in various, creative ways.

We are sure that Kitwind will give you all the necessary ingredients to prepare the secret sauce, which will give your websites a special vibe.

All sections and components will come in pure HTML, VueJS, and React, so that you’ll have more time to focus on building products, rather than writing code.

The pricing model is fairly simple. Pay once - get life-time access to all the sections and upcoming updates. Use the sections on unlimited commercial projects.

We have not yet established the price, but we’re aiming to make the product affordable for everyone and set a fair price, under $99. Also, we will be providing big discounts to support you during the pandemic.

If it sounds interesting to you, follow us on Twitter (@kitwindio), and visit the official Kitwind website (https://kitwind.io), to subscribe and get notified when Kitwind gets released.

We are looking forward to seeing all the cool things that you will build!

Dedicated, autocompleted and typed Eloquent query builders

Sat, 04 Apr 2020 00:00:00 GMT

Before we start, this article was heavily inspired by Tim MacDonald’s article “Dedicated query builders for Eloquent models”. You should definitely check it out.

Wouldn’t it be cool if Laravel’s query builder had autocomplete? Even on deep relationship queries? We can achieve this with dedicated query builders.

Our first dedicated query builder

Let’s define a new UserBuilder, which will extend Eloquent’s base query builder:

<?php

declare(strict_types=1);

namespace App\Builders;

use Illuminate\Database\Eloquent\Builder;

final class UserBuilder extends Builder
{
    public function whereName(string $name): self
    {
        return $this->where('name', $name);
    }
}

Notice how we’ve defined a custom whereName method? All the methods that we’re defining in our custom query builder will be basically simple wrappers around Eloquent’s query builder methods.

Linking our custom query builder with the model

Eloquent models have a newEloquentBuilder method under the hood, which by default returns the base query builder. We can link our custom query builder with the desired model by overriding this method:

<?php

declare(strict_types=1);

namespace App;

use App\Builders\UserBuilder;
use Illuminate\Foundation\Auth\User as Authenticatable;

final class User extends Authenticatable
{
    public function newEloquentBuilder($query): UserBuilder
    {
        return new UserBuilder($query);
    }
}

Great! Now we can use the whole thing like this:

User::whereName('Alex')->first();

But unfortunately, our IDE will not provide autocomplete, since it can’t recognize our custom query builder just by overriding the newEloquentBuilder method.

To get autocomplete working, we’ll have to type hint the return type of the query method, available in Eloquent models.

<?php

declare(strict_types=1);

namespace App;

use App\Builders\UserBuilder;
use Illuminate\Foundation\Auth\User as Authenticatable;

final class User extends Authenticatable
{
    /**
     * @return \App\Builders\UserBuilder|\Illuminate\Database\Eloquent\Builder
     */
    public static function query()
    {
        return parent::query();
    }

    public function newEloquentBuilder($query): UserBuilder
    {
        return new UserBuilder($query);
    }
}

Now, to get static analysis working, we’ll have to start all our queries with the query method:

User::query()->whereName('Alex')->first();

Static analysis on relationship queries

Let’s define a new Article model:

<?php

declare(strict_types=1);

namespace App;

use App\Builders\ArticleBuilder;
use Illuminate\Database\Eloquent\Model;

final class Article extends Model
{
    /**
     * @return \App\Builders\ArticleBuilder|\Illuminate\Database\Eloquent\Builder
     */
    public static function query()
    {
        return parent::query();
    }

    public function newEloquentBuilder($query): ArticleBuilder
    {
        return new ArticleBuilder($query);
    }
}

And a new ArticleBuilder for our Article model:

<?php

declare(strict_types=1);

namespace App\Builders;

use Illuminate\Database\Eloquent\Builder;

final class ArticleBuilder extends Builder
{
    public function wherePublished(bool $published): self
    {
        return $this->where('published', $published);
    }
}

Let’s assume that our User model has many articles, so let’s define a HasMany relationship:

<?php

declare(strict_types=1);

namespace App;

use App\Builders\UserBuilder;
use Illuminate\Foundation\Auth\User as Authenticatable;
use Illuminate\Database\Eloquent\Relations\HasMany;

final class User extends Authenticatable
{
    /**
     * @return \App\Builders\UserBuilder|\Illuminate\Database\Eloquent\Builder
     */
    public static function query()
    {
        return parent::query();
    }

    public function newEloquentBuilder($query): UserBuilder
    {
        return new UserBuilder($query);
    }

    public function articles(): HasMany
    {
        return $this->hasMany(Article::class);
    }
}

Now, by building a query from an user’s articles relationship, we won’t get any autocomplete, since the articles relationship method returns an Illuminate\Database\Eloquent\Relations\HasMany instance:

User::articles()->??????->first();

To solve this, we can also type hint the return type of the articles relationship method:

/**
  * @return \App\Builders\ArticleBuilder|\Illuminate\Database\Eloquent\Relations\HasMany
  */
public function articles()
{
    return $this->hasMany(Article::class);
}

And we’ve solved the problem:

User::articles()->wherePublished(true)->first();

Static analysis on “whereHas” queries

What if we want to retrieve all the users, which have published articles only? Normally we’d do it like this:

User::whereHas('articles', function ($query) {
    $query->where('published', true);
})->get();

However, since we are moving away from the classic query building, we’re going to define a whereHasArticles method on our UserBuilder:

public function whereHasArticles(\Closure $callback = null): self
{
    return $this->whereHas('articles', $callback);
}

Which will be used like this:

User::query()
  ->whereHasArticles(fn(ArticleBuilder $query) => $query->wherePublished(true))
  ->get();

Static analysis on “with” queries

To retrieve all the users with their published articles only, this is what we’d normally do:

User::with([
    'articles' => function ($query) {
        $query->where('published', true);
    },
])->get();

But, we’ll define a custom withArticles method in our UserBuilder:

Keep in mind that the with query closures will inject instances of relationships, like HasMany in our case. Fortunately, relationship instances provide a getQuery method, which will return our dedicated query builder.

public function withArticles(\Closure $callback = null): self
{
    return $this->with([
        'articles' => fn(HasMany $query) => $callback ?
            $callback($query->getQuery()) :
            $query,
    ]);
}

The method can be used like this:

User::query()
  ->withArticles(fn(ArticleBuilder $query) => $query->wherePublished(true))
  ->get();

Caveat: multi-where scopes

Read about this caveat on Tim MacDonald’s article “Dedicated query builders for Eloquent models”.

Wrapping up

I’ve showed how you can type hint your with / whereHas closures, but it can also be applied to basically all types of queries, like whereHasMorph, and so on.

I do really enjoy this approach, since I’m always trying to get static analysis working everywhere and I believe that this approach is the only one available out there to get it working with Eloquent and to eliminate the magic. It’s extremely helpful once your team grows or projects get larger, at least in my humble opinion.

Thanks for reading this post! Subscribe below and get notified when new posts will be released. Also, let me know on Twitter (@sandulat) what do you think about this approach.

Casting JSON columns to DTOs with Laravel's custom casts

Tue, 10 Mar 2020 00:00:00 GMT

Since custom casts have finally arrived with Laravel 7, we can take full advantage of this new feature to get full autocomplete and type checking of JSON columns.

To achieve this, we can use data-transfer-object by Spatie, since native DTOs aren’t supported in PHP (I’d recommend taking a look at it first, before reading this post). It can be installed by running:

composer require spatie/data-transfer-object

Default JSON columns casting

Having the following migration:

final class CreateUsersTable extends Migration
{
    public function up()
    {
        Schema::create('users', function (Blueprint $table) {
            $table->json('address')->nullable();
        });
    }
}

This is how we can define the deserialization method for the address column in our User model:

final class User extends Authenticatable
{
    protected $casts = [
        'address' => 'array',
    ];
}

However, our IDE can’t tell us what’s inside $user->address. In addition, there is no validation while saving something into the address column.

Custom JSON to DTO cast

Custom casts are just classes that implement the CastsAttributes interface, which requires us to define the get and set methods.

Having the following user address DTO:

<?php

namespace App\Dto;

use Spatie\DataTransferObject\DataTransferObject;

final class UserAddress extends DataTransferObject
{
    public string $city;

    public string $street;
}

This is how our address cast would look like:

<?php

namespace App\Casts;

use App\Dto\UserAddress;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;

final class UserAddressCast implements CastsAttributes
{
    /**
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @param  string  $key
     * @param  mixed  $value
     * @param  array  $attributes
     * @return UserAddress|null
     */
    public function get($model, $key, $value, $attributes): ?UserAddress
    {
        if (! $value) {
            return null;
        }

        return new UserAddress(json_decode($value, true));
    }

    /**
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @param  string  $key
     * @param  mixed  $value
     * @param  array  $attributes
     * @return string
     * @throws \Exception
     */
    public function set($model, $key, $value, $attributes): string
    {
        if (! $value instanceof UserAddress) {
            throw new \Exception("The provided value must be an instance of ".UserAddress::class);
        }

        return json_encode($value->toArray());
    }
}

Basically inside the get method, we are decoding the JSON column and return a freshly initialized UserAddress DTO. However, if the column is null (it might be nullable in our database), we’re returning null.

Inside the set method, we’re just checking if we’ve received an instance of UserAddress and serialize the DTO back to JSON using the toArray method, provided by DataTransferObject, which is the parent of UserAddress.

All that’s left is to change array to UserAddressCast::class in our user model:

final class User extends Authenticatable
{
    protected $casts = [
        'address' => UserAddressCast::class,
    ];
}

And now this is how we would fill user’s address:

// If address is null initially:
$user->address = new UserAddress([
    'city' => 'Cool City',
    'street' => 'Nice Street',
]);

// If address is already filled:
$user->address->city = 'Another Cool City';

$user->address->street = 'Another Nice City';

Same goes in factories:

$factory->define(User::class, function (Faker $faker) {
    return [
        'address' => new UserAddress([
          'city' => 'Cool City',
          'street' => 'Nice Street',
        ]),
    ];
});

Automating JSON to DTO casting

Wouldn’t it be a pain if we’ve had to define such long casting classes for each DTO? Well, we can define an abstract DTO cast which will be extended in the future:

<?php

namespace App\Casts;

use Illuminate\Contracts\Database\Eloquent\CastsAttributes;
use Spatie\DataTransferObject\DataTransferObject;

abstract class DTOCast implements CastsAttributes
{
    /**
     * @return string
     */
    abstract protected function dtoClass(): string;

    /**
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @param  string  $key
     * @param  mixed  $value
     * @param  array  $attributes
     * @return DataTransferObject|null
     */
    public function get($model, $key, $value, $attributes): ?DataTransferObject
    {
        if (!$value) {
            return null;
        }

        $dtoClass = $this->dtoClass();

        return (new $dtoClass)(json_decode($value, true));
    }

    /**
     * @param  \Illuminate\Database\Eloquent\Model  $model
     * @param  string  $key
     * @param  mixed  $value
     * @param  array  $attributes
     * @return string
     * @throws \Exception
     */
    public function set($model, $key, $value, $attributes): string
    {
        $dtoClass = $this->dtoClass();

        if (!$value instanceof $dtoClass) {
            throw new \Exception("The provided value must be an instance of ".$dtoClass);
        }

        return json_encode($value->toArray());
    }
}

The get and set methods have the exact same logic as in the UserAddressCast example above. However, notice that we’ve defined an abstract method dtoClass which must return a DTO class name.

Now our UserAddressCast becomes this:

<?php

namespace App\Casts;

use App\Dto\UserAddress;

final class UserAddressCast extends DTOCast
{
    protected function dtoClass(): string
    {
        return UserAddress::class;
    }
}

Getting autocomplete to work

The only way I know to get proper autocompletion in Laravel, is by using the awesome Laravel IDE Helper by Barry vd. Heuvel. It can be installed by running:

composer require --dev barryvdh/laravel-ide-helper

Now automatic phpDocs for models can be generated by running this in your project:

php artisan ide-helper:models

laravel-ide-helper will mark the address column as an UserAddressCast type, which in reality must be an UserAddress type, but fortunately, this package provides a configurable option for casting types overriding.

Publish the config by running:

php artisan vendor:publish --provider="Barryvdh\LaravelIdeHelper\IdeHelperServiceProvider" --tag=config

It will publish the config to config/ide-helper.php.

Now, we can override the casting class with our real DTO class, using the type_overrides option inside the published config:

'type_overrides' => [
    '\\'.UserAddressCast::class => '\\'.UserAddress::class,
],

After updating the config, regenerate the phpDocs and that’s it!

Keep in mind that I don’t recommend storing the “address” as a JSON column. This minimalistic example is just for demonstration purposes.

Thanks for reading this post! Subscribe below and get notified when new posts will be released or follow me on Twitter (@sandulat).

Safely persisting Vuex store in local storage

Tue, 03 Mar 2020 00:00:00 GMT

If you’re building a Vue front-end app, you’re most probably using Vuex as your centralized store. Usually stores are being persisted in the local storage, since cookies have a max size of 4KB, so local storage is one of your only real alternative options. However, the majority of developers store data in local storage, in its raw version (pure JSON). Local storage isn’t secure as a concept, so if you’re persisting any of user’s data there, you should encrypt it.

Vuex Persist

For persisting my Vuex store, I’m usually using the plugin vuex-persist, which can be installed by running:

npm install --save vuex-persist

# or

yarn add vuex-persist

The usage is straightforward:

import Vuex from 'vuex';
import VuexPersistence from 'vuex-persist';

const vuexLocal = new VuexPersistence({
  storage: window.localStorage,
});

const store = new Vuex.Store({
  plugins: [vuexLocal.plugin],
});

And thats it. Now your store is persisted inside browser’s local storage.

Vuex Persist Getters & Setters

The storage key passed to VuexPersistence constructor doesn’t have to necessarily be window.localStorage. It must be an object implementing the methods getItem, setItem, removeItem. In fact, the prototype of window.localStorage implements these methods and that’s why you can pass it directly.

new VuexPersistence({
  storage: {
    // Get the store (for e.g. from local storage)
    getItem: () => {},
    // Set the store (for e.g. in local storage)
    setItem: (key, value) => {},
    // Remove the store (for e.g. from local storage)
    removeItem: () => {},
  },
});

Encrypting Vuex Persisted Store

My personal approach for persisting the store securely:

Generate a random UUID and store it in a secure cookie.
Encrypt the store in the setItem setter, using the generated UUID.
Decrypt the store in the getItem getter, using the generated UUID.
Clear the store if the decryption fails in the getter.

For encryption we can use crypto-js, which can be installed by running:

npm install --save crypto-js

# or

yarn add crypto-js

For cookies we can use js-cookie, which can be installed by running:

npm install --save js-cookie

# or

yarn add js-cookie

For UUID generation we can use uuid, which can be installed by running:

npm install --save uuid

# or

yarn add uuid

And this is how the entire thing would look:

import VuexPersistence from 'vuex-persist';
import Crypto from 'crypto-js';
import Cookie from 'js-cookie';
import uuid from 'uuid';

const cookieName = 'cookieName';

const storageKey = 'storageKey';

// Get the encryption token from cookie or generate a new one.
const encryptionToken = Cookie.get(cookieName) || uuid.v4();

// Store the encryption token in a secure cookie.
Cookie.set(cookieName, encryptionToken, { secure: true, expires: 180 });

const vuexLocal = new VuexPersistence({
  storage: {
    getItem: () => {
      // Get the store from local storage.
      const store = window.localStorage.getItem(storageKey);

      if (store) {
        try {
          // Decrypt the store retrieved from local storage
          // using our encryption token stored in cookies.
          const bytes = Crypto.AES.decrypt(store, encryptionToken);

          return JSON.parse(bytes.toString(Crypto.enc.Utf8));
        } catch (e) {
          // The store will be reset if decryption fails.
          window.localStorage.removeItem(storageKey);
        }
      }

      return null;
    },
    setItem: (key, value) => {
      // Encrypt the store using our encryption token stored in cookies.
      const store = Crypto.AES.encrypt(value, encryptionToken).toString();

      // Save the encrypted store in local storage.
      return window.localStorage.setItem(storageKey, store);
    },
    removeItem: () => window.localStorage.removeItem(storageKey),
  },
});

export default vuexLocal.plugin;

Keep in mind that all the encryption logic is still exposed to the client. However, it’s still much better than keeping the raw store persisted in local storage.

Hey, thanks for reading this post! Subscribe below and get notified when new posts will be released or follow me on Twitter (@sandulat).

Mapping requests to DTOs inside Laravel's form requests

Mon, 02 Mar 2020 00:00:00 GMT

Laravel’s form requests are custom request classes that contain validation logic. To use them, you just have to type-hint the form request on your controller method and the incoming request will be automatically validated.

Form request example:

<?php

namespace App\Http\Requests;

use Illuminate\Foundation\Http\FormRequest;

final class StoreBlogPost extends FormRequest
{
    public function rules()
    {
        return [
            'title' => [
                'required',
            ],
            'body' => [
                'required',
            ],
        ];
    }
}

Form request usage inside controller methods:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use App\Http\Requests\StoreBlogPost;

final class BlogPostsController extends Controller
{
    public function store(StoreBlogPost $request)
    {
        // The incoming request is valid...
    }
}

The problem is that in our controller method, the IDE can’t tell us what data is inside the $request variable.

To solve this problem, we can use DTOs. Since native DTOs aren’t supported in PHP, we can use data-transfer-object by Spatie (I’d recommend taking a look at it first, before reading this post), which can be installed by running:

composer require spatie/data-transfer-object

Our first request DTO

Here’s how the DTO for our StoreBlogPost request would look:

<?php

declare(strict_types=1);

namespace App\DataTransferObjects;

use Illuminate\Http\Request;
use Spatie\DataTransferObject\DataTransferObject;

final class BlogPostRequestData extends DataTransferObject
{
    public string $title;

    public string $body;

    public static function fromRequest(Request $request): BlogPostRequestData
    {
        return new static([
            'title' => $request->input('title'),
            'body' => $request->input('body'),
        ]);
    }
}

Notice that we’ve declared a static constructor fromRequest, where we’ve defined how the request maps to the DTO.

Now inside our controller method, we can instantiate the DTO from the incoming request:

<?php

declare(strict_types=1);

namespace App\Http\Controllers;

use App\Http\Requests\StoreBlogPost;
use App\DataTransferObjects\BlogPostRequestData;

final class BlogPostsController extends Controller
{
    public function store(StoreBlogPost $request)
    {
        $requestData = BlogPostRequestData::fromRequest($request);
    }
}

Our IDE now knows that $requestData contains title and body.

Instantiating the DTO inside form requests

Since form requests are simple classes, we can define helper methods right inside them, for further usage inside our controller methods.

The static constructor fromRequest from BlogPostRequestData, can be moved to the form request, so we won’t have to import and instantiate DTOs in our controllers.

The formRequest method can be removed from our DTO:

<?php

declare(strict_types=1);

namespace App\DataTransferObjects;

use Spatie\DataTransferObject\DataTransferObject;

final class BlogPostRequestData extends DataTransferObject
{
    public string $title;

    public string $body;
}

And here is how our form request will look now:

<?php

namespace App\Http\Requests;

use App\DataTransferObjects\BlogPostRequestData;
use Illuminate\Foundation\Http\FormRequest;

final class StoreBlogPost extends FormRequest
{
    public function rules()
    {
        return [
            'title' => [
                'required',
            ],
            'body' => [
                'required',
            ],
        ];
    }

    public function data()
    {
        return new BlogPostRequestData([
            'title' => $this->input('title'),
            'body' => $this->input('body'),
        ]);
    }
}

This way, we can keep our controllers clean and retrieve the mapped request using the data method, defined in our form request:

public function store(StoreBlogPost $request)
{
    $request->data()->title;
}

Thank you very much for reading this post! Subscribe below and get notified when new posts will be released or follow me on Twitter (@sandulat).

Testing Laravel Vapor file uploads

Thu, 27 Feb 2020 00:00:00 GMT

Testing classic file uploads, that are submitted directly to the server, in Laravel is extremely simple, as you can see in the example below:

<?php

namespace Tests\Feature;

use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Storage;
use Tests\TestCase;

class ExampleTest extends TestCase
{
    public function testFileUpload()
    {
        Storage::fake();

        $response = $this->json('POST', '/avatar', [
            'file' => UploadedFile::fake()->image('photo.jpg'),
        ]);

        Storage::assertExists('photo.jpg');
    }
}

However if you’re are running your Laravel app on Vapor, you might know that files are never sent directly to your backend. Instead, users upload files directly to S3, into a tmp folder (which is configured to purge any files older than 24 hours) and just send the S3 file path to your backend for further processing.

After receiving the S3 file path in your API, you can move the file out of the tmp directory:

use Illuminate\Support\Facades\Storage;

Storage::copy(
    $request->input('key'),
    str_replace('tmp/', '', $request->input('key'))
);

Simulating S3 Direct Uploads in Tests

Since we have no S3 in our tests, we can place the files directly on our local system by using \Illuminate\Support\Facades\Storage::putFile() which in a testing environment will store files in storage/framework/testing/disks/local. This folder is also automatically purged each time you run your tests.

<?php

namespace Tests\Feature;

use Illuminate\Foundation\Testing\RefreshDatabase;
use Illuminate\Http\UploadedFile;
use Illuminate\Support\Facades\Storage;
use Tests\TestCase;

class ExampleTest extends TestCase
{
    public function testFileUpload()
    {
        Storage::fake();

        $file = UploadedFile::fake()->image('photo.jpg');

        $filePath = Storage::putFile('tmp', $file);

        $response = $this->json('POST', '/avatar', [
            'key' => $filePath,
        ]);

        Storage::assertMissing($filePath);

        Storage::assertExists($file->hashName());
    }
}

As you can see, we’ve stored the file in a local tmp folder and sent its path to the API (just like we would store it on S3). Finally, we can test that the file was moved out of the tmp folder.

Thank you for reading this post! Subscribe below and get notified when new posts will be released or follow me on Twitter (@sandulat).

Validating Laravel Vapor file uploads

Thu, 27 Feb 2020 00:00:00 GMT

In Laravel apps running on Vapor, users upload files directly to S3, after which the stored file path is sent to our API. Before moving out the files from the tmp folder, we have to make sure that:

The path represents the tmp folder.
The file exists.
It doesn’t exceed the size limit.
It has a valid mime type.

Such validations with classic file uploads, which are sent directly to our API, can be easily done with default Laravel rules like mimes and size. However, since we are receiving an S3 path now, we’ll have to define a reusable validation rule:

<?php

declare(strict_types=1);

namespace App\Rules;

use Illuminate\Contracts\Validation\Rule;
use Illuminate\Support\Facades\Storage;
use Illuminate\Support\Str;

final class StorageFile implements Rule
{
    public int $maxSize;

    /** @var string[] */
    public array $mimes;

    /**
     * @param int $maxSize
     * @param string[] $mimes
     */
    public function __construct(int $maxSize, array $mimes)
    {
        $this->maxSize = $maxSize;

        $this->mimes = $mimes;
    }

    /**
     * @param string $attribute
     * @param mixed $value
     * @return bool
     */
    public function passes($attribute, $value): bool
    {
        if (! Str::startsWith($value, 'tmp/')) {
            return false;
        }

        if (! Storage::exists($value)) {
            return false;
        }

        if (Storage::size($value) > $this->maxSize) {
            return false;
        }

        return in_array(Storage::mimeType($value), $this->mimes);
    }

    public function message(): string
    {
        return 'Invalid file.';
    }
}

In this example, the StorageFile rule receives the allowed max file size and mime types.

Rule Usage

This is a basic Laravel rule, so it can be used as any other rule in your validators:

Validator::make($request->all(), [
  'key' => [
    'required',
    new StorageFile(5120, ['image/jpg', 'image/jpeg', 'image/png'])
  ],
]);

Or alternatively in FormRequest:

<?php

declare(strict_types=1);

namespace App\Http\Requests;

use App\Rules\StorageFile;
use Illuminate\Foundation\Http\FormRequest;
use Illuminate\Validation\Rule;

final class FileUploadRequest extends FormRequest
{
    public function rules(): array
    {
        return [
            'key' => [
                'required',
                new StorageFile(5120, ['image/jpg', 'image/jpeg', 'image/png']),
            ],
        ];
    }
}

Thank you for reading this post! Subscribe below and get notified when new posts will be released or follow me on Twitter (@sandulat).

Moving from Laravel API resources to DTOs

Wed, 26 Feb 2020 00:00:00 GMT

Laravel’s API resources are a transformation layer that sits between your Eloquent models and the JSON responses returned by your API. This approach is completely fine, however the use case of these resources is quite limited to API responses only, they aren’t type hinted and lack autocompletion.

API resources can be replaced with DTOs. Since native DTOs aren’t supported in PHP, we can use data-transfer-object by Spatie (I’d recommend taking a look at it first, before reading this post), which can be installed by running:

composer require spatie/data-transfer-object

Our First Data Transfer Object

<?php

declare(strict_types=1);

namespace App\DataTransferObjects;

use App\Models\User;
use Spatie\DataTransferObject\DataTransferObject;

final class UserData extends DataTransferObject
{
    public int $id;

    public string $name;

    public string $email;

    public static function fromModel(User $user): UserData
    {
        return new static([
            'id' => $user->id,
            'name' => $user->name,
            'email' => $user->email,
        ]);
    }
}

Notice that we’ve defined a static constructor fromModel, which receives a type hinted User model. This way we have maximum flexibility to construct the DTO, inject relationships and so on.

Now we can instantiate UserData:

$user = User::first();

UserData::fromModel($user);

Returning the DTO as a Response

Unfortunately, UserData can’t be returned by API endpoints, since Laravel doesn’t know how to serialize it.

To achieve this, we can implement the Illuminate\Contracts\Support\Responsable interface. It would be nice to have whole thing reusable, so we can define ResponseData, which will implement the Responsable interface and wrap other DTOs.

Keep in mind, that we still want to wrap our DTOs in a data key, just like Laravel’s resources do.

<?php

declare(strict_types=1);

namespace App\DataTransferObjects;

use Illuminate\Contracts\Support\Responsable;
use Spatie\DataTransferObject\DataTransferObject;

final class ResponseData extends DataTransferObject implements Responsable
{
    public int $status = 200;

    /** @var \Spatie\DataTransferObject\DataTransferObject|\Spatie\DataTransferObject\DataTransferObjectCollection */
    public $data;

    /**
     * @param \Illuminate\Http\Request $request
     * @return \Illuminate\Http\JsonResponse|\Symfony\Component\HttpFoundation\Response
     */
    public function toResponse($request)
    {
        return response()->json(
            [
                'data' => $this->data->toArray(),
            ],
            $this->status
        );
    }
}

We’ve defined 2 attributes:

status - response status (default 200).
data - payload, which can be either a DataTransferObject or DataTransferObjectCollection.

Since we’ve implemented the Responsable interface, we have to define the toResponse method, where we can return a JSON response.

Notice the $this->data->toArray() part? Both DataTransferObject and DataTransferObjectCollection expose the toArray method.

Now inside controller methods, we can return the DTO as a response like that:

$user = User::first();

return new ResponseData([
    'data' => UserData::fromModel($user),
]);

And we’ll get:

{
  "data": {
    "id": 1,
    "name": "John",
    "email": "john@example.org"
  }
}

Returning Paginated Collection Responses

The same way we’ve defined ResponseData, we can define ResponsePaginationData:

<?php

declare(strict_types=1);

namespace App\DataTransferObjects;

use Illuminate\Contracts\Pagination\LengthAwarePaginator;
use Illuminate\Contracts\Support\Responsable;
use Spatie\DataTransferObject\DataTransferObject;
use Spatie\DataTransferObject\DataTransferObjectCollection;

final class ResponsePaginationData extends DataTransferObject implements Responsable
{
    public LengthAwarePaginator $paginator;

    public DataTransferObjectCollection $collection;

    public int $status = 200;

    /**
     * @param \Illuminate\Http\Request $request
     * @return \Illuminate\Http\JsonResponse|\Symfony\Component\HttpFoundation\Response
     */
    public function toResponse($request)
    {
        return response()->json(
            [
                'data' => $this->collection->toArray(),
                'meta' => [
                    'currentPage' => $this->paginator->currentPage(),
                    'lastPage' => $this->paginator->lastPage(),
                    'path' => $this->paginator->path(),
                    'perPage' => $this->paginator->perPage(),
                    'total' => $this->paginator->total(),
                ],
            ],
            $this->status
        );
    }
}

Here, we’ve defined 3 attributes:

status - response status (default 200).
paginator - Laravel’s paginator.
collection - our collection.

Usage in controller methods:

$users = User::paginate(30);

return new ResponsePaginationData([
    'paginator' => $users,
    'collection' => new UserCollection($users->items()),
]);

Output:

{
  "data": [
    {
      "id": 1,
      "name": "John",
      "email": "john@example.org"
    },
    {
      "id": 2,
      "name": "Mike",
      "email": "mike@example.org"
    }
  ],
  "meta": {
    "currentPage": 1,
    "lastPage": 1,
    "path": "http://localhost/api/users",
    "perPage": 30,
    "total": 2
  }
}

However, if you’ve decided to instantiate your DTOs with static constructors, like the fromModel example above, you won’t be able to instantiate your collections with the default constructor. Instead, we need to define a static constructor in collections as well:

<?php

declare(strict_types=1);

namespace App\DataTransferObjects;

use App\Models\User;
use Spatie\DataTransferObject\DataTransferObjectCollection;

final class UserCollection extends DataTransferObjectCollection
{
    public function current(): UserData
    {
        return parent::current();
    }

    /**
     * @param  User[]  $data
     * @return UserCollection
     */
    public static function fromArray(array $data): UserCollection
    {
        return new static(
            array_map(fn(User $item) => UserData::fromModel($item), $data)
        );
    }
}

So here’s how the controller method will look in the end:

$users = User::paginate(30);

return new ResponsePaginationData([
    'paginator' => $users,
    'collection' => UserCollection::fromArray($users->items()),
]);

Hey, thank you for reading this post entirely! Hopefully it was helpful for you. If you’ve enjoyed this post, subscribe below and get notified when new articles will be released.