DEV Community: Marc Guinea

Improve your factories in Symfony

Marc Guinea — Thu, 03 Mar 2022 14:12:27 +0000

Sometimes we need to retrieve some kind of handler class that depending on an attribute is different.

Thanks to Factory pattern we can solve this scenario in an elegant way... but we can improve it through the Service Container.

In this case we are going to see how to do it with Symfony Service Container, but this could be achieved by any other Service Container implementation.

Example scenario

Let's imagine a (more or less) real situation and work with it: We have an endpoint that depending on payload parameter "channel", we will send a "message" through different possible communication channels (email, sms, letter...).

To make things easier, we will do not cover additional parameters as to or phone_number etc.

Example payload:

{
  "channel": "email",
  "message": "Hello world"
}

Using a simple factory

The easiest way to solve this is creating a factory class that solves that logic:

final class ChannelFactory
{
    public static function create(string $type): ChannelInterface
    {
      switch($type) {
        case 'email':
          return new EmailChannelHandler();
        break;
        case 'sms':
          return new SmsChannelHandler();
        break;
      }

      throw new InvalidArgumentException('Unknown channel given');
    }
}

Pros

Easy to read if only 2 or 3 different types

Cons

Difficult to read if lot of types
You have to add code to add a new type

Using a simple factory through service container

Let's make it more scalable and maintainable!

We can have an array of compatible handlers and decide which one is the correct. You need to add the related type to the Channel handler with some method like getType().

final class ChannelFactory
{
    public function __construct(private ChannelInterface ...$channels)
    {
    }

    public function create(string $type): ChannelInterface
    {
      foreach($this->channels as $channel) {
        if ($type === $channel::getType()) {
          return new $channel;
        }
      }

      throw new InvalidArgumentException('Unknown channel given');
    }
}

And now, in our services.yml file we initialize it as follows:

App\ChannelFactory:
    arguments:
      - App\EmailChannelHandler
      - App\SmsChannelHandler

Pros

You can add as many handlers as you want without changing php code
Easy to add new handlers

Cons

Maybe a little bit less easy to read for a noob

Conclusion

Service Container is a pattern really powerful and nowadays we have some amazing implementations that can help us a lot.

It's worth to use them and give to our application more flexibility even adding a little complexity for newcomers.

Updated! (2022-03-07)

As Valentin Silvestre suggested, there is a better way to set up the container to make it even more automagically:

_instanceof:
        App\ChannelHandlerInterface:
            tags: ['app.channel_handler']

App\ChannelFactory:
    arguments:
      - !tagged_iterator app.channel_handler

This is an awesome way to tell to service container that all implementations of ChannelHandlerInterface should be loaded in our factory, so we don't need to write each one in a list.

Thanks Valentin!

Stop using Mocking libraries

Marc Guinea — Sun, 15 Aug 2021 21:37:02 +0000

This weekend I read a post titled "Don't use Mocking libraries" by Crell and I think it's a gold nugget.

I will just make an overview of it to show you how powerful and clever solution he is proposing us.

Mock libraries are great but we can achieve the same feature with just plain PHP giving an:

Easier reading and understanding of our code.
Better performance.
Less dependencies (oh yes please, less composer packages to keep up to date).

Example

We have a UserRepository we need to mock to make our Unit Tests without coupling with infrastructure layer (MySQL, SQLite...)

Let's show our scenario:


class User
{
    private string $id;

    public function __construct(string $id)
    {
        $this->id = $id;
    }

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

interface UserRepository
{
    public function findById(string $id): User;
}

// An example implementation of our repository.
// not required for our example.
class InMemoryUserRepository implements UserRepository
{
    private array $users;

    public function findById(string $id): User
    {
        return $this->users[$id];
    }
}

Well, it's time to mock it to run our tests. We just need to create a class that mocks our UserRepository

$userRepositoryMock = new class implements UserRepository
{
    public function __construct() {}

    public function findById(string $id): User
    {
        switch($id) {
            case '1':
                return new User('1');
            case '2':
                return new User('2');
        }

        throw new \Exception('Not found');
    }
};

Boom! just using an anonymous class and implementing our interface we have the UserRepository mocked and ready to test

public function itShouldTestSomething(): void
{
    $user = $userRepositoryMock->findById('1');

    $this->assertEquals('1', $user->id());
}

Conclusion

It's usual to look for libraries / packages that help us to implement some feature to avoid reinventing the wheel and save some time but this is (sometimes) not necessary and easily achieve with just pure PHP.

Create dummy objects for testing

Marc Guinea — Thu, 12 Aug 2021 10:30:38 +0000

When testing our application, we usually need to use our objects with fake data in order to cover as much as possible all combinations.

Here is where Object Mother pattern helps us.

Use case

Imagine we have the following classes that we need for any of our tests:

class UserName
{
    public function __construct(private string $value)
    {
    }

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

class User
{
    public function __construct(private UserName $name)
    {
    }

