Forem: Adrien Roches

PHP : The fall of `array`

Adrien Roches — Thu, 23 Feb 2023 13:11:53 +0000

array is a very common type in PHP but is often overused.

I'll try to explain why you don't (almost) need to type hint array anymore !

The problems
First steps
Using Countable
Using ArrayAccess
Using Traversable
1. The hard way (implementing Iterator)
2. The easy way (implementing IteratorAggregate)
3. But what do I gain ?
Conclusion

The problems

Businness logic

Let's first talk about why we need a replacement to array.

When declaring a simple parameter like array $products we often need to apply some domain logic on it : groupByCategories, filterNonUnavailable, calculateTotalPrice, ... But where should we put all of these logic ? Often I see it repeated over multiple places in the code or in helper classes with naming or structure inconsistencies.
Memory consumption

Arrays are known to be memory intensive in PHP (see the tweet from Nikita Popov below).

Additionally, it cannot be generated on the fly (vs Generator's that we will discuss later).
// Detect dark theme var iframe = document.getElementById('tweet-847855830821109760-257'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=847855830821109760&theme=dark" }
ISP

It always provides 3 different features : Countable, Traversable, ArrayAccess which you may not always have a need for.
Keys must be string or int

When using an array you MUST use either a string or an int as key (⚠️ floats are automatically converted to int as well as numeric string).

Sometimes you may want to have a DateTimeImmutable as key or any objects. You even may want to have duplicated keys !
Pass by value

When you use an array variable to call a method or a function, PHP will actually duplicate that array everytime (pass by value). Object however are pass by reference.

First steps

If you've made it this far you might be afraid of all the refactoring it may take ! Let me reassure you first and then explain how we can improve from this. Here is a simple class that does exactly the same as array :

/** @extends ArrayIterator<string, Product> */
class ProductCollection extends ArrayIterator
{
    /**
      * @param array<string, Product> $products
      */
    public function __construct(array $products) 
    {
        parent::__construct($products);
    }
}

Now you can typehint ProductCollection $products everywhere without changing anything else. It can be used in all similar way as array and PHPStorm will know that $productCollection['someId'] will return a Product class.

EDIT : The object IS NOT compatible with array_* functions natively. You'll need to use iterator_to_array($productCollection) to apply it to an array_* function. Either that or create a method on your object that will use the internal value.

Seems enough right ? Well I said first step. Now let's see how and why we can improve a bit further.

Using `Countable`

This one is very light and is often used in combination with the other two. If you only need to check the number in your array you can simply says that your class is Countable like so :

class ProductCollection implements Countable
{
    public function count(): int
    {
        return count($this->products);
    }
}

This class on its own is not very useful. Let's dive into the other two.

Using `ArrayAccess`

Let's say that now you want to provide the same syntax as $productCollection[$productId] to access data BUT you want to provide an immutable-like array.

Here is an example:

/** @implements ArrayAccess<string, Product> */
class FrozenProductCollection implements ArrayAccess
{
    /**
      * @param array<string, Product> $products
      */
    public function __construct(private readonly array $products) 
    {
    }

    public function offsetExists(mixed $offset): bool
    {
        return array_key_exists($offset, $this->products);
    }

    public function offsetGet(mixed $offset): mixed
    {
        return $this->products[$offset];
    }

    public function offsetSet(mixed $offset, mixed $value): void
    {
        throw new Exception('Cannot add a product to a FrozenProductCollection');
    }

    public function offsetUnset(mixed $offset): void
    {
        throw new Exception('Cannot remove a product to a FrozenProductCollection');
    }
}

With this you can access data but you cannot remove or add new products to the Collection.

offsetExists(mixed $offset): bool : return true if entry at position $offset exists (used by isset, ??, ...
offsetGet(mixed $offset): mixed : return the entry associated to the offset.
offsetSet(mixed $offset, mixed $value): void : add / override an entry at the position $offset.
offsetUnset(mixed $offset): void : remove an entry at the position $offset

Note that all these methods use mixed for $offset. So yes you could have a logic to offsetGet a Product by a given ProductId object or if you have a ProductAlias or whatever you want.

You could even combine this with the basic class like so :

/** @extends ArrayIterator<string, Product> */
class ProductCollection extends ArrayIterator
{
    /**
      * @param array<string, Product> $products
      */
    public function __construct(array $products) 
    {
        parent::__construct($products);
    }
}

/** @implements ArrayAccess<string, Product> */
class FrozenProductCollection implements ArrayAccess
{
    public function __construct(
        private readonly ProductCollection $products,
    ) {
    }

    public function offsetExists(mixed $offset): bool
    {
        return array_key_exists($offset, $this->products);
    }

    public function offsetGet(mixed $offset): mixed
    {
        return $this->products[$offset];
    }

    public function offsetSet(mixed $offset, mixed $value): void
    {
        throw new Exception('Cannot add a product to a FrozenProductCollection');
    }

    public function offsetUnset(mixed $offset): void
    {
        throw new Exception('Cannot remove a product to a FrozenProductCollection');
    }
}

$productCollection = new FrozenProductCollection(new ProductCollection([
    '#123' => new Product(
        id: '#123',
        name: 't-shirt',
    ),
]));

$productCollection['#456'] = new Product(
    id: '#456',
    name: 'headband',
); // This is now forbidden

Decorator for the win 🎉 !

Using `Traversable`

PHP interface Traversable is used to define an object that can be iterated over (with foreach). array is Traversable but objects can too ! LEt's look how to implement it. You cannot implement Traversable directly (reserved for PHP) but you can either use Iterator or IteratorAggregate.

The hard way (implementing `Iterator`)

/** @implements Iterator<string, Product> */
class ProductCollection implements Iterator
{
    private int $cursorPosition = 0;

    /** @var array<string> */
    private readonly array $keys;

    /** @var array<Product> */
    private readonly array $products;

    /**
      * @param array<string, Product> $products
      */
    public function __construct(
        array $products
    ) {
        $this->keys = array_keys($products);
        $this->products = array_values($products);
    }

    public function rewind(): void
    {
        $this->cursorPosition = 0;
    }

    public function current(): Product
    {
        return $this->products[$this->cursorPosition];
    }

    public function key(): string
    {
        return $this->keys[$this->cursorPosition];
    }

    public function next(): void
    {
        ++$this->cursorPosition;
    }

    public function valid(): bool
    {
        return isset($this->products[$this->cursorPosition]);
    }
}

You can see that is a lot of code for something that does not provide yet anything better than array. Although this syntaxe may look the same accross any Collection it is actually a good way of implementing the PDO Generator technique. So do we avoid this much repeated code ?

The easy way (implementing `IteratorAggregate`)

Take a look at this class :

/** @implements IteratorAggregate<string, Product> */
class ProductCollection implements IteratorAggregate
{
    /**
      * @param array<string, Product> $products
      */
    public function __construct(
        private readonly array $products
    ) {
    }

    /** @return ArrayIterator<string, Product> */
    public function getIterator(): ArrayIterator
    {
        return new ArrayIterator($this->products);
    }
}

Both of these example produce the same result : you can iterate over a ProductCollection instance like so :

$productCollection = new ProductCollection([
    '#123' => new Product(
        id: '#123',
        name: 't-shirt',
    ),
]);

foreach ($productCollection as $product) {
    echo $product->id; // will print '#123'
}

But what do I gain ?

First of all you now a typed collection that you can explicitly typehint anywhere. Your collection herself holds the information about iteration whereas with array you had to typehint using phpdoc everywhere what does this array contains.

You also have access to a class so you can add any methods that you deemed usefull to this context.

As of this moment you do not have any PHP memory improvements because we are still using an array in our class. Let's improve this.

/** @implements IteratorAggregate<string, Product> */
class ProductCollection implements IteratorAggregate
{
    /**
      * @param iterable<string, Product> $products
      */
    public function __construct(
        private readonly iterable $products
    ) {
    }

    /** @return Generator<string, Product> */
    public function getIterator(): Generator
    {
        yield from $this->products;
    }
}

⚠️ Beware that this might be a non rewindable generator meaning that you can iterate over $this->products only once.

Now you can use it either with an object or an array. This object can be a generator (created using yield). Here is an example using doctrine that will iterate over every rows without loading all of them to memory at once :

class ProductRepository extends ServiceEntityRepository
{
    public function __construct(ManagerRegistry $registry)
    {
        parent::__construct($registry, Product::class);
    }

    public function streamAll(): ProductCollection
    {
        $qb = $this->createQueryBuilder('product');

        return new ProductCollection($qb->getQuery()->toIterable());
    }
}

There are a lot more to say about Iterator's. Depending on feedback on this post, I might go deeper in a follow-up article.

Conclusion

Using classes for what used to be provided by array allows you to :

more easily extend your code
keep business logic together
typehint precisely what you inject in a method or class
keep your static analysers happy !

Symfony : why I stopped using the AbstractController

Adrien Roches — Tue, 24 Jan 2023 09:35:48 +0000

A typical Controller in Symfony may look like this :

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class HelloController extends AbstractController
{
    #[Route(
        path: '/hello/{name}',
        name: 'app_hello',
        requirements: ['name' => '[a-zA-Z-]+'],
        methods: ['GET']
    )]
    public function index(string $name = 'Adrien'): Response
    {
        $form = $this->createForm(SomeFormType::class);

        return $this->render('hello.html.twig', [
            'name' => $name, 
            'form' => $form,
        ]);
    }
}

