Let’s dive right into an example!

class Money{
    public function __construct(
        public readonly string $amount,
        public readonly string $currency
    ){}

    public function equals(Money $money): bool {
        return $this->amount === $money->amount &&
                $this->currency === $money->currency;
    }
}

$tenDollar = new Money(10, 'USD');
$tenRupee = new Money(10, 'INR');

$tenDollar->equals($tenRupee); // false

As you can see value objects are just simple simple classes with a function that computes equality. Here we can specify our custom logic to compare entities.

Other bonus advantages of Value Objects:

• Can be used as DTOs to pass data around different services.

• Reliable data due to readonly properties of the class which means the data cannot be changed.

Hope this post makes it easier to understand Value Objects in PHP. I’ve kept it brief on purpose to not overcomplicate things.

If you have any questions, I will be happy to answer them in the comments.

class IpApi{
    public function getLocation(): array{
        // Make an API call
        // Sample api Response from https://ip-api.com
        return [
            'countryCode' => 'US',
            'country' => 'United States',
            'city' => 'New York'
        ];
    }
}

Now we have the API setup to fetch the user’s location via their IP address. Let’s now fetch news articles in user’s location.

use App\Models\News;

class NewsService{
    public function getNewsNearby(protected array $location){
        return News::where('country', $location['country'])->where('city', $location['city'])->get();
    }
}

// Get the location
$locationApi = new IpApi;
$location = $locationApi->getLocation();

// Fetch the news articles
$newsService = new NewsService;
$news = $newsService->getNewsNearby($location);

We should get the news articles in the user’s city. Everything works as expected.

Though what will happen if we change the API service in the future? Lets use https://ipgeolocation.io as an example.

class IpGeolocationApi{
    public function getLocation(): array{
        // Make an API call
        // Sample api Response from https://ipgeolocation.io
        return [
            'country_code2' => 'US',
            'country_code3' => 'USA',
            'country_name' => 'United States',
            'city' => 'New York'
        ];
    }
}

As you can see, the API response from https://ipgeolocation.io is a bit different and hence our previous code to fetch news will fail.

// This will now throw an error

use App\Models\News;

class NewsService{
    public function getNewsNearby(protected array $location){
        return News::where('country', $location['country'])->where('city', $location['city'])->get();
    }
}

One simple solution is to change $location['country'] to $location['country_name'] and the code should work. But we will have the same issue whenever we change the API in the future. Also it might not be feasible to change the code if we are using it multiple places.

Enter DTOs

What if we can have our own data structure independent of APIs? Using DTOs, we can simply create a PHP class to hold user’s location.

class LocationDTO{
    public function __construct(public readonly string $country, public readonly string $city){
    }
}

Now we can use this class instead of raw API responses in array. We can also type hint fields like $country and $city so we always have the correct data format.

Additionally, readonly properties ensures that the property values cannot be changed once initialized. This solidifies that we will always have unaltered and accurate data. Readonly properties are supported in PHP 8.1 and later.

Now lets refactor our code a bit and implement DTOs. We need to do couple of things:

1. Replace array with a DTO in api response when fetching location.

2. Replace array with a DTO when using location data in our application, like when fetching news articles.

// Replace array with a DTO
class IpApi{
    public function getLocation(): LocationDTO{
        // Make an API call
        // Sample api Response from https://ip-api.com
        $location = [
            'countryCode' => 'US',
            'country' => 'United States',
            'city' => 'New York'
        ];

        return new LocationDTO($location['country'], $location['city']);
    }
}

class IpGeolocationApi{
    public function getLocation(): LocationDTO{
        // Make an API call
        // Sample api Response from https://ipgeolocation.io
        $location = [
            'country_code2' => 'US',
            'country_code3' => 'USA',
            'country_name' => 'United States',
            'city' => 'New York'
        ];

        return new LocationDTO($location['country_name'], $location['city']);
    }
}

Now we can return a DTO from the API response instead of an array. Let’s use it in our application to fetch news articles nearby to the user.

