&lt;?php

class LivingThing{}

class Animal extends LivingThing {}

class Cat extends Animal 
{
    public function __construct(
        public string $name,
        public bool $needToBeBrushed = true,
        public bool $needClawsCutting = true,
        public bool $needToBeFed = true
    ){}
}

interface AnimalShelter
{
    public function adopt(string $name): Animal;
}

class CatShelter implements AnimalShelter
{
    public function adopt(string $name): Cat
    {
        return new Cat($name);
    }
}

class BetterCatShelter implements AnimalShelter
{
    // The decorated instance is given
    public function __construct(private AnimalShelter $decorated)
    {}
     
    public function adopt(string $name): Cat
    {
        // We use the initial behavior of the decorated instance
        $cat = $this->decorated->adopt($name);
        
        // As well as an additional behavior
        $this->groom($cat);
        
        return $cat;
    }
     
    private function groom(Cat $cat)
    {
        $cat->needToBeBrushed = false;
        $cat->needClawsCutting = false;
        $cat->needToBeFed = false;
    }
}

class Me
{
    private Cat $cat;
     
    // Since the decorator has the same interface, 
    // I don't have to change anything in this class to use either
    public function getACatFromShelter(AnimalShelter $shelter, string $catName)
    {
        $this->cat = $shelter->adopt($catName);
    }
     
    public function checkCatStatus(): string
    {
        if (!$this->cat->needToBeBrushed &amp;&amp; !$this->cat->needClawsCutting &amp;&amp; !$this->cat->needToBeFed) {
            return "All is well for {$this->cat->name}.";
        }
        
        return "Wow... {$this->cat->name} needs attention!";
    }
}

$me = new Me();
$catShelter = new CatShelter();

$me->getACatFromShelter($catShelter, 'Cripper');
echo $me->checkCatStatus(). PHP_EOL;

$betterCatShelter = new BetterCatShelter($catShelter);
$me->getACatFromShelter($betterCatShelter, 'Jinjer');

echo $me->checkCatStatus(). PHP_EOL;

Applying the pattern with Symfony services


&lt;?php

// src/Mailer/LoggingMailer.php
namespace App\Mailer;

// ...
use Symfony\Component\DependencyInjection\Attribute\AsDecorator;

#[AsDecorator(decorates: Mailer::class)]
class LoggingMailer implements MailerInterface
{
<meta charset="utf-8"> // ...
}

&lt;?php

// ...

#[AsDecorator(
<meta charset="utf-8"> decorates: Mailer::class,
<meta charset="utf-8"> priority: 10,
<meta charset="utf-8"> onInvalid: ContainerInterface::IGNORE_ON_INVALID_REFERENCE,
)]
class LoggingMailer implements MailerInterface
{
<meta charset="utf-8"> // ...
}

&lt;?php
 
// ...
use Symfony\Component\DependencyInjection\Attribute\AsDecorator;
use Symfony\Component\DependencyInjection\Attribute\MapDecorated;

#[AsDecorator(decorates: Mailer::class)]
class LoggingMailer implements MailerInterface
{
    public function __construct(#[MapDecorated] &lt;meta charset="utf-8">MailerInterface $originalMailer)
    {
    	// ...
    }

    // ...
}

&lt;?php

class CrackersBox 
{
    private array $authorizedFlavours = ['bacon', 'cheese', 'onion cream', 'garlic and herbs'];
    protected array $crackers = [];
    
    public function getCracker()
    {
        if (empty($this->crackers)) {
            throw new RuntimeException('empty box!');
        }
        
        return array_shift($this->crackers);
    }
    
    public function insertCrackers(array $crackers) 
    {
        if (!empty($this->crackers)) {
            throw new RuntimeException('Finish what is left first!');
        }
        
        $this->crackers = array_filter($crackers, fn ($cracker) => in_array($cracker, $this->authorizedFlavours));
    }
}


$crackersBox = new CrackersBox();
$crackersBox->insertCrackers(['bacon', 'cheese', 'onion cream', 'garlic and herbs']);

echo $crackersBox->getCracker().PHP_EOL; // bacon
echo $crackersBox->getCracker().PHP_EOL; // cheese, no barbecue.

&lt;?php

class CrackersBox 
{
 protected array $authorizedFlavours = ['bacon', 'cheese', 'onion cream', 'garlic and herbs'];
 protected array $crackers = [];
 