It is perfectly fine of course but there are a few things we can improve.

What are the dependencies ?

By calling $this->render(...), it hides what are the dependencies. Indeed we did not provide anything through the usual ways : __construct, setter, properties (See documentation)

So what are we using and how do I have access to it ?

Taking a look at the AbstractController::render(...) method here we can see it is using the twig service. But it is not declared as a dependency so how does it work ?

It is another feature called "Service Subscriber", which AFAIK is only used by controllers. Basically it is a "Service Locator" where the class defines itself which are its dependencies.

Besides twig there are (ATM) 9 additional dependencies declared this way which are (source) :

public static function getSubscribedServices(): array
{
    return [
        'router' => '?'.RouterInterface::class,
        'request_stack' => '?'.RequestStack::class,
        'http_kernel' => '?'.HttpKernelInterface::class,
        'serializer' => '?'.SerializerInterface::class,
        'security.authorization_checker' => '?'.AuthorizationCheckerInterface::class,
        'twig' => '?'.Environment::class,
        'form.factory' => '?'.FormFactoryInterface::class,
        'security.token_storage' => '?'.TokenStorageInterface::class,
        'security.csrf.token_manager' => '?'.CsrfTokenManagerInterface::class,
        'parameter_bag' => '?'.ContainerBagInterface::class,
    ];
}

