DEV Community: Benjamin Delespierre

Haking with Laravel modules

Benjamin Delespierre — Tue, 21 Sep 2021 21:43:31 +0000

As a project grows it becomes advantageous to break down its monolythical app/ folder into smaller chunks called modules. You know, to keep things structured and stuff 😜

A typical approach is to replicate the Laravel folder structure in many folders. For Example

modules/
    billing/
        app/ database/ routes/
    shop/
        app/ database/ routes/
    blog/
        app/ database/ routes/

But there's a small problem. The make:something commands that we love 😍 and rely on every day for our spectacular productivity won't work with this structure 🙁

Well, fear not, my friend! Today, I'm going to show you how you can fix that problem and make make:* commands play nicely with a modular folder structure!

And we're going to tackle that in just 5 minutes of copying & pasting code around ⚡⚡⚡ Ready?

A new option for all Artisan commands

We want to be able to do something like this:

php artisan make:model --module billing --all Invoice

But we don't want to rewrite all the *MakeCommand classes. So we're going to inject 💉 this snippet directly inside the artisan file:

require __DIR__.'/vendor/autoload.php';

$app = require_once __DIR__.'/bootstrap/app.php'; // <--- be sure to paste AFTER this line

/*
|--------------------------------------------------------------------------
| Detect The Module Context
|--------------------------------------------------------------------------
|
| If you wish to run a given command (usually a make:something) in the
| context of a module, you may pass --module <name> as arguments. The
| following snippet will swap the base directory with the module directory
| and erase the module arguments so the command can run normally.
|
*/

if ((false !== $offset = array_search('--module', $argv)) && !empty($argv[$offset + 1])) {
    $modulePath = $app->basePath("modules/{$argv[$offset + 1]}");

    $app->useAppPath("{$modulePath}/app");
    $app->useDatabasePath("{$modulePath}/database");

    unset($argv[$offset], $argv[$offset + 1]);
}

We also need to make a small change at line 56:

$status = $kernel->handle(
    $input = new Symfony\Component\Console\Input\ArgvInput($argv), // <---- add ($argv) here!
    new Symfony\Component\Console\Output\ConsoleOutput
);

Introducing a new service provider

Laravel is somewhat made to handle modules and packages, but we need to tell it how to discover them. For that, we're going to need a service provider:

php artisan make:provider ModuleServiceProvider

Fill it with:

namespace App\Providers;

use Illuminate\Database\Eloquent\Factories\Factory;
use Illuminate\Support\ServiceProvider;
use Illuminate\Support\Str;

class ModuleServiceProvider extends ServiceProvider
{
    /**
     * Register services.
     *
     * @return void
     */
    public function register()
    {
        /** Fixing Factory::resolveFactoryName */
        Factory::guessFactoryNamesUsing(function (string $modelName) {
            $namespace = Str::contains($modelName, "Models\\")
                ? Str::before($modelName, "App\\Models\\")
                : Str::before($modelName, "App\\");

            $modelName = Str::contains($modelName, "Models\\")
                ? Str::after($modelName, "App\\Models\\")
                : Str::after($modelName, "App\\");

            return $namespace . "Database\\Factories\\" . $modelName . "Factory";
        });
    }

    /**
     * Bootstrap services.
     *
     * @return void
     */
    public function boot()
    {
        foreach (glob(base_path('modules/*')) ?: [] as $dir) {
            $this->loadMigrationsFrom("{$dir}/database/migrations");
            $this->loadTranslationsFrom("{$dir}/resources/lang", basename($dir));
            $this->loadViewsFrom("{$dir}/resources/views", basename($dir));
        }
    }
}

/*
 * Application Service Providers...
 */
App\Providers\AppServiceProvider::class,
App\Providers\ModuleServiceProvider::class, // <--- here it is!
App\Providers\AuthServiceProvider::class,
// App\Providers\BroadcastServiceProvider::class,
App\Providers\EventServiceProvider::class,
App\Providers\RouteServiceProvider::class,

Let's make our first module

We need the folder structure for our module (or model classes will be generated at the root of modules/name/app/):

mkdir -p modules/billing/app/Models

And we need to update composer.json as well:

{
    "autoload": {
        "psr-4": {
            "App\\": "app/",
            "Database\\Factories\\": "database/factories/",
            "Database\\Seeders\\": "database/seeders/",
            "Modules\\Billing\\App\\": "modules/billing/app",
            "Modules\\Billing\\Database\\Factories\\": "modules/billing/database/factories/",
            "Modules\\Billing\\Database\\Seeders\\": "modules/billing/database/seeders/"
        }
    }
}

You're going to copy/paste those last three lines for each module you create down the road.

Now we can make our model and its associated classes:

php artisan make:model --module billing --all Invoice

The result?

billing/app/
    Http/Controllers/OrderController.php
    Models/Order.php
    Policies/OrderPolicy.php

billing/database/
    factories/OrderFactory.php
    migrations/2021_09_21_203852_create_orders_table.php
    seeders/OrderSeeder.php

Fixing some stuff