 public function getCracker()
 {
 if (empty($this->crackers)) {
 throw new RuntimeException('empty box!');
 }
 
 return array_shift($this->crackers);
 }
 
 public function insertCrackers(array $<meta charset="utf-8">crackers) 
 {
 if (!empty($this->crackers)) {
 throw new RuntimeException('We finish the box first!');
 }
 
 $this->crackers = array_filter($crackers, fn ($cracker) => in_array($cracker, $this->authorizedFlavours));
 }
}

class CrackersBoxSortingCheese extends CrackersBox 
{
 public function getCracker()
 {
 while ('cheese' === $cracker = parent::getCracker()){
 $this->crackers[] = $cracker;
 }
 
 return $cracker;
 }
}


$crackersBox = new CrackersBoxSortingCheese();
$crackersBox->insertCrackers(['bacon', 'cheese', 'onion cream', 'garlic and herbs']);
echo $crackersBox->getCracker().PHP_EOL; // bacon
echo $crackersBox->getCracker().PHP_EOL; // onion cream... Phew, no cheese or barbecue

Description of the Liskov Substitution Principle


&lt;?php

interface LivingThingInterface {}
interface AnimalInterface extends LivingThingInterface {}

interface DogInterface extends AnimalInterface {}
interface PlantInterface extends LivingThingInterface {}


class Dog implements DogInterface {}

class Plant implements PlantInterface {}

class Pet
{
	public function __construct(AnimalInterface $animal) {}
}

class PetDog extends Pet
{
 	// Works
	public function __construct(DogInterface $dog)
	{
 		parent::__construct($dog);
	}
}

class PlantPet extends Pet
{
 	// Does not work
	public function __construct(PlantInterface $plant)
	{
 		parent::__construct($plant);
	}
}

&lt;?php

class LivingThing{}

class Plant extends LivingThing {}
class Animal extends LivingThing {}

class Cat extends Animal {}

interface AnimalShelter
{
	public function adopt(string $name): Animal;
}

class CatShelter implements AnimalShelter
{
 	// Works
	public function adopt(string $name): Cat
	{
 		return new Cat($name);
	}
}

class PlantShelter implements AnimalShelter
{
 	// Does not work
	public function adopt(string $name): Plant
	{
 		return new Plant($name);
	}
}

Pre-reading note: if you are unfamiliar with any of the terms, pause your reading and check their meaning before continuing!



In <a href="https://api-platform.com/" target="_blank" rel="noreferrer noopener">API Platform</a>, but also in <a href="https://les-tilleuls.coop/technologies/symfony" target="_blank" rel="noreferrer noopener">Symfony</a> &nbsp;— and in a lot of softwares &nbsp;— &nbsp;it is often recommended to &#8220;decorate&#8221; to extend third-party code. In API Platform, we are asked to decorate providers, processors, listeners, resolvers, factories…&nbsp; For an experienced dev, this is trivial. But if you are new to the term, it is not so obvious.



Before discussing the pattern, we need to understand the reasons for its existence. To do this, we must define the difference (in OOP) between composition and inheritance.



<h2>Inheritance</h2>



Inheritance is one of the four major concepts associated with object-oriented programming. It includes abstraction, encapsulation, inheritance and polymorphism. Inheritance allows us to acquire properties and methods from the base class in the derived (or child) class. Derived classes usually have a (logical) relationship with the base class.



<h3>Benefits of Inheritance</h3>



<ul>
<li>Inheritance allows code reuse, to easily inherit features from the parent class without copying the code.</li>



<li>It provides a clear hierarchical structure that allows us to break down a model into a simple, easily digestible structure.</li>
</ul>



<h3>Disadvantages of inheritance</h3>



<ul>
<li>Inherited functions are slower than normal functions (without mentioning any specific programming language).</li>



<li>All variables and methods of the base class are inherited even if they are not used, this causes an unnecessary surplus.</li>



<li>Small changes can affect all derived classes in unexpected ways due to tight coupling.</li>



<li>Inheritance has a structure defined at compile time: we cannot change anything in the higher classes when &#8220;distributing&#8221; public or protected methods and properties to derived classes. The details of the parent class are exposed to the child class and this breaks the fundamental concept of encapsulation (i.e. &#8220;hiding&#8221;, &#8220;keeping private&#8221; properties and methods, to control their contents and actions).</li>
</ul>



To make an analogy, if I put Crackers on the table for each person with 1 Cracker per person. Without supervision, after 2 or 3 greedy people, there is no more for the others. Then I put the Crackers in a dispenser (it would be a class) which is in charge of checking that only one is distributed to each person. No one can take one directly. I define an accessor `getCracker`. Once empty however, I can&#8217;t renew the stock. So I also define an `insertCrackers` mutator. Is it enough? No! I just allowed adding barbecue Cracker! Tragedy, they are not good! So my mutator will also be responsible for controlling the quality of the inserted Crackers.





We have properly protected the access and addition of Crackers!



If an implementation of a class is perfect from an encapsulation point of view, and if changes are applied on this class, no changes will be necessary in the classes that inherit from it. Only in reality, as soon as I extend the Crackers box, my new class will have knowledge of all the public and protected properties and methods.



Let&#8217;s just say I&#8217;m not in the mood for Cheese Crackers today and I want to sort out:





Let&#8217;s imagine that the brand that distributes these crackers decides to replace the cheese range with 3 variations: beaufort, comté and goat. When I update my `CrackersBox`, I will have to modify my `CrackersBoxSortingCheese`: the inheritance has broken the encapsulation contract.



<h2>Composition</h2>



In the composition, one of the classes has one or more instances of other classes often obtained by passing them to the constructor.



<h3>Advantages of the composition</h3>



<ul>
<li>Dependencies are less compared to inheritance, the idea being to rely mainly on typed arguments with the help of interfaces to be as versatile and resilient as possible in the future.</li>



<li>The objects are defined at runtime, they do not have the possibility to access the protected data of another object: this allows to maintain the encapsulation.</li>
</ul>



<h3>Disadvantages of the composition</h3>



<ul>
<li>It requires more time and produces more verbose code.</li>



<li>The system is dependent on the interrelation between the objects.</li>



<li>A good breakdown to keep flexibility while ensuring the scalability of the code without having to make a deep restructuring is difficult: it is necessary to spend some time upstream to study the possibilities of structures, design pattern, to make the optimal choice.</li>
</ul>



<h2>Why choose composition over inheritance</h2>



Composition is an object-oriented programming concept that stipulates that classes must have <a href="https://fr.wikipedia.org/wiki/Polymorphisme_(informatique)" target="_blank" rel="noreferrer noopener">polymorphic</a> behavior (we are talking about method overloading here, which is not possible in PHP for example). This makes the whole thing more flexible, easier to maintain despite a larger code at the beginning. This is the reason for the saying &#8220;<a href="https://en.wikipedia.org/wiki/Composition_over_inheritance" target="_blank" rel="noreferrer noopener">Favor object composition over class inheritance</a>&#8220;.



Inheritance is a powerful tool. If used well, it can make your code compact, easy to read and fast to develop, but there are many pitfalls a person can easily fall into. Small changes can have disastrous consequences as seen above. That&#8217;s why, as a rule, we opt for composition instead.



<h2>When to inherit or not?</h2>



Let&#8217;s look at some OOP typing rules and the limits they impose. With these in mind, you will be able to identify situations where inheriting is not a good solution.



Do you know Barbara Liskov? She produced a publication called &#8220;A behavioral notion of subtyping&#8221; where she formalized the Liskov Substitution Principle, one of the <a href="https://fr.wikipedia.org/wiki/SOLID_(informatique)" target="_blank" rel="noreferrer noopener">SOLID</a> principles. I encourage you to study these principles (and <a href="https://fr.wikipedia.org/wiki/Loi_de_D%C3%A9m%C3%A9ter" target="_blank" rel="noreferrer noopener">Demeter&#8217;s Law</a>).



<h3>Description of the Liskov Substitution Principle</h3>



If S is a subtype of T, then objects of type T in a program can be replaced by objects of type S without altering any properties of that program.



Liskov&#8217;s substitution principle imposes certain requirements on method signatures in OOP languages. Among them, two notions that we will detail:



<ul>
<li>Respecting the contravariance of method parameter types in the subtype.</li>



<li>Respecting the covariance of the return types of the methods in the subtype.</li>
</ul>



<h3>Covariance and Contravariance</h3>



Many programming languages support subtyping. For example, if the type Cat is a subtype of Animal, an element of type Cat should be accepted wherever an element of type Animal is used.



Variance refers to how subtyping between more complex types relates to subtyping between their components. For example, how should a list of cats identify itself as a list of animals? Or how should a function that returns a cat identify as a function that returns an animal? These sentences are complex, and nothing beats a hands-on example to get the hang of the rule.



<h4>Example of contravariance in PHP</h4>





DogInterface inherits from AnimalInterface, the inheritance tolerates this change of type, it is the contravariance. S subtype of T -&gt; S being DogInterface and T being AnimalInterface.



PlantInterface inherits from LivingThingInterface, just like Animal. However PlantInterface is not a subtype of AnimalInterface, it is a subtype of LivingThingInterface.



Let&#8217;s consider it as a cousin. Inheritance will refuse this type change.



An example of covariance in PHP





Cat inherits from Animal, the inheritance tolerates this change of type, it is the contravariance. S subtype of T -&gt; S being Cat and T being Animal.



Plant inherits from LivingThingInterface, just like Animal. However Plant is not a subtype of Animal. It is a subtype of LivingThing.



Consider it a cousin. Inheritance will refuse this change of type.



Note that by the obviousness of the names used, it seems strange to have classified Plant under Animal, but it is not always so obvious. A better structure would have been to have everything derived from LivingThing.



Also, new exceptions should not be thrown by methods of the subtype, unless they are subtypes of exceptions thrown by methods of the supertype. You are beginning to see the limits of inheritance!



There comes a point in our structures where these relationships conflict with what we want to accomplish. So, rather than inheriting to add behavior, it becomes clearer by creating classes that do just what is desired and injecting them into classes that need that behavior. As a bonus, these classes can be used more easily.



Composition makes a lot more sense, all right. And what about the decoration?



The pattern



Let&#8217;s say we have used composition in our code. Among the SOLID principles is also the O for Open/Closed Principle. This principle states: that software entities (classes, modules, functions, etc.) should be open to extension, but closed to modification. That is, such an entity can allow its behavior to be extended without changing its source code.



How to add behavior to a class, but without touching its interface and signatures, without adding new methods? It is possible to inherit and overload, but we don&#8217;t want to fall back into the limitations we saw above. So we compose. We compose by decorating!



A decorator is a class. It is a class that exposes the same interface(s) as the class it is decorating, that it wants to extend. This is not enough of course, to complete the decoration, it will be necessary to pass an instance of the decorated class to the class which decorates it, often via its constructor. The most common image to visualize this operation is that of Russian dolls nesting in each other. This is also known as onion architecture.



An example with PHP





Don&#8217;t hesitate to play with this example, to mess with it to understand the mechanics. For example, have fun adding a CollarOptionCatShelter that puts a collar on the cat when you pay more.



And try to decorate CatShelter, and/or BetterCatShelter.



<h3>Applying the pattern with Symfony services</h3>



In Symfony, all classes registered as services are decoratable. In version 6.1 of the framework, here is how to do it (taken from the documentation: <a href="https://symfony.com/blog/new-in-symfony-6-1-service-decoration-attributes" target="_blank" rel="noreferrer noopener">https://symfony.com/blog/new-in-symfony-6-1-service-decoration-attributes</a>). You can also refer to our cooperator Robin&#8217;s talk: <a href="https://slides.com/chalasr/symfonybc-promise-demystifed/" target="_blank" rel="noreferrer noopener">https://slides.com/chalasr/symfonybc-promise-demystifed/</a>.



Consider the common case where you want to decorate a service (e.g. Mailer) with a new service that adds logging capabilities to it (e.g. LoggingMailer). Here&#8217;s how you can set up the decoration with PHP attributes: Both classes should implement a common interface. Here MailerInterface.





The <code>#[AsDecorator]</code> attribute supports any additional options you may need:





If you need to access the decorated service from within the decorator service, add the <code>#[MapDecorated]</code> attribute to one of the service constructor arguments:





<blockquote class="wp-block-quote">
Be careful not to decorate a service that is used as an Alias in Symfony, to avoid looking for reasons why the code doesn&#8217;t work. Symfony&#8217;s dependency injection does not yet support Alias decoration.




<cite>From Baptiste, Antoine, Vincent, Robin, Myself&#8230; (and all those who have suffered from it)</cite></blockquote>



I hope this concept is a bit clearer for you now. For your personal monitoring, don&#8217;t hesitate to <a href="https://symfony.com/doc/current/service_container/service_decoration.html" target="_blank" rel="noreferrer noopener">check this Symfony</a> post on the different ways to decorate a service. 



Enjoy your code!

Mastering the decorator pattern

Dive into a tutorial about the decorator pattern and its specificities with our cooperator Grégoire Hébert.

Mastering the decorator pattern | Les-Tilleuls.coop

Accueil

Les-Tilleuls.coop

https://secure.gravatar.com/avatar/b473bd9d058c922e08d57f39a4a861db?s=96&d=mm&r=g

Grégoire Hébert

The second edition of <a href="https://api-platform.com/con/2022/" target="_blank" rel="noreferrer noopener">API Platform Conference</a> is around the corner! Join us on Thursday 15 and Friday 16 September in Lille and online. Two stages are scheduled in French and in English. Both of them will be broadcasted live on Livestorm. 



<h2>An intensive week of knowledge sharing </h2>



Let&#8217;s see together <a href="https://api-platform.com/con/2022/" target="_blank" rel="noreferrer noopener">a sneak peek of the conference schedule!</a> 



<ul><li><a href="https://api-platform.com/con/2022/conferences/php-websockets-or-how-to-communicate-with-clients-in-real-time/" target="_blank" rel="noreferrer noopener">Pauline Vos</a> will speak about&nbsp;PHP Websockets</li><li><a href="https://api-platform.com/con/2022/conferences/dilemmas-and-decisions-what-we-ve-learned-designing-the-new-sylius-api/" target="_blank" rel="noreferrer noopener">Lukasz Chrusciel</a> will share news from Sylius&#8217; new API</li><li><a href="https://api-platform.com/con/2022/conferences/domain-driven-design-with-api-platform-3/" target="_blank" rel="noreferrer noopener">Robin Chalas and Mathias Arlaud</a> will speak about DDD with API Platform 3</li><li><a href="https://api-platform.com/con/2022/conferences/gerer-les-operations-sequentielles-avec-REST/" target="_blank" rel="noreferrer noopener">Grégoire Hébert</a> will show you how to manage sequential operations with REST&nbsp;</li><li><a href="https://api-platform.com/con/2022/conferences/building-schema-first-event-driven-architectures-with-async-api/" target="_blank" rel="noreferrer noopener">Fran Mendez</a> will present schema-first event-driven architectures with AsyncAPI</li><li><a href="https://api-platform.com/con/2022/conferences/API-platform-au-quotidien-dans-une-entreprise-e-commerce-et-logistique/" target="_blank" rel="noreferrer noopener">Kévin Verschaeve and Clément Sanchez</a> will show how API Platform works in the daily life of an e-commerce and logistics company</li><li><a href="https://api-platform.com/con/2022/conferences/decentralizaion-query-apis-and-other-myths/" target="_blank" rel="noreferrer noopener">Ruben Verborgh</a> will speak about decentralization, query APIs and other myths</li><li><a href="https://api-platform.com/con/2022/conferences/la-revue-de-code-est-un-art/" target="_blank" rel="noreferrer noopener">Smaïne Millianni</a> will present a talk about code review</li><li><a href="https://api-platform.com/con/2022/conferences/fighting-impostor-syndrome-a-pratical-handbook/" target="_blank" rel="noreferrer noopener">Marine Gandy</a> will talk about impostor syndrome</li><li><a href="https://api-platform.com/con/2022/conferences/what-s-new-in-caddy-the-webserver-of-api-platform/" target="_blank" rel="noreferrer noopener">Francis Lavoie</a> will show you what&#8217;s new in Caddy, API Platform&#8217;s webserver</li><li><a href="https://api-platform.com/con/2022/conferences/webauthn-se-debarrasser-des-mots-de-passe-definitivement/">Florent Morselli</a> will share thoughts about&nbsp;Webauthn</li></ul>



More speakers are announced on <a href="https://api-platform.com/con/2022/schedule" target="_blank" rel="noreferrer noopener">our website</a>!



Interested in getting trained about API Platform? <a href="https://api-platform.com/con/2022/schedule" target="_blank" rel="noreferrer noopener">Two workshops are also available</a>:



<ul><li>Tuesday 13/09: <a href="https://api-platform.com/con/2022/conferences/designing-and-building-an-api-first-project-with-API-Platform-3/" target="_blank" rel="noreferrer noopener">Design and development of a 1st API project with API Platform 3,</a> with <a href="https://twitter.com/dunglas" target="_blank" rel="noreferrer noopener">Kévin Dunglas</a> and <a href="https://twitter.com/s0yuka" target="_blank" rel="noreferrer noopener">Antoine Bluchet</a></li><li>Wednesday 14/09: <a href="https://api-platform.com/con/2022/conferences/workshop-domain-driven-design-with-API-Platform-3/" target="_blank" rel="noreferrer noopener">Domain Driven Design with API Platform 3</a>, with <a href="https://twitter.com/chalas_r" target="_blank" rel="noreferrer noopener">Robin Chalas</a> and <a href="https://twitter.com/matarld" target="_blank" rel="noreferrer noopener">Mathias Arlaud</a></li></ul>



When you register to the on-site conference, you can also join our <a href="https://api-platform.com/con/2022/conferences/API-platform-3-hack-day/" target="_blank" rel="noreferrer noopener">hackday</a> planned on Saturday 17/09. It&#8217;s free and it will be hosted by Kévin Dunglas and Antoine Bluchet in our office.



Moreover, we also remind you that all tickets are free for student or job seekers. <a href="mailto:events@les-tilleuls.coop" target="_blank" rel="noreferrer noopener">Contact our team</a> to get your voucher.



<h2>Thanks to our partners</h2>



This event would not have been possible without our partners support! Many thanks to <a href="https://www.francetelevisions.fr/" target="_blank" rel="noreferrer noopener nofollow">France Télévisions</a>, <a href="https://sensiolabs.com/fr/" target="_blank" rel="noreferrer noopener nofollow">Sensiolabs</a>, <a href="https://www.alicesgarden.fr/" target="_blank" rel="noreferrer noopener nofollow">Alice&#8217;s Garden</a>, <a href="https://link-value.fr/" target="_blank" rel="noreferrer noopener nofollow">Linkvalue</a>, <a href="https://platform.sh/" target="_blank" rel="noreferrer noopener nofollow">Platform.sh</a>, <a href="https://www.apimatic.io/" target="_blank" rel="noreferrer noopener nofollow">APImatic</a> and <a href="https://fairness.coop/" target="_blank" rel="noreferrer noopener nofollow">Fairness</a> for contributing to the organization of this event! Want to be a partner? Some slots are still available: <a href="mailto:events@les-tilleuls.coop" target="_blank" rel="noreferrer noopener">contact us to get the sponsorship brochure</a>. 







We are really excited to meet you both online and in Lille for <a href="https://les-tilleuls.coop/en/blog/api-platform-conference-2021-a-successful-edition" target="_blank" rel="noreferrer noopener">this second edition</a>! Still not registered? <a href="https://api-platform.com/con/2021/#pricing" target="_blank" rel="noreferrer noopener">Late bird tickets are still available.</a> See you soon!

API Platform Conference 2022: join us and meet the best API experts!

Only one month left until API Platform Conference 2022. Join us and let's see together a sneak peek of the entire schedule!

Join API Platform Conference

https://secure.gravatar.com/avatar/54fb8ea2a1a36c3b9ef44f25bf976b48?s=96&d=mm&r=g

Cécile Hamerel

SIGNATURE_KEY=XAR5vxusewjY9KJ2w8apxVzVq5EPtl

&lt;?php
declare(strict_types=1);

namespace AppController;

use CoopTilleulsUrlSignerBundleUrlSignerUrlSignerInterface;
use SymfonyBundleFrameworkBundleControllerAbstractController;
use SymfonyComponentHttpFoundationJsonResponse;
use SymfonyComponentHttpFoundationResponse;
use SymfonyComponentRoutingAnnotationRoute;

class VideoController extends AbstractController
{
    public function __construct(
        private UrlSignerInterface $urlSigner,
    )
    {
    }

    #[Route('/videos/{id}/signed-url', methods: ['GET'])]
    public function newSignedUrl(string $id): Response
    {
        $this->denyAccessUnlessGranted('ROLE_USER');
        return new JsonResponse(['url' => $this->generateSignedUrl($id)]);
    }

    private function generateSignedUrl(string $id): string
    {
        $url = $this->generateUrl('download_video', ['id' => $id]);
        // Will expire after 10 seconds.
        $expiration = (new DateTime('now'))->add(new DateInterval('PT10S'));
        return $this->urlSigner->sign($url, $expiration);
    }
}

&lt;?php
declare(strict_types=1);

namespace AppController;

use SymfonyBundleFrameworkBundleControllerAbstractController;
use SymfonyComponentHttpFoundationBinaryFileResponse;
use SymfonyComponentHttpFoundationResponse;
use SymfonyComponentRoutingAnnotationRoute;

class VideoController extends AbstractController
{
    #[Route('/videos/{id}/download', name: 'download_video', defaults: ['_signed' => true], methods: ['GET'])]
    public function download(string $id): Response
    {
        // Get the file.        return new BinaryFileResponse();
    }
}

&lt;?php
declare(strict_types=1);

namespace AppEntity;

use ApiPlatformCoreAnnotationApiResource;
use AppControllerCreateSignedUrlVideoAction;
use AppControllerDownloadVideoAction;

#[ApiResource(
    itemOperations: [
    'get',
    'delete',
    'put',
    'signed_url' => [
        'security' => "is_granted('ROLE_USER')",
        'method' => 'GET',
        'path' => '/videos/{id}/signed-url',
        'controller' => CreateSignedUrlVideoAction::class,
    ],
    'download' => [
        'method' => 'GET',
        'path' => '/videos/{id}/download',
        'controller' => DownloadVideoAction::class,
        'defaults' => ['_signed' => true],
        'formats' => ['binary'],
    ],
],
)]
class Video
{
    // Properties, getters, setters
}