It makes the dependencies very blurry IMO as we have to dig into the class to discover what is already accessible from the $this->container->get(...).

How does the `Request $request` work ?

My argument here could seem a bit off, but I found that a lot of symfony developers doesn't know anymore that to be able to reference the Request class within a controller method, you need your controller class to be tagged with controller.service_arguments.

Part of why I think people don't know that is because by extending the AbstractController + using autoconfigure: true it will automatically add it. I know it is supposed to help and it does. But if you understand that by leveling up your team on symfony core functionnalities, they will become more and more productive then they might miss this.

Same argument could be applied to any service that is "autoconfigured" but

In general it refers to an Interface instead of an Abstract class
It doesn't alter your class with unwanted / unneeded dependencies.

It hides what it really does

⚡️ Quizz : what changed in the render method in 6.2 ?

➡️➡️➡️ The way Form is handled.

Here is the explanation : normally if you need to pass on a form from a controller to a template (twig), then you learned to do it this way (prior to 6.2) :

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;

class HelloController extends AbstractController
{
    #[Route(
        path: '/hello/{name}',
        name: 'app_hello',
        requirements: ['name' => '[a-zA-Z-]+'],
        methods: ['GET']
    )]
    public function index(string $name = 'Adrien'): Response
    {
        $form = $this->createForm(SomeFormType::class);

        return $this->render('hello.html.twig', [
            'name' => $name, 
            'form' => $form->createView(),
        ]);
    }
}