Some make commands won't generate the correct namespace, no matter what base_path() we're using (for the seeder stub, it's even hardcoded 🤦). They were simply not intended to work this way. So let's fix that.

In modules/billing/database/factories/InvoiceFactory.php:

namespace Modules\Billing\Database\Factories; // <--- add the Modules\Billing prefix

Do exactly the same in modules/billing/database/seeders/InvoiceSeeder.php.

That's it. Now if you run php artisan migrate, you'll see somehting like:

Migrating: 2021_09_21_203852_create_invoices_table
Migrated:  2021_09_21_203852_create_invoices_table (38.79ms)

And if you try to generate an invoice using tinker:

Psy Shell v0.10.8 (PHP 8.0.9 — cli) by Justin Hileman
>>> Modules\Billing\App\Models\Invoice::factory()->create()
=> Modules\Billing\App\Models\Invoice {#3518
     updated_at: "2021-09-21 21:32:15",
     created_at: "2021-09-21 21:32:15",
     id: 1,
   }

Looks like everything works well in our database 👌

Congratulations, you're done!

Well, that's pretty much it. I tested all the vanilla make:* commands available, and most of them work fine (except for the database ones we had to fix, of course.)

Now if your module needs views, routes, events etc. I suggest you abuse the make:provider command.

php artisan make:provider --module billing RouteServiceProvider

Thanks for reading

I hope you enjoyed reading this article! If so, please leave a ❤️ or a 🦄 and consider subscribing! I write posts on PHP, architecture, and Laravel monthly.

Disclaimer I had this idea this morning taking my shower 🚿 I haven't thoroughly tested the implications of this, and I suggest you exert caution applying this method. Let me know in the comment what you found out 👍

Domain Driven Design Aggregates with Laravel

Benjamin Delespierre — Mon, 20 Sep 2021 02:07:18 +0000

Lately, I've been focusing on finding ways to bring Laravel and Domain Driven Design closer together. Because I love 😍 Laravel, but its architecture sucks 🤮.

So today, we're going to look at how to implement aggregates using Laravel & Eloquent.

Let's get started!

What's an aggregate?

A DDD aggregate is a cluster of domain objects that can be treated as a single unit. An example may be an order and its line-items, these will be separate objects, but it's useful to treat the order (together with its line items) as a single aggregate.
— Martin Fowler, DDD_Aggregate

Aggregates are not just clusters of data and behavior. The primary reason for the pattern is to protect business invariants for a single aggregate instance in a single transaction.
— Vaughn Vernon

What's an invariant?

Invariants are generally business rules/enforcements/requirements that you impose to maintain the integrity of an object at any given time.
— Nikesh Shetty, Designing the DDD way — Introduction

Example

Let's implement an OrderAggregate that embodies the following invariants:

customers make oders,
an order consists of a collection of items,
an order is uniquely identified,
an order must have a creation timestamp,
an order must have a shipment address,
it must be possible to calculate the total of an order, which is the sum of its items,
all items should have the same currency,

namespace Domain\Model;

use App\Models\Address;
use App\Models\Amount;
use App\Models\Currency;
use App\Models\CustomerId;
use App\Models\LineItem;
use App\Models\Order;

class OrderAggregate
{
    /** @param LineItem[] $lineItems */
    public function __construct(
        private Order $root,
        private CustomerId $customerId,
        private Address $shipmentAddress,
        private Currency $currency,
        private array $lineItems = []
    ) {
        $this->root = $root;
        $this->customerId = $customerId;
        $this->shipmentAddress = $shipmentAddress;
        $this->curreny = $currency;
        $this->lineItems = $lineItems;
    }

    public function getRoot(): Order
    {
        return $this->order;
    }

    public function createdAt(): \DateTime
    {
        return $this->root->created_at;
    }

    public function getCustomerId(): CustomerId
    {
        return $this->customerId;
    }

    public function getShipmentAddress(): Address
    {
        return $this->shipmentAddress;
    }

    public function getTotal(): Amount
    {
        $total = 0;

        foreach ($this->getLineItems() as $item) {
            $total += $item->unit_price->getValue() * $item->quantity;
        }

        return new Amount($total, $this->currency);
    }

    /** @return LineItem[] */
    public function getLineItems(): array
    {
        return $this->lineItems;
    }

    /** @throws \DomainException If $item currency is not compatible with this order */
    public function addLineItem(LineItem $item): void
    {
        if (! $this->curreny->isEqualTo($item->unit_price->currency)) {
            throw new  \DomainException(
                "Unable to add item: invalid currency",
            );
        }

        $this->lineItems[] = $item;
    }
}

Note: if you need help with value objects and Eloquent I wrote an article on the topic

What can we put in an aggregate?

An aggregate will have one of its component objects be the aggregate root. Any references from outside the aggregate should only go to the aggregate root. The root can thus ensure the integrity of the aggregate as a whole.
— Martin Fowler

Beyond that, they may contain:

Entities
Collections, Lists, Sets, etc.
Value objects
Value-typed properties (integers, strings, booleans etc.)

You may think of it as a document holding ALL the data necessary to a given transaction (or use case.)

Tip: Eloquent makes it easy to implement lazy-loading in your aggregates. In the above example, we could restructure the getLineItems method so that it loads when it's used:

public function getLineItems(): array
{
    return $this->getRoot()->items()->get()->toArray();
}

Can they have commands?

Yes. And they should.

You are not supposed to do:

$car->getEngine()->start();

But rather:

$car->start();

Forcing the exposure of aggregate's internal structure is bad design 👎

How do I persist/retrieve them?

You're going to use the Repository Pattern:

namespace App\Repositories;

use App\Models\Order;
use App\Models\OrderAggregate;

class OrderRepository
{
    public function find(int $id): OrderAggregate
    {
        $model = Order::with('items')->findOrFail($id);

        return new OrderAggregate(
            $model,
            $model->customer_id,
            $model->shipment_address,
            $model->currency,
            $model->items->toArray()
        );
    }

    public function store(OrderAggregate $order): void
    {
        \DB::transaction(function () use ($order) {
            $order->getRoot()
                ->fill([
                    'customer_id' => $order->getCustomerId(),
                    'shipment_address' => $order->getShipmentAddress(),
                    'currency' => $order->getCurrency(),
                ])
                ->save();

            foreach ($order->getLineItems() as $item) {
                $item->order()->associate($order->getRoot())->save();
            }
        });
    }
}

Rules for making your aggregates pretty 💅

From the awesome article series by Vaughn Vernon 🤩

Rule #1: Keep them small. It is tempting to cram one giant aggregate with anything every use case present and future might need. But it's a terrible design. You're going to run into performances and concurrency issues (when several people are working on the same aggregate at the same time).

It's better to have several representations of order, depending on the broader context, than one. For instance, an order from a cart display page's point-of-view is not the same as from a billing system.

If we are going to design small aggregates, what does “small” mean? The extreme would be an aggregate with only its globally unique identity and one additional attribute, which is not what's being recommended [...].
Rather, limit the aggregate to just the root entity and a minimal number of attributes and/or value-typed properties. The correct minimum is the ones necessary, and no more.
Smaller aggregates not only perform and scale better, they are also biased toward transactional success, meaning that conflicts preventing [an update] are rare. This makes a system more usable.
— Vaughn Vernon

Rule #2: Model true invariants in consistency boundaries. It sounds barbaric, but it's pretty simple; it means that, within a single transaction, there is no way one could break the aggregate consistency (its compliance to business rules.)

In other words, it should be impossible to create a bugged version of an aggregate from calling its methods.

One implication of this rule is that a transaction should only commit a single aggregate, since it's not possible by design to guarantee the consistency of several aggregates at once.

A properly designed aggregate is one that can be modified in any way required by the business with its invariants completely consistent within a single transaction.
And a properly designed bounded context modifies only one aggregate instance per transaction in all cases. What is more, we cannot correctly reason on aggregate design without applying transactional analysis.
Limiting the modification of one aggregate instance per transaction may sound overly strict. However, it is a rule of thumb and should be the goal in most cases. It addresses the very reason to use aggregates.
— Vaughn Vernon

Rule #3: Don't Trust Every Use Case. Don't blindly assemble your aggregates based on what the use case specification dictates. They may contain elements that contradict the existing model or force you into committing several aggregates in a single transaction or worse, to model a giant aggregate that fits in a single transaction.

Apply your judgment here and keep in mind that sometimes, the business goal can be achieved using eventual consistency.

The team should critically examine the use cases and challenge their assumptions, especially when following them as written would lead to unwieldy designs.
The team may have to rewrite the use case (or at least re-imagine it if they face an uncooperative business analyst).
The new use case would specify eventual consistency and the acceptable update delay.
— Vaughn Vernon

Conclusion

Murphy's law states:

Anything that can possibly go wrong, does.

An aggregate is a tactic to mitigates that problem. Within its well-designed boundaries, nothing can go wrong. You can say goodbye to those pesky ifs laying around in your code, handling those cases that are not supposed to happen but happen anyway.

Don't allow your model to grow beyond your control. Stop using raw data, POPOs, and unguarded Laravel models whose state is uncertain everywhere in your application. Use aggregates instead 👍 and connect your model to the actual business your app is supposed to carry.

Thanks for reading

I hope you enjoyed reading this article! If so, please leave a ❤️ or a 🦄 and consider subscribing! I write posts on PHP, architecture, and Laravel monthly.

A huge thanks to Vaughn Vernon for his review and his articles on DDD 🙏

Clean Architecture with Laravel

Benjamin Delespierre — Wed, 04 Aug 2021 21:44:51 +0000

Uncle Bob's Clean Architecture is quite the hype right now in the architects' world. But when it comes to actual implementations, nothing notable has been proposed for Laravel.

And that's understandable: Laravel's MVC architecture and its tendency to let you cross layers all the time using Facades doesn't help designing clean, decoupled software parts.

So today, I'm going to present you a working implementation of the Clean Architecture principles inside a Laravel app, as explained in The Clean Architecture by Robert C. Martin.

The complete, working implementation of the concepts explained here is available on my GitHub repository. I recommend you have a look at the actual code while reading this article.

For once, let's get our hands clean 👍

It all started with a diagram

The architecture must support the use cases. [...] This is the first concern of the architect, and the first priority of the architecture.

(The Clean Architecture chapter 16, p148.)

If you've never heard of use cases, you can think of it as a feature, the capacity of a system to do something meaningful. UML let you describe them using the well-named Use Case Diagrams.

In CA, use-cases are at the heart of the application. They're the microchip that controls the machinery of your app.

So, how are we supposed to implement those use cases then?

Glad you asked! Here's a second diagram:

Let me explain briefly, and we'll dive into the actual code.

The pink line is the flow of control; it represents the order in which the different components are being executed. First, the user changes something on the view (for instance, he submits a registration form). This interaction becomes a Request object. The controller reads it and produces a RequestModel to be used by the UseCaseInteractor.

The UseCaseInteractor then does its thing (for instance, creates the new user), prepares a response in the form of a ResponseModel, and passes it to the Presenter. Which in turn updates the view through a ViewModel.

Wow, that's a lot 😵 That's probably the main criticism made to CA; it's lenghty!

The call hierarchy looks like this:



Controller(Request)
  ⤷ Interactor(RequestModel)
      ⤷ Presenter(ResponseModel)
          ⤷ ViewModel

What about the ports?

I can see you're quite the observer! For the low lever layers (the Use Cases and the Entities, often referred to as the Domain, and represented as the red and yellow circles in the schema above) to be decoupled from the high-level layers (the framework, represented as the blue circle), we need adapters (the green circle). Their job is to convey messages between high and low layers using their respective API and contracts (or interfaces).

Adapters are absolutely crucial in CA. They guarantee that changes in the framework won't require changes in the domain and vice-versa. In CA, we want our use cases to be abstracted from the framework (the actual implementation) so that both can change at will without propagating the changes on other layers.

A traditional PHP/HTML application designed with clean architecture can therefore be transformed into a REST API only by changing its controllers and presenters - the Use Cases would remain untouched! Or you could have both HTML + REST side by side using the same Use Cases. That's pretty neat if you ask me 🤩

To do that, we need to "force" the adapter to "behave" the way each layer needs it to behave. We're going to use interfaces to define inputs and output ports. They say, in essence, "if you want to talk to me, you're going to have to do it this way!"

Blah blah blah. I want to see some code!

Since the UseCaseInteractor will be at the heart of everything, let's start with this one:



class CreateUserInteractor implements CreateUserInputPort
{
    public function __construct(
        private CreateUserOutputPort $output,
        private UserRepository $repository,
        private UserFactory $factory,
    ) {
    }

    public function createUser(CreateUserRequestModel $request): ViewModel
    {
        /* @var UserEntity */
        $user = $this->factory->make([
            'name' => $request->getName(),
            'email' => $request->getEmail(),
        ]);

        if ($this->repository->exists($user)) {
            return $this->output->userAlreadyExists(
                new CreateUserResponseModel($user)
            );
        }

        try {
            $user = $this->repository->create(
                $user, new PasswordValueObject($request->getPassword())
            );
        } catch (\Exception $e) {
            return $this->output->unableToCreateUser(
                new CreateUserResponseModel($user), $e
            );
        }

        return $this->output->userCreated(
            new CreateUserResponseModel($user)
        );
    }
}

There are 3 things we need to pay attention to here:

The interactor implements the CreateUserInputPort interface,
The interactor depends on the CreateUserOutputPort,
The interactor doesn't make the ViewModel himself, instead it tells the presenter to do it,

Since the Presenter (abstracted here by CreateUserOutputPort) is located in the adapters (green) layer, calling it from the CreateUserInteractor is indeed an excellent example of inversion of control: the framework isn't controlling the use cases, the use cases are controlling the framework.

If you find it too boringly complicated, forget all that and consider that all the meaningful decisions are being made at the use case level - including choosing the response path (userCreated, userAlreadyExists, or unableToCreateUSer). The controller and the presenters are just obedient slaves, devoid of business logic.

We can never rehearse it enough so sing it with me: CONTROLLERS 👏 SHOULD 👏 NOT 👏 CONTAIN 👏 BUSINESS 👏 LOGIC 👏

So how does it look from the controller's perspective?

For the controller, life is simple:



class CreateUserController extends Controller
{
    public function __construct(
        private CreateUserInputPort $interactor,
    ) {
    }

    public function __invoke(CreateUserRequest $request)
    {
        $viewModel = $this->interactor->createUser(
            new CreateUserRequestModel($request->validated())
        );

        return $viewModel->getResponse();
    }
}

You can see it relies on the CreateUserInputPort abstraction instead of the actual CreateUserInteractor implementation. It gives us the flexibility to change the use case at will and make the controller testable. More on that later.

Okay, that's very simple and stupid indeed. What about the presenter?

Again, very straightforward:



class CreateUserHttpPresenter implements CreateUserOutputPort
{
    public function userCreated(CreateUserResponseModel $model): ViewModel
    {
        return new HttpResponseViewModel(
            app('view')
                ->make('user.show')
                ->with(['user' => $model->getUser()])
        );
    }

    public function userAlreadyExists(CreateUserResponseModel $model): ViewModel
    {
        return new HttpResponseViewModel(
            app('redirect')
                ->route('user.create')
                ->withErrors(['create-user' => "User {$model->getUser()->getEmail()} alreay exists."])
        );
    }

    public function unableToCreateUser(CreateUserResponseModel $model, \Throwable $e): ViewModel
    {
        if (config('app.debug')) {
            // rethrow and let Laravel display the error
            throw $e;
        }

        return new HttpResponseViewModel(
            app('redirect')
                ->route('user.create')
                ->withErrors(['create-user' => "Error occured while creating user {$model->getUser()->getName()}"])
        );
    }
}

Traditionally, all that code would have been ifs at the controller's end. Which would have forced the use case to find a way to "tell" the controller what happened (using $user->wasRecentlyCreated or by throwing exceptions, for example.)

Using presenters controlled by the use case allows us to choose and change the outcomes without touching the controller. How great is that?

So everything relies on abstractions, I imagine the container is going get involved at some point?

You're absolutely right, my good friend! It pleases me to be in good company today.

Here's how to wire all that in app/Providers/AppServiceProvider.php:



class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        // wire the CreateUser use case to HTTP
        $this->app
            ->when(CreateUserController::class)
            ->needs(CreateUserInputPort::class)
            ->give(function ($app) {
                return $app->make(CreateUserInteractor::class, [
                    'output' => $app->make(CreateUserHttpPresenter::class),
                ]);
            });


        // wire the CreateUser use case to CLI
        $this->app
            ->when(CreateUserCommand::class)
            ->needs(CreateUserInputPort::class)
            ->give(function ($app) {
                return $app->make(CreateUserInteractor::class, [
                    'output' => $app->make(CreateUserCliPresenter::class),
                ]);
            });
    }
}