A signed URL is a URL containing authentication information directly in its query string. It allows a non-authenticated user to access protected resources or routes, for a limited time.



Signing a URL can be very useful in a stateless application. There are two main use cases for using them:



<ul><li>allowing an external user to access a resource otherwise not accessible without being authenticated,</li><li>downloading a file with the browser without using Ajax (without a fetch() sending the authentication information).</li></ul>



The latter is the most common use case. Let&#8217;s take an example: we have created a personal cloud where users can store their files. This application is built with a SPA for the front and communicates with a secured API by using a JWT token. Jean has uploaded a big video showing a live coding session of a nice feature in API Platform, and he wants to download it to watch it again.



The first reflex to implement this download feature in the SPA would be to do something like this:





This method has a lot of drawbacks:



<ul><li>The browser download interface is used only after the file has been downloaded. We need to show Jean that a download is ongoing, for instance by adding a spinner somewhere. Jean cannot pause or cancel the download.</li><li>The downloaded file is stored in memory until it is complete, which can cause performance issues if the file is too big.</li></ul>



To solve this, you could use the JWT token in the query string to download the video. Yes, <a href="https://tools.ietf.org/html/rfc6750#section-2.3" target="_blank" rel="noopener">it is possible</a>, but it is a bad idea:



<ul><li>A JWT token can be big. Big enough to exceed the URL length limit.</li><li>You don&#8217;t want the JWT tokens to show in your server logs. This is a security breach in your application that would facilitate a <a href="https://en.wikipedia.org/wiki/Session_hijacking">session hijacking</a> kind of attack.</li></ul>



