converters.rst

@ParamConverter

Usage

The @ParamConverter annotation calls converters to convert request parameters to objects. These objects are stored as request attributes and so they can be injected as controller method arguments:

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Route;
use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;

/**
 * @Route("/blog/{id}")
 * @ParamConverter("post", class="SensioBlogBundle:Post")
 */
public function showAction(Post $post)
{
}

Several things happen under the hood:

• The converter tries to get a SensioBlogBundle:Post object from the request attributes (request attributes comes from route placeholders -- here id);
• If no Post object is found, a 404 Response is generated;
• If a Post object is found, a new post request attribute is defined (accessible via $request->attributes->get('post'));
• As for other request attributes, it is automatically injected in the controller when present in the method signature.

If you use type hinting as in the example above, you can even omit the @ParamConverter annotation altogether:

// automatic with method signature
public function showAction(Post $post)
{
}

You can disable the auto-conversion of type-hinted method arguments feature by setting the auto_convert flag to false:

# app/config/config.yml
sensio_framework_extra:
    request:
        converters: true
        auto_convert: false

<sensio-framework-extra:config>
    <request converters="true" auto-convert="true" />
</sensio-framework-extra:config>

You can also explicitly disable some converters by name:

# app/config/config.yml
sensio_framework_extra:
    request:
        converters: true
        disable: ['doctrine.orm', 'datetime']

<sensio-framework-extra:config>
    <request converters="true" disable="doctrine.orm,datetime" />
</sensio-framework-extra:config>

To detect which converter is run on a parameter the following process is run:

• If an explicit converter choice was made with @ParamConverter(converter="name") the converter with the given name is chosen.
• Otherwise all registered parameter converters are iterated by priority. The supports() method is invoked to check if a param converter can convert the request into the required parameter. If it returns true the param converter is invoked.

Built-in Converters

The bundle has two built-in converters, the Doctrine one and a DateTime converter.

Doctrine Converter

Converter Name: doctrine.orm

The Doctrine Converter attempts to convert request attributes to Doctrine entities fetched from the database. Several different approaches are possible:

1) Fetch Automatically

If your route wildcards match properties on your entity, then the converter will automatically fetch them:

/**
 * Fetch via primary key because {id} is in the route.
 *
 * @Route("/blog/{id}")
 */
public function showByPkAction(Post $post)
{
}

/**
 * Perform a findOneBy() where the slug property matches {slug}.
 *
 * @Route("/blog/{slug}")
 */
public function showAction(Post $post)
{
}

Automatic fetching works in these situations:

• If {id} is in your route, then this is used to fetch by primary key via the find() method.
• The converter will attempt to do a findOneBy() fetch by using all of the wildcards in your route that are actually properties on your entity (non-properties are ignored).

You can control this behavior by actually adding the @ParamConverter annotation and using the @ParamConverter options.

2) Fetch via an Expression

If automatic fetching doesn't work, another great option is to use an expression:

use Sensio\Bundle\FrameworkExtraBundle\Configuration\Entity;

/**
 * @Route("/blog/{post_id}")
 * @Entity("post", expr="repository.find(post_id)")
 */
public function showAction(Post $post)
{
}

Use the special @Entity annotation with an expr option to fetch the object by calling a method on your repository. The repository method will be your entity's Repository class and any route wildcards - like {post_id} are available as variables.

Tip

The @Entity annotation is a shortcut for using expr and has all the same options as @ParamConverter.

This can also be used to help resolve multiple arguments:

/**
 * @Route("/blog/{id}/comments/{comment_id}")
 * @Entity("comment", expr="repository.find(comment_id)")
 */
public function showAction(Post $post, Comment $comment)
{
}

In the example above, the $post parameter is handled automatically, but $comment is configured with the annotation since they cannot both follow the default convention.

DoctrineConverter Options

A number of options are available on the @ParamConverter or (@Entity) annotation to control behavior:

• id: If an id option is configured and matches a route parameter, then the converter will find by the primary key:

  /**
   * @Route("/blog/{post_id}")
   * @ParamConverter("post", options={"id" = "post_id"})
   */
  public function showPostAction(Post $post)
  {
  }

• mapping: Configures the properties and values to use with the findOneBy() method: the key is the route placeholder name and the value is the Doctrine property name:

  /**
   * @Route("/blog/{date}/{slug}/comments/{comment_slug}")
   * @ParamConverter("post", options={"mapping": {"date": "date", "slug": "slug"}})
   * @ParamConverter("comment", options={"mapping": {"comment_slug": "slug"}})
   */
  public function showCommentAction(Post $post, Comment $comment)
  {
  }

• exclude Configures the properties that should be used in the findOneBy() method by excluding one or more properties so that not all are used:

  /**
   * @Route("/blog/{date}/{slug}")
   * @ParamConverter("post", options={"exclude": {"date"}})
   */
  public function showAction(Post $post, \DateTime $date)
  {
  }

• strip_null If true, then when findOneBy() is used, any values that are null will not be used for the query.

• entity_manager By default, the Doctrine converter uses the default entity manager, but you can configure this:

  /**
   * @Route("/blog/{id}")
   * @ParamConverter("post", options={"entity_manager" = "foo"})
   */
  public function showAction(Post $post)
  {
  }

• evict_cache If true, forces Doctrine to always fetch the entity from the database instead of cache.

DateTime Converter

Converter Name: datetime

The datetime converter converts any route or request attribute into a datetime instance:

/**
 * @Route("/blog/archive/{start}/{end}")
 */
public function archiveAction(\DateTime $start, \DateTime $end)
{
}

By default any date format that can be parsed by the DateTime constructor is accepted. You can be stricter with input given through the options:

/**
 * @Route("/blog/archive/{start}/{end}")
 * @ParamConverter("start", options={"format": "Y-m-d"})
 * @ParamConverter("end", options={"format": "Y-m-d"})
 */
public function archiveAction(\DateTime $start, \DateTime $end)
{
}

A date in a wrong format like 2017-21-22 will return a 404.

Creating a Converter

All converters must implement the ParamConverterInterface:

namespace Sensio\Bundle\FrameworkExtraBundle\Request\ParamConverter;

use Sensio\Bundle\FrameworkExtraBundle\Configuration\ParamConverter;
use Symfony\Component\HttpFoundation\Request;

interface ParamConverterInterface
{
    function apply(Request $request, ParamConverter $configuration);

    function supports(ParamConverter $configuration);
}

The supports() method must return true when it is able to convert the given configuration (a ParamConverter instance).

The ParamConverter instance has three pieces of information about the annotation:

• name: The attribute name;
• class: The attribute class name (can be any string representing a class name);
• options: An array of options.

The apply() method is called whenever a configuration is supported. Based on the request attributes, it should set an attribute named $configuration->getName(), which stores an object of class $configuration->getClass().

If you're using service auto-registration and autoconfiguration, you're done! Your converter will automatically be used. If not, you must add a tag to your service:

# app/config/config.yml
services:
    my_converter:
        class:        MyBundle\Request\ParamConverter\MyConverter
        tags:
            - { name: request.param_converter, priority: -2, converter: my_converter }

<service id="my_converter" class="MyBundle\Request\ParamConverter\MyConverter">
    <tag name="request.param_converter" priority="-2" converter="my_converter" />
</service>

You can register a converter by priority, by name (attribute "converter"), or both. If you don't specify a priority or a name, the converter will be added to the converter stack with a priority of 0. To explicitly disable the registration by priority you have to set priority="false" in your tag definition.

Tip

If you would like to inject services or additional arguments into a custom param converter, the priority shouldn't be higher than 1. Otherwise, the service wouldn't be loaded.

Tip

Use the DoctrineParamConverter class as a template for your own converters.