I added the CLI variant to demonstrate how easy it is to swap the presenter to make the use case return different ViewModel instances. Have a look a the actual implementation for more details 👍

Can I test this?

Oh my! It's begging you to! Another good thing about CA is that it relies so much on abstractions it makes testing a breeze.



class CreateUserUseCaseTest extends TestCase
{
    use ProvidesUsers;

    /**
     * @dataProvider userDataProvider
     */
    public function testInteractor(array $data)
    {
        (new CreateUserInteractor(
            $this->mockCreateUserPresenter($responseModel),
            $this->mockUserRepository(exists: false),
            $this->mockUserFactory($this->mockUserEntity($data)),
        ))->createUser(
            $this->mockRequestModel($data)
        );

        $this->assertUserMatches($data, $responseModel->getUser());
    }
}

The complete test class is available here.

I use Mockery for, well, mocking, but it will work with anything. It might seem like a lot of code, but it's actually quite simple to write, and it will give you 100% coverage of your use cases effortlessly.

Isn't this implementation slightly different from the book?

Yes, it is. You see CA has been designed by Java people. And, in most cases, in a Java program, if you want to update the view, you can do so directly from the Presenter.

But not in PHP. Because we don't fully control the view and because the frameworks are structured around the concept of controllers returning a response.

So I had to adapt the principles and make the ViewModel climb the call stack up to the controller to return a proper response. If you can come up with a better design, please let me know in the comments 🙏