That&#8217;s why in this case, it is preferable to use a signed URL, like this:





That&#8217;s way better: fetch() is only used to get the signed URL with authentication, signed URL which is then used directly to download the file. And of course you can also use this signed URL generation for adding a sharing feature, for instance if Jean wants his friends to download the video without being authenticated.



Laravel includes the <a href="https://laravel.com/docs/5.6/urls#signed-urls" target="_blank" rel="noopener">generation of signed URLs</a> since its version 5.6, but there was no easy way to do it in Symfony.



With the <a href="https://github.com/coopTilleuls/UrlSignerBundle" target="_blank" rel="noopener">UrlSignerBundle</a>, it has now been fixed!



So, how do we use it?



<h3>Usage</h3>



First step, install the bundle. By using Symfony Flex, it&#8217;s very straightforward:





Thanks to Flex, all the configuration has been done (see the config/packages/url_signer.yaml file).



Change the signature in the .env (or the .env.local) file:





Everything is ready to start using the bundle and to create your signed URL!



For instance in a controller, we will inject the UrlSignerInterface service and then use it to create a signed URL which will be returned in the JSON response of the /videos/{id}/signed-url route:





We can now retrieve a signed URL from the /videos/{id}/signed-url route. The signed URL will look like this:



/videos/d35e0296-7b19-42be-82f2-789213229f36/download?expires=1611316656&amp;signature=82f6958bd5c96fda58b7a55ade7f651fadb51e12171d58ed271e744bcc7c85c3