use App\Models\News;

class NewsService{
    public function getNewsNearby(protected LocationDTO $location){
        return News::where('country', $location->country)->where('city', $location->city)->get();
    }
}

// Get the location
$locationApi = new IpApi;
$location  = $locationApi->getLocation();

// Fetch the news articles
$newsService = new NewsService;
$news = $newsService->getNewsNearby($location);

Now if we change our API in the future, we just have to switch our API class and the data format will remain the same.

// Get the location using https://ipgeolocation.io
$locationApi = new IpGelocationApi;
$location  = $locationApi->getLocation();

// Fetch the news articles
$newsService = new NewsService;
$news = $newsService->getNewsNearby($location);

Note that we didn’t had to change our logic to fetch news from the database as it uses DTO which does not change. Similarly wherever we use DTO in our codebase, we won’t have to make a change which makes maintenance easier.

Bonus: Use Interface

In modern frameworks like Laravel, you can bind an interface to the concrete class. So instead of manuallly initializing an API like new IpApi, we can use an interface.

interface LocationInterface{
    public function getLocation(): LocationDTO;
}

$this->app->bind(LocationInterface::class, IpApi::class);

Now you can fetch location in your code without using the IpApi class.

class NewsController{
    public function index(LocationInterface $location){
        $newsService = new NewsService;
        $news = $newsService->getNewsNearby($location);
    }
}

The benefit of this approach is you can change the API service in future with only one line of change.

//Use IpGelocationApi instead of IpApi
$this->app->bind(LocationInterface::class, IpGelocationApi::class);

Our controller will remain exactly as it is and it does not care which API service you are using.

This approach also satisfies 2 SOLID principles - Liskov Substitution Principle and Dependency Inversion Principle.

Hope this makes it easier to understand DTOs in PHP and how useful it can be. If you have any questions, I will be happy to answer them in the comments.

• Duplicate Queries: Repeating the same database query in multiple places, which makes it tricky to update them in the future as you will have to hunt them down every time you want to make a change.

• Caching: Maintaining caches and invalidating them can be difficult if your database queries are scattered throughout the codebase.

Lately in my projects, I have been using a technique.

The Solution

Turns out the solution is to quite simply refactor your queries into simple PHP classes and store them in a dedicated folder. I use App\Stores, but you can use App\Data or whatever makes the most sense to you.

namespace App\Stores;

use Illuminate\Database\Eloquent\Builder;
use App\Models\Movie;

class TopRatedMovies
{
    public function query(): Builder
    {
        return Movie::orderByDesc('rating');
    }
}

Now you can use database queries anywhere in your code.

class TopRatedMoviesController extends Controller
{
    public function index(TopRatedMovies $topRatedMovies)
    {
        $movies = $topRatedMovies->get();
        ...
    }
}

Refactoring into a package

I refactored this solution into a package to use across different projects. It contains additional features like caching & custom data types.

Check out the “Laravel Store“ package on GitHub.

Caching

Every store has its own methods to manage cache.

(new TopRatedMovies)->getCachedData();
(new TopRatedMovies)->cache();
(new TopRatedMovies)->clearCache();

Custom Data Types

You might have some data in your application that is in a different format, like an array, and does not return a database query. In those cases, you can use a CustomStore where you can return data in your own format rather than being dependent on Laravel model and query builder.

use Mayank\Store\CustomStore;

class Languages extends CustomStore
{
    public function data(): array
    {
        return ['English', 'Spanish', 'French'];
    }
}

CLI

If you manage your data via the command line or via Task Scheduling, Laravel Store provides cache specific commands:

php artisan store:cache TopRatedMovies

Flexibility

As we are simply using PHP classes, you have infinite flexibility to add more features to your database queries. Perhaps you need a method to get a slightly different version of the data exclusively for the apps? Or maybe you want to do some processing to the data? You can add as many methods as you need in your store class.

Feedback

I hope this was useful to you. I would love to hear any feedback and know more about how you organize database queries in your application.