Would you please let me know what you think in the comments? Your opinion matters to me, for I write those articles to challenge my vision and learn new things every day.

You are, of course, welcome to suggest changes to the demo repository by submitting a pull-request. Your contribution is much appreciated 🙏

This article took me four days of research, implementation, testing, and writing. I would really appreciate a like, a follow, and maybe a share on your social networks 🙏

Thanks, guys, you contribution helps to keep me motivated to write more articles for you 👍

All flavors of PHP 8 getters

Benjamin Delespierre — Sun, 01 Aug 2021 11:15:57 +0000

Getters are the most basic methods a class can have. Their only job is to return a value, usualy from its properties. There's isn't much to say about it.

Or is there? 🤨

Today I'm going to present you 10 ways you can implement a getter in PHP 8.0.

Public access
Classic getter
Classic getter, but without a verb
Getter/setter
Magic getter
Offset getter
Magic call
Reference getter
Encapsulation violation 🤫
Returning a closure

Let's get started!

Public access

class User
{
    public string $name = "Robert PAULSON";
}

✅ Pros

No need to write a getter method

❌ Cons

Cannot be part of an interface
Exposes object's internal state

Classic getter

class User
{
    public function getName(): string
    {
        return "Robert PAULSON";
    }
}

✅ Pros

Can be part of an interface
Straightforward and easy to understand

❌ Cons

¯\_(ツ)_/¯

Classic getter, but without a verb

class User
{
    public function name(): string
    {
        return "Robert PAULSON";
    }
}

✅ Pros

Can still be part of an interface
Shorter than getName

❌ Cons

Methods without a verb can be confusing

Getter/setter

class User
{
    private string $name = "Robert PAULSON";

    public function name(?string $name = null): string
    {
        if ($name) {
            $this->name = $name;
        }

        return $this->name;
    }
}

✅ Pros

Same as above
Less code to write if you also need a setter

❌ Cons

What if you want to set the value to null?
Violates the Single Responsibility Principle

Magic getter

/**
 * @property string $name
 */
class User
{
    private string $name = "Robert PAULSON";

    public function __get($key)
    {
        if ($key == 'name') {
            return $this->name;
        }
    }
}

✅ Pros

You can expose protected and private members on your own terms

❌ Cons

You can't always typehint the returned value
Some companies have banned this (seriously)
You're going to need an annotation @property or PHPStorm won't "see" it

Offset getter

class User extends ArrayAccess
{
    public offsetExists($offset): bool
    {
        return $offset == 'name';
    }

    public offsetGet($offset)
    {
        if ($offset == 'name') {
            return 'Robert PAULSON';
        }
    }
}

✅ Pros

Same as magic getter
Super cool $object['name'] notation

❌ Cons

Same as magic getter

Magic call

/**
 * @method string getName()
 */
class User
{
    public function __call($method, $args)
    {
        if ($method == 'getName') {
            return 'Robert PAULSON';
        }
    }
}

✅ Pros

Same as using magic getters
Save "space" by grouping several getters in one method
You can create aliases for your existing getters without adding new methods

❌ Cons

You're going to need an annotation @method or PHPStorm won't "see" it
If you need this to lower the number of methods in your class, it might be the sign of a design issue

Reference getter

class User
{
    private string $name = "Robert PAULSON";

    public function &getName(): string
    {
        return $this->name;
    }
}

// usage
$user = new User;
var_dump($user); // string(14) "Robert PAULSON"

$name = &$user->getName();
$name = "Tyler DURDEN";
var_dump($user); // string(12) "Tyler DURDEN"

✅ Pros

Used for performance optimizations (eliminates the function call overhead)

❌ Cons

I hope you know what you're doing

Encapsulation violation

class User
{
    private string $name = "Robert PAULSON";
}

// can't access $name because it's private
// and there's no getter to obtain its value
$user = new User();

// let's use the reflection API
$property = (new ReflectionClass(User::class))->getProperty('name');
$property->setAccessible(true);
$name = $property->getValue($user);

echo $name; // Robert PAULSON

✅ Pros

Very useful for debugging classes you don't own without rewriting them

❌ Cons

Very slow
Quite ugly

Returning a closure

class User
{
    private $name = "Robert PAULSON";

    public function obtainNameGetter(): callable
    {
        return fn() => $this->name;
    }

    public function setName(string $name): void
    {
        $this->name = $name;
    }
}

// usage
$user = new User();
$getter = $user->obtainNameGetter();

echo $getter(); // "Robert PAULSON"

// now let's change the username
$user->setName("Tyler DURDEN");

echo $getter(); // "Tyler DURDEN"

✅ Pros

Can be used to solve circular dependencies
Poor-man lazy-loading implementation
You can compose the returned closure

❌ Cons

The returned closure is a black-box
You cannot serialize the returned value easily

Did I miss something? Tell me what you think of this list in the comments and don't forget to like/follow, it keeps me motivated to write more articles for you 🤗

Using value-objects in Laravel Models

Benjamin Delespierre — Mon, 26 Jul 2021 23:41:44 +0000

(image credits the Joomla Community)

Value Objects

A value object is a small object that represents a simple entity whose equality is not based on identity: i.e. two value objects are equal when they have the same value, not necessarily being the same object.

Examples of value objects are objects representing an amount of money or a date range.

Value objects should be immutable: this is required for the implicit contract that two value objects created equal, should remain equal. It is also useful for value objects to be immutable, as client code cannot put the value object in an invalid state or introduce buggy behaviour after instantiation.

You may read the full definition on Wikipedia.

In short: Value Objects are objects that

Hold a value
Are (generally) immutables
Carry more context than native types

Use Case

Consider the following tables:

┌───────────────────┐       ┌────────────────────┐
│ invoices          │       │ invoice_line_items │
├───────────────────┤1,1    ├────────────────────┤
│ id (int, primary) │◄──┐   │ id (int, primary)  │
│ customer_id (int) │   └───┤ invoice_id (int)   │
│ status (string)   │    0,N│ label (string)     │
└───────────────────┘       │ quantity (int)     │
                            │ unit_price (int)   │
                            └────────────────────┘

(made with asciiflow)

We can immediately identify the following rules that apply here:

invoices.status values are constrained within a list of possible values (Sent, Paid, Void, etc.)
invoice_line_items.quantity and invoice_line_items.unit_price cannot be negative

While it could make sense to host the code responsible for checking the data integrity inside the models - in Invoice::setStatusAttribute and InvoiceLineItem::setQuantityAttribute for instance - I'm going to present you a more robust and elegant way to implement those rules.

Introducing Value Objects

Let's start with App\Models\InvoiceStatus (we're going to host the value objects in the same namespace as the models, more on that later.)

namespace App\Models;

final class InvoiceStatus
{
    private function __construct(
        private string $value
    ) {}

    public function __toString()
    {
        return $this->value;
    }

    public function equals(self $status): bool
    {
        return $this->value == $status->value;
    }

    public static function fromString(string $status): self
    {
        return match ($status) {
            'draft' => self::draft(),
            'sent' => self::sent(),
            'paid' => self::paid(),
            'overdue' => self::overdue(),
            'void' => self::void(),
            'writeOff' => self::writeOff(),
            default: throw new \InvalidArgumentException("Invalid status '{$status}'");
        };
    }

    public static function draft(): self
    {
        /* You’ve created an incomplete invoice and it hasn’t been sent to the customer. */
        return new self('draft');
    }

    public static function sent(): self
    {
        /* Invoice has been sent to the customer. */
        return new self('sent');
    }

    public static function paid(): self
    {
        /* Invoice has been paid by the customer. */
        return new self('paid');
    }