As you can see, the signed URL has two parameters:



<ul><li>expires which contains the timestamp of the expiration date: the URL is no longer valid after this date.</li><li>signature which is in fact the hash of the path, the expiration parameter and the secret.</li></ul>



The last step is to validate it when the route corresponding to the URL is accessed. We reuse our VideoController:





As you can see, we just added a _signed <a href="https://symfony.com/doc/current/routing.html#extra-parameters" target="_blank" rel="noopener">extra parameter</a> to the route. It is this parameter that activates the signature validation when a request hits the route.



And that&#8217;s it! If you access the download route without a signature or with an invalid signature, you will get a 403 response.



If you want to use signed URLs in API Platform, how do you do it? Well it&#8217;s even easier!



It will look like this:





The signed_url operation creates the signed URL (and has authentication). The download operation allows users to download the video using the signed URL, with the extra _signed parameter that enables validation of the signed URL. The corresponding controllers are very similar to the previous VideoController controller.



<h3>Features</h3>



There are of course other features in the bundle:



<ul><li>The algorithm to sign the URL can be changed. By default, it is SHA-256.</li><li>You can easily create your own Signer: extend the AbstractUrlSigner class, and you are done (you can use it by modifying the configuration in the config/packages/url_signer.yaml file)!</li><li>The time before expiration is customizable (by default 24h).</li><li>Parameter names in the signed URL are customizable.</li></ul>



