FOSRestBundle Documentation

FOSRestBundle is a Symfony bundle designed for rapid RESTful API development. It provides several core capabilities:

• View Layer: Enables controllers to remain agnostic of the output format.
• Format Negotiation: Handles Accept header negotiation, including support for custom mime types.
• RESTful Decoding: Automatically decodes HTTP request bodies and Accept headers.
• Exception Mapping: Maps exception codes directly to appropriate HTTP response status codes.
• RFC 7807 Error Rendering: Provides a serializer error renderer that returns exceptions and errors in a format compatible with RFC 7807, utilizing either the Symfony Serializer or the JMS Serializer.

FOSRestBundle provides several loosely coupled tools for building REST applications with Symfony:

• The view layer: Tools for managing how data is transformed into responses.
• Listener support: Various listeners to handle request/response lifecycle events (e.g., format listeners, body listeners, versioning).
• ExceptionController support: Support for handling exceptions within a REST context.

FOSRestBundle extends Symfony's @Route annotation by providing shortcuts for specific HTTP methods. These shortcuts support all standard @Route options.

Available shortcuts include:

• @Get, @Post, @Put, @Patch, @Delete
• @Head, @Link, @Unlink, @Lock, @Unlock
• @PropFind, @PropPatch, @Move, @Mkcol, @Copy

// src/Controller/BlogController.php
namespace App\
Controller;

use FOS\RestBundle\Controller\AbstractFOSRestController;
use FOS\RestBundle\Controller\Annotations as Rest;

class BlogController extends AbstractFOSRestController
{
    /**
     * @Rest\Get("/blog", name="blog_list")
     */
    public function list()
    {
        // ...
    }
}
// Or using PHP 8 Attributes:

class BlogController extends AbstractFOSRestController
{
    #[Rest\Get('/blog', name: 'blog_list')]
    public function list()
    {
        // ...
    }
}

The versioning listener detects the API version from several sources in the Request:

• URI: /{version}/users
• Query parameter: /users?version=v1
• Accept header: Accept: application/json; version=1.0
• Custom header: X-Accept-Version: v1

FOSRestBundle provides special handling for Symfony Forms. If you return a Form from a controller, set a Form as the view data, or return an array containing a 'form' key, the bundle automatically manages the response.

If a bound form is invalid and no status code is explicitly set, the bundle will return a "validation failed" response (typically with a 400 status code) containing the error details in a structured format.

// Example of an invalid form response structure:
{
  "code": 400,
  "message": "Validation Failed",
  "errors": {
    "children": {
      "username": {
        "errors": [
          "This value should not be blank."
        ]
      }
    }
  }
}

When versioning is enabled, FOSRestBundle automatically sets the matched version as an exclusion strategy in the ViewHandler when using JMSSerializer.

To make this effective, you must tag your entities with version information using JMS Serializer annotations such as @Since or @Until.

FOSRestBundle requires a serializer to function. It automatically attempts to resolve a serializer in the following order of priority:

1. A custom service configured via the fos_rest.service.serializer configuration key.
2. The JMSSerializerBundle, if it is installed and registered.
3. The Symfony Serializer, if it is enabled or if a service named serializer is available in the container.

To add FOSRestBundle to an existing Symfony project, run the following command in your project directory using Composer:

$ composer require friendsofsymfony/rest-bundle

If SensioFrameworkExtraBundle is installed and sensio_framework_extra.view.annotations is set to true, you can use the @View() annotation. This allows you to return raw data (like an array or object) from your controller instead of a View instance, as the listener will wrap the returned data into a view automatically.

Note: The @View() annotation extends from the @Template() annotation provided by SensioFrameworkExtraBundle.

<?php

namespace AppBundle\
Controller;

use FOS\\RestBundle\\Controller\\Annotations\\View;

class UsersController
{
    /**
     * @View()
     */
    public function getUsersAction()
    {
        // ...
        return $data;
    }
}