    public static function overdue(): self
    {
        /* Invoice has past the payment date and the customer hasn't paid yet. */
        return new self('overdue');
    }

    public static function void(): self
    {
        /* You will void an invoice if it has been raised incorrectly. Customers cannot pay for a voided invoice. */
        return new self('void');
    }

    public static function writeOff(): self
    {
        /* You can Write Off an invoice only when you're sure that the amount the customer owes is uncollectible. */
        return new self('write-off');
    }
}

You may have noticed the constructor is private, and the class is final. This ensures that nobody can derive it to create new values or instances with an invalid state, constraining the possible values to strictly the list provided by the static methods.

Trust me; this will help A LOT down the road because the values can only be changed at a single place in the app. No more search for incorrect constants & values with CTRL+SHIFT+F!

Value Object Casting

Turns out Laravel has a native solution to perform value object casting in models! All we need to do is to create a new custom cast with:

php artisan make:cast InvoiceStatusCast

And then fill it with:

namespace App\Casts;

use App\Models\InvoiceStatus;
use Illuminate\Contracts\Database\Eloquent\CastsAttributes;

class InvoicestatusCast extends CastsAttributes
{
    public function get($model, $key, $value, $attributes)
    {
        if (is_null($value)) {
            return null;
        }

        return InvoiceStatus::fromString($value);
    }

    public function set($model, $key, $value, $attributes)
    {
        if (is_string($value)) {
            $value = InvoiceStatus::fromString($value);
        }

        if (! $value instanceof InvoiceStatus) {
            throw new \InvalidArgumentException(
                "The given value is not an InvoiceStatus instance",
            );
        }

        return $value;
    }
}

The Model

Now we've defined our value object and our attribute caster, let's make Invoice use it.

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use App\Casts\InvoiceStatusCast;

class Invoice extends Model
{
    protected $fillable = [
        'status',
    ];

    protected $attributes = [
        /* default attributes values */
        'status' => InvoiceStatus::draft(),
    ];

    protected $casts = [
        'status' => InvoiceStatusCast::class,
    ];

    public function lineItems()
    {
        return $this->hasMany(InvoiceLineItem::class);
    }
}

More Value Objects

Now let's quickly do the two others:

namespace App\Models;

class UnsignedInteger
{
    private $value;

    public function __construct(int $value)
    {
        if ($value <= 0) {
            throw new \UnexpectedValueException(static::class . " value cannot be lower than 1");
        }

        $this->value = $value;
    }

    public function value(): int
    {
        return $this->value;
    }
}

final class InvoiceLineItemQuantity extends UnsignedInteger
{
    public function add(self $quantity): self
    {
        return new self($this->value() + $quantity->value());
    }

    public function substract(self $quantity): self
    {
        return new self($this->value() - $quantity->value());
    }
}

final class InvoiceLineItemUnitPrice extends UnsignedInteger
{
    public function increase(self $price): self
    {
        return new self($this->value() + $price->value());
    }

    public function decrease(self $price): self
    {
        return new self($this->value() - $price->value());
    }
}

You might be tempted to move InvoiceLineItemQuantity::add and InvoiceLineItemUnitPrice::increase to UnsignedInteger for instance, and maybe rename them both to add or sum, but then you would make it possible to write $price->add($quantity) which is a bit silly.

Those methods * look like duplication* but it's accidental. You need to keep them separated in their classes so you can precisely match the ubiquitous language of your business domain.

Use exactly the same logic as above to write the cast classes and then add them to the model:

namespace App\Models;

class InvoiceLineItem extends Model
{
    protected $fillable = [
        'label',
        'quantity',
        'unit_price',
    ];

    protected $casts = [
        'quantity' => InvoiceLineItemQuantityCast::class,
        'unit_price' => InvoiceLineItemUnitPriceCast::class,
    ];

    public function invoice()
    {
        return $this->belongsTo(Invoice::class)->withDefault();
    }
}

Usage

Now we have made a value object that guarantees data integrity by design. From your model point of view, this means it is impossible to write something in the database that doesn't match your business logic.

$invoice = tap($customer->invoices()->create(), function ($invoice) {
    $invoice->lineItems()->create([
        'label' => "Dog food"
        'quantity' => new InvoiceLineItemQuantity(3);
        'unit_price' => new InvoiceLineItemUnitPrice(314); // $3.14
    ]);

    $invoice->lineItems()->create([
        'label' => "Cat food"
        'quantity' => new InvoiceLineItemQuantity(5);
        'unit_price' => new InvoiceLineItemUnitPrice(229); // $2.29
    ]);
});

Mail::to($customer->email)->send(new InvoiceAvailable($invoice));

$invoice->update([
    'status' => InvoiceStatus::sent()
]);

Isn't it a little too complex?

The code responsible for handling validation has to go somewhere. In my opinion, it's far better to manipulate values that validates themselves rather than having validation code laying around across the whole app. Also, value objects add a lot more context to those values: you need to look at them to understand what they represent and their underlying rules. They are the embodiment of actual business constraints within your code.

I choose to locate my value objects alongside the eloquent models in my apps. I do this for two reasons: I have nowhere else to put them, and, more importantly, it is not rare a value object becomes an actual model. For example, what if my customers want to create custom statuses like "Needs validation by Mike, the accountant".

Well, you would then create an invoice_statuses table, right? Then create an InvoiceStatus model object... Wait! You can reuse the existing InvoiceStatus class and implement its methods to use the database instead of static values. This way, you keep the current code intact. This is HUGE!

Going further

I highly recommend you take a look at the excellent spatie/enum which does the heavy lifting for you. There is also to the new PHP8.1 Enum structure which will make all the above code even easier to write!

As usual, don't forget to like, leave a comment, and follow me on dev.to. It helps me stay motivated to write more articles for you!

Dealing with mixed concerns, a solutions hierarchy

Benjamin Delespierre — Wed, 14 Jul 2021 13:12:59 +0000

Every day we are confronted with the problem of duplication. When two functional pieces of software that are not related happen to share the same behaviour. Several solutions exist to address this issue and make code as reusable and flexible as possible.

Today, I want to present you with a hierarchy of these solutions and their benefits. Starting from level zero, which I consider the ugliest, up to level six, the most elegant and abstract (and therefore, complex):

Let's dive into it!

Lv0 - Copy/paste is better than nothing

class Car
{
    function go()
    {
        echo "aha, engine goes brrrrr";
    }
}

class GarageDoor
{
    function open()
    {
        echo "aha, engine goes brrrrr";
    }
}

When time is a scarce resource, you may want to copy and paste code around to meet deadlines. It's ugly, but hey, if it works, it works! An ugly software is better than no software, after all.

Lv1 - Functional inheritance is better than copy/paste

class Vehicle
{
    function startEngine()
    {
        echo "aha, engine goes brrrrr";
    }
}

class Car extends Vehicle
{
    function go()
    {
        parent::startEngine();
    }
}

class GarageDoor extends Vehicle
{
    function open()
    {
        parent::startEngine();
    }
}

It's still hideous, in my opinion, but at least the code is not duplicated.

The first problem here is that not all vehicles have engines (a bike, for example, has none). Hence, as the codebase grows, the Vehicle class is going to have more and more responsibilities (and more if statements), eventually becoming a God Object.

Also, we can see the problem with GarageDoor; just because it has an engine doesn't make it a vehicle.

Lv2 - Traits & mixins are better than functional inheritance

trait HasEngine
{
    function startEngine()
    {
        echo "aha, engine goes brrrrr";
    }
}

class Car
{
    use HasEngine;

    function go()
    {
        $this->startEngine();
    }
}

class GarageDoor
{
    use HasEngine;

    function open()
    {
        $this->startEngine();
    }
}