<h3>How does it work?</h3>



Internally the bundle uses the library <a href="https://github.com/spatie/url-signer" target="_blank" rel="noopener">spatie/url-signer</a>.



Each Signer corresponds to an algorithm and extends an abstract class (AbstractUrlSigner) based on the Spatie URL signer. In a dedicated compiler pass, the configured signer is automatically aliased to the UrlSignerInterface.



For the validation, the method is really simple: an event listener is used. Each time a request is performed, it checks if the route has the _signed parameter. When it does, the signature is validated by the URL signer.



The bundle is very well tested: it has unit tests with PHPUnit and Prophecy and functional tests with Behat and the SymfonyExtension. The tests cover 100% of the code, and even better, the mutation score, calculated with the mutation testing framework <a href="https://infection.github.io" target="_blank" rel="noopener">Infection</a> is also 100%.



And finally, the type coverage is 100% too, calculated by Psalm (PHPStan is also used).



If you need signed URLs in a Symfony or API Platform project, this bundle is for you! Feel free to test it, tell us what you think about it, and why not contribute to its development on GitHub: <a href="https://github.com/coopTilleuls/UrlSignerBundle" target="_blank" rel="noopener">https://github.com/coopTilleuls/UrlSignerBundle</a>.

UrlSignerBundle, create and validate signed URLs with Symfony

A signed URL is a URL containing authentication information directly in its query string. It allows a non-authenticated user to access protected resources or routes, for a limited time. Signing a URL can be very useful in a stateless application. There are two main use cases for using them: allowing an external user to access [&hellip;]

UrlSignerBundle, create and validate signed URLs with Symfony | Les-Tilleuls.coop

https://secure.gravatar.com/avatar/04b6d9886e782e0676c0d26063f77ac9?s=96&d=mm&r=g

What's new at Les-Tilleuls.coop ?

Mastering the decorator pattern

API Platform Conference 2022: join us and meet the best API experts!

UrlSignerBundle, create and validate signed URLs with Symfony