    public function name(): UserName
    {
        return $this->name;
    }
}

As you can see, there is an entity class called User which contains a value object called UserName corresponding to the name attribute.

Instead of forcing its values in a test (which will make it weak, because it tests the same data each time) we can use the pattern Object Mother.

Object Mother pattern gives us the benefits of auto generating dummy data plus force it to fixed value if required.

Implementation

In our example case we need a UserNameMother and UserMother classes. Let's see how to implement them:

class UserNameMother
{
    public static function create(?string $value = null): UserName
    {
        $random = ['Marc', 'Anna', 'Júlia', 'Ivet'];

        return new UserName($value?->value() ?? $random[rand(0, count($random) - 1)]);
    }
}

class UserMother
{
    public static function create(?UserName $name = null): User
    {
        return new User($name?->value() ?? UserNameMother::create()->value());
    }
}

We have set 4 different names that will be set randomly, but using a fake data provider like FakerPHP we can achieve a bigger set of data.

Usage

Let's see how to use it in our test.

class SomeTest extends TestCase
{
    /** @test */
    public function itShouldAssertSomething(): void
    {
        $user = UserMother::create();

        $this->assertNotNull($user->name());
    }
}

Sometimes we need to have a no random attribute, so we can force it. In the next example, we force the name to 'John' value:

class SomeTest extends TestCase
{
    /** @test */
    public function itShouldAssertSomething(): void
    {
        $user = UserMother::create(
            UserNameMother::create('John')
        );

        $this->assertEquals('John', $user->name()->value());
    }
}

If we had more attributes, depending on the test, we can combine random and fixed values.

Conclusion

Our example is really simple and silly, but imagine the flexibility of that approach; your tests can use a huge amount of combinations when required giving them more strength and coverage.

Special thanks to Christian Puga

Understanding Dependency Inversion principle

Marc Guinea — Tue, 10 Aug 2021 12:55:13 +0000

"Depend upon abstractions, [not] concretions."

Dependency Inversion is the "D" of the SOLID principles promoted by Robert C. Martin.

There are a lot of articles talking about it, but I want to explain it as easily as possible through an example.

When you create a new service, create first its interface, then implement it in a class.

Example

A service that calculates the average of two numbers.

Interface has the contract that will always be respected

interface AverageCalculator
{
    public function calculate(float $first, float $second): float;
}

Then, the implementation (which can be anything... a call to an external API, package, your own implementation...)

use AverageCalculator;

class InMemoryAverageCalculator implements AverageCalculator
{
    public function calculate(float $first, float $second): float
    {
        return ($first + $second) / 2;
    }
}

When you inject it in a controller, never inject the class, inject the interface. Let Service Container resolve it.

use AverageCalculator;

class Somewhere
{
    private AverageCalculator $calculator;

    public function __construct(AverageCalculator $calculator)
    {
        $this->calculator = $calculator;
    }