now you can change it like so :

- 'form' => $form->createView(),
+ 'form' => $form,

Easier right ? But is it because twig changed the way it handles forms ? Not at all ! Taking a look at this code (source)

foreach ($parameters as $k => $v) {
    if ($v instanceof FormInterface) {
        $parameters[$k] = $v->createView();
    }
}

from the AbstractController it clearly shows that it iterates over all the parameters you gave to do it for you. Meaning that if you go from this AbstractController to a lighter one like I'll show later, then you have to change this yourself otherwise it won't work.

It may break your application

Maybe you already have built some simple HTTP API using return $this->json(...) ? But how does it work ? Take a look at the code (source)

protected function json(
    mixed $data,
    int $status = 200,
    array $headers = [],
    array $context = []
): JsonResponse {
    if ($this->container->has('serializer')) {
        $json = $this->container->get('serializer')->serialize($data, 'json', array_merge([
            'json_encode_options' => JsonResponse::DEFAULT_ENCODING_OPTIONS,
        ], $context));

        return new JsonResponse($json, $status, $headers, true);
    }

    return new JsonResponse($data, $status, $headers);
}

The issue is that if you didn't had the Serializer component installed then the encoding of your data will be handled by the JsonResponse class which does json_encode. But at the moment you install the Seralizer component then the behaviour changes and the output may differ as well.

What is the alternative ?

Here is what I propose :

-use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+use Symfony\Component\Form\FormFactoryInterface;
+use Twig\Environment;

-class HelloController extends AbstractController
+class HelloController
{
+     public function __construct(
+         private readonly Environment $twig,
+         private readonly FormFactoryInterface $formFactory,
+     ) {
+     }

    #[Route(
        path: '/hello/{name}',
        name: 'app_hello',
        requirements: ['name' => '[a-zA-Z-]+'],
        methods: ['GET']
    )]
    public function index(string $name = 'Adrien'): Response
    {
-        $form = $this->createForm(SomeFormType::class);
+        $form = $this->formFactory->create(SomeFormType::class);

-        return $this->render('hello.html.twig', [
+        return $this->twig->render('hello.html.twig', [
            'name' => $name, 
-            'form' => $form,
+            'form' => $form->createView(),
        ]);
    }
}

and of course don't forget to update your services.yaml configuration accordingly :

services:
    _defaults:
        autowire: true
        autoconfigure: true

    App\Controller\:
-        resource: '../src/Controller/'
+        resource: '../src/Controller/**/*Controller.php'
+        tags: [{ name: 'controller.service_arguments' }]

I don't think this alternative is more complicated than what symfony propose. Of course this was a very simple case. I recommend to always have a look at the AbstractController because there are also very useful tips like this one which sets the 422 status code if a form has been submitted but is not valid.

Conclusion

There is nothing wrong using the AbstractController if you are building a very simple app that doesn't require much maintenance.

But if you are building something that requires improved readability (== improved maintenance), you should consider moving away from the AbstractController to have explicit configurations.

Forem: Adrien Roches

PHP : The fall of `array`

Table of Contents

The problems

First steps

Using Countable

Using ArrayAccess

Using Traversable

The hard way (implementing Iterator)

The easy way (implementing IteratorAggregate)

But what do I gain ?

Conclusion

Symfony : why I stopped using the AbstractController

What are the dependencies ?

How does the Request $request work ?

It hides what it really does

It may break your application

What is the alternative ?

Conclusion

Using `Countable`

Using `ArrayAccess`

Using `Traversable`

The hard way (implementing `Iterator`)

The easy way (implementing `IteratorAggregate`)

How does the `Request $request` work ?