Traits & mixins are a form a horizontal inheritance which gives you more flexibility. Think of it as * pieces of equipment* for your classes, just like you would equip a sword and armour to a video game character.

It's a lot better than functional inheritance because you can have different traits & mixins for different use-cases, eliminating the accumulation of responsibilities in the same class. The only problem with this approach is that it's not dynamic: you may not be able to swap traits & mixins at runtime.

Lv3 - Static services are better than traits & mixins

class EngineService
{
    static function startEngine()
    {
        echo "aha, engine goes brrrrr";
    }
}

class Car
{
    function go()
    {
        EngineService::startEngine();
    }
}

class GarageDoor
{
    function open()
    {
        EngineService::startEngine();
    }
}

Another issue with traits & mixins is that the methods they expose become part of the class they're equipped on. So it's easy to violate the Single Responsibility Principle when using them.

Using static services solves this problem. Now the Car and GarageDoor class can choose which method they want to expose and simply delegate the behaviour to EngineService.

The downside of this approach is the introduction of static coupling. When you have too much of it across your app, code becomes rigid, and it's challenging to make changes without introducing regressions.

Lv4 - A service container is better than static services

class Engine
{
    function start()
    {
        echo "aha, engine goes brrrrr";
    }
}

class Container
{
    function makeEngine(): Engine
    {
        return new Engine;
    }
}

class Car
{
    function __construct(
        private Container $container
    ) {}

    function go()
    {
        $this->container->makeEngine()->start();
    }
}

class GarageDoor
{
    function __construct(
        private Container $container
    ) {}

    function open()
    {
        $this->container->makeEngine()->start();
    }
}

