Provides support for RESTful Controllers inside Symfony2 project.

Features

• fast to start REST services development
• conventionaly clean & self-explanatory action names
• autogenerated routes by proper action names

Installation

Add Everzet\RestfulControllersBundle to your src/Bundle dir

git submodule add git://github.com/everzet/EverzetRestfulControllersBundle.git src/Bundle/Everzet/RestfulControllersBundle

Add EverzetRestfulControllersBundle to your application kernel

// app/AppKernel.php
public function registerBundles()
{
    return array(
        // ...
        new Bundle\Everzet\RestfulControllersBundle\EverzetRestfulControllersBundle(),
        // ...
    );
}

Turn on restful bundle in application config

# app/config/config.yml
restful.config: ~

Single RESTful controller routes

# app/confg/routing.yml
users:
  type:     restful
  resource: Application\HelloBundle\Controller\UsersController

this will tell Symfony2 to automatically generate proper REST routes from your UsersController action names.
Notice type: restful option. It's required to RestfulControllers to find which routes are supported.

Define resource actions

class UsersController extends Controller
{
    public function getUsersAction()
    {} // `get_users`   [GET] /users

    public function getUserAction($slug)
    {} // `get_user`    [GET] /users/{slug}

    public function postUsersAction()
    {} // `post_users`  [POST] /users

    public function putUserAction($slug)
    {} // `put_user`    [PUT] /users/{slug}

    public function lockUserAction($slug)
    {} // `lock_user`   [PUT] /users/{slug}/lock

    public function newUsersAction()
    {} // `new_users`   [GET] /users/new

    public function banUserAction($slug, $id)
    {} // `ban_user`    [PUT] /users/{slug}/ban

    public function voteUserCommentAction($slug, $id)
    {} // `vote_user_comment`   [PUT] /users/{slug}/comments/{id}/vote

    public function getUserCommentsAction($slug)
    {} // `get_user_comments`   [GET] /users/{slug}/comments

    public function getUserCommentAction($slug, $id)
    {} // `get_user_comment`    [GET] /users/{slug}/comments/{id}

    public function deleteUserCommentAction($slug, $id)
    {} // `delete_user_comment` [DELETE] /users/{slug}/comments/{id}

    public function newUserCommentsAction($slug)
    {} // `new_user_comments`   [GET] /users/{slug}/comments/new
}

That's all. All your resource (UsersController) actions will get mapped to proper routes (commented examples).

Relational RESTful controllers routes

Sometimes it's better to place subresource actions in it's own controller. Especially when you have more than 2 subresource actions.

Resource collection

In this case, you must first specify resource relations in special restful YML or XML collection:

# HelloBundle/Resources/config/users_routes.yml
users:
  type:     restful
  resource: Application\HelloBundle\Controller\UsersController

comments:
  type:     restful
  parent:   users
  resource: Application\HelloBundle\Controller\CommentsController

Notice parent: users option in second case. This option specifies that comments resource is child of users resource. In this case, your UsersController MUST always have single resource get... action:

class UsersController extends Controller
{
    public function getUserAction($slug)
    {} // `get_user`   [GET] /users/{slug}

    ...
}

It's used to determine parent collection name. Controller name itself not used in routes autogeneration process & can be any name you like.

Define child resource controller

CommentsController actions now will looks like:

class CommentsController extends Controller
{
    public function voteCommentAction($slug, $id)
    {} // `vote_user_comment`   [PUT] /users/{slug}/comments/{id}/vote

    public function getCommentsAction($slug)
    {} // `get_user_comments`   [GET] /users/{slug}/comments

    public function getCommentAction($slug, $id)
    {} // `get_user_comment`    [GET] /users/{slug}/comments/{id}

    public function deleteCommentAction($slug, $id)
    {} // `delete_user_comment` [DELETE] /users/{slug}/comments/{id}

    public function newCommentsAction($slug)
    {} // `new_user_comments`   [GET] /users/{slug}/comments/new
}

Notice, that we get rid of User part in action names. It's because RestfulControllers routing already knows, that CommentsController::... is child resources of UsersController::getUser() resource.

Include resource collections in application routing

Last step is mapping of your collection routes into application routing.yml:

# app/confg/routing.yml
users:
  type:     restful
  resource: HelloBundle/Resources/config/users_routes.yml

That's all.

Routes naming

RestfulControllersBundle uses REST path to generate route name. It means, that URL:

[PUT] /users/{slug}/comments/{id}/vote

will become route with name:

vote_user_comment

For further examples, see comments of controllers code above.

Naming collisions

Sometimes, routes autonaming will lead to the route names collisions, so RestfulControllers route collections has name_prefix (name-prefix for xml) parameter:

# HelloBundle/Resources/config/users_routes.yml
comments:
  type:         restful
  resource:     Application\HelloBundle\Controller\CommentsController
  name_prefix:  api_

With this configuration, route name would become:

api_vote_user_comment

Say NO to name collisions!

CREATORS

• Bulat Shakirzyanov (avalanche123)
• Konstantin Kudryashov (everzet)