zrzut-ekranu-2016-09-20-o-19-57-58

I was working on a project in C# and ASP.NET MVC once. It was a long time ago. I can remember how happy I was. Earlier I was creating a project in PHP in the worst way: on an own framework. It was all old, shitty PHP. With big routing arrays, custom validation services, and ancient template engine, Smarty2.

When I started to create a project in ASP.NET I was astonished how many great features it has. One of them were annotations. That little pieces of code simplify developing and keep the code clean and readable. And short 😉

But unfortunately, the project came to an end. And the next one was again in PHP. I was really considering changing specialization and becoming .NET developer. But then, a miracle occurred…

The next project did not use our own, company framework. It used Symfony2 framework. Suddenly I saw, that PHP isn’t that bad, it has almost all features that stunned me in .NET! Yes, annotations as well 🙂

I can’t remember what were annotations used for in .NET. But I can tell you what they are used in Symfony (or in fact any PHP project – this is a standalone package).

@Route

The most used type of annotation is for routing. You can create routing in XML, YML, PHP or via annotations. All of them have pros and cons. The biggest advantage of annotations is readability and simplicity. All the code affecting actions is in one place. Look at the short example:

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;

// [...]

/**
 * @Route("/", name="blog_home")
 */
public function indexAction()
{
    // ...
}

And voila, the actions is alive and available to access! No additional file with routing needed and you always know where to find routing options for specific action.

@Security

Next type of useful annotations is security. Symfony provides a very handy way to manage access by user roles. You can check it inside action by this simple line:

$this->denyAccessUnlessGranted("ROLE_ADMIN");

But there is another way to do it – by using annotation @Security:

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Security;

// [...]

/**
 * @Security("is_granted('ROLE_ADMIN')")
 */
public function showAction(Post $post)
{
}

@Template

Third most used annotation is @Template. It allows you to specify a template for action, and thanks to that you must only return an array with parameters from an action. It may look like this:

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Template;

// [...]

/**
 * @Template("SensioBlogBundle:Post:show.html.twig")
 */
public function showAction($id)
{
    // get the Post
    $post = ...;
    return ['post' => $post];
}

Personally, I don’t like it and I’m avoiding to use it in my projects. I think, that if I must return some values either way then I prefer to return all information at once. Separating template from its parameters is a complication of the code.

Summary

And there are many more useful annotations available. In fact, you can create your own annotation as well. If you have some logic that you use often in actions then annotation may be something worth considering. There are many tutorials that help with writing an own annotation, you can try for example this one. I’ve seen them used for choosing the template from desktop/mobile, specifying Cron parameters for commands and redirecting to other actions if you don’t have permissions.

An annotation is only a tool, and if you have a good using for it – that’s great. Create some, and see how it helps you with creating good software.

Don’t forget to check out other PHPhyts!