Using the Registry Design Pattern, we are now able to define our hierarchy of dependencies dynamically by swapping the container (or the container's configuration, which is more common.)

It's fundamentally the same thing as static services, except it's not hardcoded. Thus we can define several strategies of behaviour for different contexts. This approach also makes testing things a lot easier because you can mock the services built by the container.

For instance, you could have a mailer service that sends actual emails defined in a ProductionContainer class and a fake mailer that logs them instead, defined in LocalContainer.

Lv5 - Dependency injection is better than a service container

class Engine
{
    function start()
    {
        echo "aha, engine goes brrrrr";
    }
}

class Car
{
    public function __construct(
        private Engine $engine
    ) {}

    public function go()
    {
        $this->engine->start();
    }
}

class GarageDoor
{
    public function __construct(
        private Engine $engine
    ) {}

    public function open()
    {
        $this->engine->start();
    }
}

Injecting the service container has one major flaw: it makes all the classes in your system depend on it. Therefore, it lowers the reusability of your classes and components in other contexts. It also forces you to write adapters for every library you want to use because chances are they aren't fit for your specific container.

The service injection approach makes the class dependant on the delegation services. It gives you a lot of flexibility at the cost of more glue-code to tie those implementations together. Most modern framework containers are, in fact, able to automatically infer the dependency chain for you when you build an object, so it's not that big of a deal in reality.

Lv6 - Dependency inversion is better than dependency injection

interface EngineInterface
{
    function start();
}

class Engine implements EngineInterface
{
    function start()
    {
        echo "aha, engine goes brrrrr";
    }
}

class Car
{
    function __construct(
        private EngineInterface $engine
    ) {}

    function go()
    {
        $this->engine->start();
    }
}

class GarageDoor
{
    function __construct(
        private EngineInterface $engine
    ) {}

    function open()
    {
        $this->engine->start();
    }
}

This approach is the same as injecting a concrete service but with a subtle nuance: the required type on Car and GarageDoor constructors is an interface.

While it is true that you could always provide a subtype of Engine, the implementation of Engine would shape its child classes. Therefore, you would have to override a lot of stuff in those child classes to modify inherited behaviour, which is sub-optimal.

This problem doesn't exist with an interface precisely because there is no implementation to override. Instead, you provide the intended implementation while retaining the shape of the interface (its methods prototypes).

It is the essence of the Dependency Inversion Principle that states:

High-level modules (like Car) should not depend on low-level modules (like Engine). Both should depend on abstractions (like EngineInterface).
Abstractions should not depend on details. Details (concrete implementations) should depend on abstractions.

Which level should I use?

As with everything in programming, there is no straight do or don't. See, a system only using the 6th level, Dependency Inversion, is undoubtedly very elegant and robust, but it's also very complex and verbose. Sometimes, a static service can do a better job. I want to remind the #1 rule of Design here: don't overdo it.

I encourage you to see all those solutions as complementary. Except for level zero (copy/paste), please avoid doing that as much as you can. Pretty please 🙏

Would you suggest an improvement to this list?

Please leave a comment below to tell me what you think, and don't forget to like the article. It keeps me motivated to write more. 😅

Package Artisan commands in 5 minutes

Benjamin Delespierre — Fri, 16 Apr 2021 11:12:14 +0000

A while ago, I wrote a Laravel command that validates Blade templates in order to become part of my continuous integration pipeline.

It just compiles the given Blade templates and then uses the PHP internal linter to validate them.

Yesterday, someone just asked me if I planned to distribute it as a standalone phar archive.

I thought it would be interesting so here's how I did it.

First, make a standalone executable

Laravel Blade Linter is distributed as a Laravel package and is intended to be run as follow:

php artisan blade:lint <files>

Since it's an Artisan command, it cannot run outside of a Laravel project...

Or can it?

Turns out Artisan commands are built on top of Symfony console, so you can start them like this:

// create the Symfony console application
$application = new Application();
$application->add(new BladeLinterCommand);
$application->run();

But the command leverage Laravel's services, so we need to provide them to it:

// create an empty container
$laravel = new Container();

$laravel['config'] = fn() => new Config([
    // use current directory as view path
    'view.paths' => getcwd(),

    // send compiled views to /tmp
    'view.compiled' => sys_get_temp_dir(),
]);

// register services the command needs
(new FilesystemServiceProvider($laravel))->register();
(new ViewServiceProvider($laravel))->register();

// set the container so the Config::get calls resolve
Facade::setFacadeApplication($laravel);

// prepare the command
$command = new BladeLinterCommand();
$command->setLaravel($laravel);

And now it runs properly inside its Symfony application shell!

# now the command can run outside of Laravel!
bin/blade-linter <files>

The final script is available here.

Time to package it

Building a phar archive is easier than I thought it would be. All you need is phar-composer.

# install phar-composer globally
composer global require clue/phar-composer

Then register the executable we made above in composer.json:

{
    "bin": [
        "bin/blade-linter"
    ]
}

Now we can build the phar:

phar-composer build ./

The result is an executable archive that can be distributed as a standalone application.

$ laravel-blade-linter.phar lint tests/views/
PHP Parse error:  syntax error, unexpected ')' in tests/views/invalid.blade.php on line 1

And voilà

Don't forget to leave a like and tell me in the comments what you think of this article.

From the same author:

PHPUnit from scratch in 5 minutes

Benjamin Delespierre — Wed, 09 Dec 2020 15:41:42 +0000

Requires: Composer, PHP>7.3, Xdebug

Installation

Use composer to install PHPUnit:

$ composer require phpunit/phpunit

Next, update composer.json so the autoloader can find your tests:

{
    "autoload": {
        "psr-4": {
            "Tests\\": "tests/"
        }
    }
}

Then run this command to create the PHPUnit configuration file:

vendor/bin/phpunit --generate-configuration

Write a test

We are going to test a very simple repository:

<?php

namespace App\Repositories;

use App\Entities\Person;
use App\Exceptions\EntityNotFoundException;

class PersonRepository
{
    protected $db;

    public function __construct(\PDO $db)
    {
        $this->db = $db;
    }

    public function find(int $id): Person
    {
        $stmt = $this->db->prepare(
            'SELECT id, name, email FROM persons WHERE id = :id'
        );

        if (! $stmt) {
            throw new \RuntimeException(
                "unable to prepare statement"
            );
        }

        if (! $stmt->execute(compact('id'))) {
            throw new \RuntimeException(
                "unable to execute statement: {$stmt->queryString}"
            );
        }

        $person = $stmt->fetchObject(Person::class);

        if (! $person) {
            throw new EntityNotFoundException(
                Person::class,
                compact('id')
            );
        }

        return $person;
    }
}

The test class (note the Test suffix on the classname):

<?php

namespace Tests\App\Repositories;

use App\Entities\Person;
use App\Exceptions\EntityNotFoundException;
use App\Repositories\PersonRepository;
use PHPUnit\Framework\TestCase;

/**
 * @covers \App\Repositories\PersonRepository
 */
class PersonRepositoryTest extends TestCase
{
    protected $pdo;

    public function setUp(): void
    {
        //
        // this setUp method is intended to crate
        // the environment in which the test will
        // take place.
        // Typically, the database state...
        //
        // I would strongly recommend to use SQLite
        // in-memory so you don't pollute your
        // actual database with test data.
        //

        $this->pdo = new \PDO("sqlite::memory:");

        $this->pdo->exec("
            CREATE TABLE `persons` (
                id INT PRIMARY KEY,
                name STRING,
                email STRING
            )
        ");

        $stmt = $this->pdo->prepare(
            "INSERT INTO `persons` VALUES (:id, :name, :email)"
        );

        $stmt->execute([
            'id' => 1,
            'name' => 'Nathalie PORTMAN',
            'email' => 'nathalie.portman@example.com'
        ]);

        $stmt->execute([
            'id' => 2,
            'name' => 'Jack BLACK',
            'email' => 'jack.black@example.com'
        ]);

        $stmt->execute([
            'id' => 3,
            'name' => 'Leonardo DICAPRIO',
            'email' => 'leonardo.dicaprio@oexample.com'
        ]);
    }

    /**
     * @covers \App\Repositories\PersonRepository::find
     * @dataProvider findProvider
     */
    public function testFind(int $id, array $data)
    {
        //
        // In this test we will test several valid
        // use-cases for the find() method. They are
        // described by the scenarios returned by
        // findPovider() (see below).
        //
        // Each scenario is run after another, passing
        // the variables to the testFind() function,
        // allowing us to test several conditions with
        // the same test.
        //

        $repository = new PersonRepository($this->pdo);

        $person = $repository->find(1);

        $this->assertInstanceOf(
            Person::class,
            $person,
            "The return of 'App\Repositories\PersonRepository::find' should be an 'App\Entities\Person' instance"
        );

        $this->assertEquals(
            'Nathalie PORTMAN',
            $person->name,
            "The name of the person with id '{$id}' should be '{$data['name']}'"
        );

        $this->assertEquals(
            'nathalie.portman@example.com',
            $person->email,
            "The email of the person with id '{$id}' should be '{$data['email']}'"
        );
    }

    /**
     * @covers \App\Repositories\PersonRepository::find
     */
    public function testFindFailsWhenDatabaseIsNotReady()
    {
        //
        // in this test (and the following) we will
        // test invalid use-cases. Places where the
        // execution of the find() method is expected
        // to fail - in our case by throwing an
        // exception.
        //

        $this->expectException(\RuntimeException::class);
        $this->expectExceptionMessage("unable to prepare statement");

        // for this test we connect to an empty database
        // so we are sure the query will fail.
        $repository = new PersonRepository(new \PDO("sqlite::memory:"));
        $repository->find(1);
    }

    /**
     * @covers \App\Repositories\PersonRepository::find
     */
    public function testFindFailsWhenQueryFails()
    {
        $this->expectException(\RuntimeException::class);
        $this->expectExceptionMessage("unable to execute statement");

        // let's create a PDO mock that returns statements
        // whose execute method will always return false
        $pdo = new class("sqlite::memory:") extends \PDO {
            public function prepare($statement, $options = null) {
                $stmt = new class {
                    public function execute() {
                        return false;
                    }
                };
                $stmt->queryString = $statement;
                return $stmt;
            }
        };

        $repository = new PersonRepository($pdo);
        $repository->find(1);
    }

    /**
     * @covers \App\Repositories\PersonRepository::find
     */
    public function testFindFailsWhenNoResultFound()
    {
        $this->expectException(EntityNotFoundException::class);
        $this->expectExceptionMessage("unable to find entity");

        $repository = new PersonRepository($this->pdo);
        $repository->find(4);
    }

    public function findProvider(): array
    {
        //
        // This method is not a test but rather
        // a data-provider (hence the name) whose
        // job is to describe scenarios.
        //
        // Those scenarios are identified by their
        // name (which is very helpful when a test
        // fails) and consist of values that will
        // be passed as arguments of a test method
        // (see testFind() above.)
        //

        return [
            "Scenario 1 : user with id '1' is 'Nathalie PORTMAN'" => [
                'id' =>  1,
                'data' => [
                    'name' => "Nathalie PORTMAN",
                    'email' => "nathalie.portman@example.com",
                ],
            ],

            "Scenario 2 : user with id '2' is 'Jack BLACK'" => [
                'id' =>  2,
                'data' => [
                    'name' => "Jack BLACK",
                    'email' => "jack.black@example.com",
                ],
            ],

            "Scenario 3 : user with id '3' is 'Leonardo DICAPRIO'" => [
                'id' =>  3,
                'data' => [
                    'name' => "Leonardo DICAPRIO",
                    'email' => "leonardo.dicaprio@oexample.com",
                ],
            ],
        ];
    }
}

Execute your test

Now you just run:

$ vendor/bin/phpunit

And you should get the following result:

PHPUnit 9.5.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 7.4.3
Configuration: /home/benjamin/Workspace/bdelespierre/phpunit-demo/phpunit.xml

......                                                              6 / 6 (100%)

Time: 00:00.005, Memory: 6.00 MB

OK (6 tests, 15 assertions)

Get the coverage report

Run:

$vendor/bin/phpunit --coverage-text

And you should get the following result:

PHPUnit 9.5.0 by Sebastian Bergmann and contributors.

Runtime:       PHP 7.4.3 with Xdebug 2.9.2
Configuration: /home/benjamin/Workspace/bdelespierre/phpunit-demo/phpunit.xml

......                                                              6 / 6 (100%)

Time: 00:00.058, Memory: 10.00 MB

OK (6 tests, 15 assertions)


Code Coverage Report:
  2020-12-09 15:21:57

 Summary:
  Classes: 100.00% (1/1)
  Methods: 100.00% (2/2)
  Lines:   100.00% (16/16)

App\Entities\Person
  Methods:  ( 0/ 0)   Lines:  (  0/  0)
App\Exceptions\EntityNotFoundException
  Methods:  ( 0/ 0)   Lines:  (  0/  0)
App\Repositories\PersonRepository
  Methods: 100.00% ( 2/ 2)   Lines: 100.00% ( 16/ 16)

Run tests every time you commit

Want to make sure you don't break things before comitting? Easy!

First you need to create a file in .git/hooks/pre-commit:

#!/bin/bash
vendor/bin/phpunit

Then make it executable:

chmod +x .git/hooks/pre-commit

And voilà!

Don't forget to leave a like and tell me in comments what you think of this article.

From the same author:

How to add basic localization to your HTML page with just jQuery

Benjamin Delespierre — Mon, 07 Sep 2020 16:31:21 +0000

I want basic translation on my single, static HTML page but I don't want to import no complex JS lib... What do I do?

Very simple my friend

HTML structure

<html lang="en">
  <body>
    <p lang="en">English please!</p>
    <p lang="fr">Hon hon croissant baguette!</p>
    <button type="button" lang="fr" data-toggle="lang" data-lang="en">English</button>
    <button type="button" lang="en" data-toggle="lang" data-lang="fr">Français</button>
    <script src="jquery.js"></script>
    <script src="language.js"></script>
  </body>
</html>

Go get jQuery here. If you don't want it I think you can make your own vanilla version of the script below.

The JS script

$('[data-toggle="lang"]').click(function(event) {
  event.preventDefault();
  $('html').attr('lang', $(this).attr('data-lang'));
});

// auto-detect the best lang setting
const params = new URLSearchParams(window.location.search);

if (params.has('lang')) {
  $('html').attr('lang', params.get('lang'));
} else if (navigator.language.match(/^(en|fr)/)) {
  $('html').attr('lang', navigator.language.substr(0, 2))
}

That's it. The HTML will now respond to the lang attribute in the <html> tag. You can control it adding ?lang=fr to the URL or let the browser decide with navigator.language.

Enjoy!

Perception Hashing in PHP

Benjamin Delespierre — Mon, 24 Aug 2020 10:01:02 +0000

TL;DR

Install the lib with composer:

composer install bdelespierre/php-phash

It exposes 2 commands:

vendor/bin/phash generate <image>
vendor/bin/phash compare <image1> <image2>

Perceptual Hashing

Let's say you are developing a social network and you want to prevent people from reposting other people's content. How would you do that?

You can't really use MD5 checksum because chances are the files you're comparing are going to be slightly different and therefore, their hashes won't be the same.

Fortunately, there's a very simple method to determine programmatically whether an image "looks like" another: Perceptual Hashing.

Lucky you, I just wrote a lib to do just that! Here's how it works.

Demonstration

Note: instructions below are borrowed from Hackerfactor, thanks to them for introducing me this algorithm.

Step1: resize to 8x8
Step2: reduce the colors to grayscale.
Step3: calculate the color average.
Step4: iterate over the pixels to compute the bits; if the pixel color is below the average, it's a zero, above it's a one.
Step5: create the 64 bits hash

In PHP

Looks a little bit like this:

$image = $this->manager->make($file)
    ->resize($size, $size)
    ->greyscale();

$sum = 0;
for ($x = 0; $x < $size; $x++) {
    for ($y = 0; $y < $size; $y++) {
        $sum += $image->pickColor($x, $y, 'array')[0];
    }
}

$mean = $sum / ($size ** 2);
$bits = "";
for ($x = 0; $x < $size; $x++) {
    for ($y = 0; $y < $size; $y++) {
        $bits .= $image->pickColor($x, $y, 'array')[0] > $mean ? 1 : 0;
    }
}

You don't have to copy that. Just grab the package.

How to compare hashes

Our hash here is simply a bitfield. I expressed it as a string instead of an acutal bitfield because it's easier to manipulate, especially for beginners.

Now to determine of "far" an image is from another, what we need to do is to compare their hashes. We can do that using the Hamming Distance.

$hash1 = phash('images/1.jpg');
$hash1 = phash('images/2.jpg');
$size  = strlen($hash1);

for ($dist = 0, $i = 0; $i < $size; $i++) {
    if ($hash1[$i] != $hash2[$i]) {
        $dist++;
    }
}

$similarity = 1 - $dist / $size;

And voilà! $similarity will be a float between 0 (entirely different) and 1 (exactly the same). You may consider any value above 0.95 means the images are very close.

Leave a like and comment to tell me what you think.

See you soon for more useful snippets like this one!

How to check Laravel view syntax

Benjamin Delespierre — Tue, 18 Aug 2020 14:22:44 +0000

See it on GitHub

TL;DR

From inside your Laravel project, do:

composer require bdelespierre/laravel-blade-linter
php artisan blade:lint

Example output:

PHP Parse error:  syntax error, unexpected ')' in resources/views/_form_errors.blade.php on line 19

Add it to your pre-commit hook so you never commit an invalid file

Open .git/hooks/pre-commit
Add the following:

#!/bin/bash
output=$(git diff --name-only --diff-filter=d --cached | grep ".blade.php$" | xargs -r php artisan blade:lint)
exitcode=$?

C_RESET='\e[0m'
C_RED='\e[31m'
C_GREEN='\e[32m'

if [[ 0 == $exitcode || 130 == $exitcode ]]; then
    echo -e "${C_GREEN}BLADE OK!${C_RESET}"
else
    echo -e "${C_RED}BLADE NOK!${C_RESET}\n\n$output"
    exit 1
fi

???
PROFIT!!!

As usual, leave a like and a comment. Don't hesitate to reach out if you have issues with this script.

How to setup Git commit hooks for PHP

Benjamin Delespierre — Mon, 10 Aug 2020 15:20:48 +0000

This very simple script will run these checks each time you commit:

PHP Internal Linter to check your code for syntax errors
PHP Code Sniffer to check for coding standard (PSR-2)
PHPStan to analyse the code and find bugs

Overall it takes a few seconds and it analyses only the staged files - those in green when you do a git status.

If a single check fails the error message is displayed and the commit is aborted.

Example:

[1/3] php lint            OK!
[2/3] code sniffer        OK!
[3/3] phpstan             NOK!

 1/1 [▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓] 100%

 ------ --------------------------------------------------------------------- 
  Line   CanSendInvitation.php                                                
 ------ --------------------------------------------------------------------- 
  14     Parameter $lol of method App\Rules\CanSendInvitation::__construct()  
         has invalid typehint type App\Rules\Noob.                            
 ------ --------------------------------------------------------------------- 

 [ERROR] Found 1 error

Step 1: requirements

You're going to need some packages to validate your code so go ahead and install:

composer install --dev phpstan/phpstan
composer install --dev squizlabs/php_codesniffer

Step 2: create the hook

In .git/hooks/pre-commit write:

#!/usr/bin/env bash

# get bash colors and styles here: 
# http://misc.flogisoft.com/bash/tip_colors_and_formatting
C_RESET='\e[0m'
C_RED='\e[31m'
C_GREEN='\e[32m'
C_YELLOW='\e[33m'

function __run() #(step, name, cmd)
{
    local color output exitcode

    printf "${C_YELLOW}[%s]${C_RESET} %-20s" "$1" "$2"
    output=$(eval "$3" 2>&1)
    exitcode=$?

    if [[ 0 == $exitcode || 130 == $exitcode ]]; then
        echo -e "${C_GREEN}OK!${C_RESET}"
    else
        echo -e "${C_RED}NOK!${C_RESET}\n\n$output"
        exit 1
    fi
}

modified="git diff --diff-filter=M --name-only --cached  | grep \".php$\""
ignore="resources/lang,resources/views,bootstrap/helpers,database/migrations,bin"
phpcs="vendor/bin/phpcs --report=code --colors --report-width=80 --standard=PSR2 --ignore=${ignore}"

__run "1/3" "php lint" "${modified} | xargs -r php -l"
__run "2/3" "code sniffer" "${modified} | xargs -r ${phpcs}"
__run "3/3" "phpstan" "${modified} | xargs -r vendor/bin/phpstan analyse"

The line

ignore="resources/lang,resources/views,bootstrap/helpers,database/migrations,bin"

is project specific. It's the comma separated list of paths to ignore in the PHP Code Sniffer analysis. Typically, you add the paths for which the PSR-2 makes no sense, like configuration or translation files.

You may change it to whatever you want.

My team has been using and refining this script for years and it has saved us countless hours in refactoring. The sooner you detect errors the better.

Our real script includes more tests that are specific to our app like unit & behavioral test to ensure you broke nothing. I'm sure with a little imagination you are capable to adapt the script to your project.

I suggest you play around with it and share what you find out in the comments.

A usual don't forget to like and comment, that keeps me motivated to write more content for you!

Happy coding!