    public function __invoke(float $first, float $second): float
    {
        return $this->calculator->calculate($first, $second);
    }
}

Service Container knows what is the implementation (InMemoryAverageCalculator) so we just need to configure it if required.

Benefits

There are several benefits of this approach:

You force yourself at first step to define a contract (interface) knowing what you want.
You can change the implementation at any time without having to change everywhere it is used.
Concretions will not affect to the design of your application because your interface rules the inputs / outputs.

Conclusion

When injecting an interface, you are depending upon an abstraction, you don't set the class that implements that logic but yo define what to expect from that class.

This brings a lot of flexibility and adaptation to changes.

Remember:

Abstraction === Interface
Concretion === Class with implementation

How to integrate an external API into your PHP application🔥

Marc Guinea — Tue, 10 Aug 2021 07:40:38 +0000

You are developing an application that requires an integration with a third party API to provide you some data or any other functionality but... what is the best way to approach it? should I use anything special?

As always, there is no a magic perfect approach, but I will explain what worked for me.

Context example

First of all, we need to define what exactly we want to and what we need.

Our application needs some external service (API) that giving a minimum and maximum integer numbers, it returns a random integer number.

Then, after defining or requirements and use cases, it's time to search the best service that covers it all.

There is a service that fits our requirements! let's create a provider that implements http://www.randomnumberapi.com

Definition

We have made the effort to know what we need and how, so it's time to define a contract (interface).

Why? if we have an interface that defines the methods to use and the parameters, the implementation can be changed at any time without breaking down the application.

We need some name that identifies what is it doing. This is one of the most complex parts of development... NAMING!

Do not use words that do not add anything like manager.
Read the user story that defines what is needed to get some clues.
Never use the name of the specification you are going to implement.
Avoid acronyms or abbreviations.

interface RandomNumberProvider
{
    public function generate(int $min, int $max): int;
}

Now, it's time to create a class that implements our interface.

Implementation

There are different http clients that will help us to make a connection to an external API. I like those which implements PSR standards as much as possible.

I will use Guzzle but feel free to use the one you like the most.

If you are using composer, just run composer require guzzlehttp/guzzle to install it in your project as a new dependency.

use GuzzleHttp\Client as HttpClient;

final class RandomNumberAPIProvider implements RandomNumberProvider
{
    private HttpClient $client;

    public function __construct(HttpClient $client)
    {
        $this->client = $client;
    }

    public function generate(int $min, int $max): int
    {
        $response = $this->client->request('GET', 'http://www.randomnumberapi.com/api/v1.0/random?min='.$min.'&max='.$max.'&count=1');

        return json_decode($response->getBody(), true)[0];
    }
}

Use the benefits of a Service Container and bind the interface to the implementation to keep Inversion of Control (Dependency Inversion Principle). This brings you the possibility to change the implementation to another API or service without breaking the application.

Testing

Some API have a quota limitation of usage or maybe they will charge you costs even in development environment.

A good approach is to mock it using some tool for this purpose.

I have used Killgrave and the result was really good. The best of all is that you can configure a mock API just using yml configurations files.

Conclusion

It's easy to be overwhelmed when integrating some external API so, if we start thinking on what we need and forgetting the complexity of the specific implementation we will have a better overview and we will not fall in a headache hell.

Interfaces bring us the benefit of separation of concerns and avoid to be hardly coupled to an external implementation. This gives us freedom to change the service if our requirements change.

Feature flags in your Symfony project 🌱

Marc Guinea — Fri, 06 Aug 2021 11:36:26 +0000

Feature flag, or also known as Feature switch, is a functionality that allows to your app to enable or disable some parts on runtime depending on your needs.

Why?

There are many reasons to implement feature flags in your project:

An specific feature must be available for a single customer at first.
You have to deploy it but it's not finished yet.
Feature is production ready but there is an specific date to be available to public API...

How?

First of all, let's create an interface to abstract the implementation:

interface FeatureChecker
{
    public function isEnabled(string $feature): bool;
}

At this point, we can implement it in several ways. Let's see the easiest one: In Memory implementation

class InMemoryFeatureChecker implements FeatureChecker
{
    private array $features;

    public function __construct(array $features = [])
    {
        $this->features = $features;
    }

    public function isEnabled(string $feature): bool
    {
        return $this->features[$feature] ?? false;
    }
}

If using Symfony, we can use Service Container to set that feature flags in a yml file when injecting the FeatureChecker in our code:

First, we should register our service:

services:
    InMemoryFeatureChecker:
        public: true
        arguments:
            - '%features%'

Then, using Service Container parameters we set the argument:

parameters:
    features:
        {
            foo: false,
            bar: true
        }

Example

Let's imagine following situation: you have an endpoint that shouldn't be active yet, but it is already implemented:

class SomeController
{
    private FeatureChecker $featureChecker;

    public function __construct(FeatureChecker $featureChecker) 
    {
        $this->featureChecker = $featureChecker;
    }

    public function __invoke(Request $request): JsonResponse
    {
        if (false === $this->featureChecker->isEnabled('foo')) {
            // throw exception to exit endpoint
        }
    }
}

Conclusion

Having the interface, you can implement it as better fits to your requirements (from yml files, from redis, mysql...).

Using feature flags, you have a tool to enable / disable easily features of your application.

Our approach has been really basic, but can be extended containing more info about user, quota usage, timestamp to be available from specific moment...