Developed with love by KnpLabs Hire us for your project!
7

EverzetRestfulControllersBundle

by sheknows

RESTful Controllers for Symfony2

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)
Copyright (c) 2010 Konstantin Kudryashov <ever.zet@gmail.com>

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.
  • Updating Symfony
    By cristiangraz, 3 years ago
  • Merge branch 'master' of github.com:sheknows/EverzetRestfulControllersBundle
    By justinrainbow, 3 years ago
  • Updating bundle to use new Config Component
    By justinrainbow, 3 years ago
  • Merge branch 'master' of github.com:sheknows/EverzetRestfulControllersBundle
    By justinrainbow, 3 years ago
  • Fixed loading resources that start with @
    By justinrainbow, 3 years ago
  • Fixed the DIC from latest Symfony update
    By justinrainbow, 3 years ago
  • Quick fixes to work with Symfony bundle management refactoring (fabpot/symfony@6d1e91a1)
    By justinrainbow, 3 years ago
  • Adding getPath() and getNamespace() methods to EverzetRestfulControllersBundle
    By justinrainbow, 3 years ago
  • Merge branch 'master' of git://github.com/everzet/EverzetRestfulControllersBundle
    By justinrainbow, 3 years ago
  • route names prefix option
    By everzet, 3 years ago
  • Merge branch 'master' of git://github.com/everzet/EverzetRestfulControllersBundle
    By justinrainbow, 3 years ago
  • updated to new pattern syntax (PR5)
    By everzet, 3 years ago
  • added failing tests
    By everzet, 3 years ago
  • fixed pluralization
    By everzet, 3 years ago
  • Merge branch 'master' of git://github.com/everzet/EverzetRestfulControllersBundle
    By justinrainbow, 3 years ago
  • added ability to define actions with underscored methods
    By everzet, 3 years ago
  • added ability to turn off route autogeneration
    By everzet, 3 years ago
  • added ability to define `_` prefixed actions without route autogeneration
    By everzet, 3 years ago
  • updated README.md with relations documentation
    By everzet, 3 years ago
  • updated type specification & documentation
    By everzet, 3 years ago
  • Merge branch 'master' of github.com:everzet/EverzetRestfulControllersBundle
    By everzet, 3 years ago
  • updated bundle to support latest Symfony2 PR4
    By everzet, 3 years ago
  • Merge branch 'master' of git://github.com/everzet/EverzetRestfulControllersBundle
    By justinrainbow, 4 years ago
  • Updating the RestfulControllerLoader to match new method names for Routes
    By everzet, 4 years ago
  • Updating the RestfulControllerLoader to match new method names for Routes
    By justinrainbow, 4 years ago
  • Symfony2 now will know when class changed & will
    By everzet, 4 years ago
  • fixed DIC extension configuration
    By everzet, 4 years ago
  • fixed README
    By everzet, 4 years ago
  • Merge branch 'collisions-fixes'
    By everzet, 4 years ago
  • added additional supports test
    By everzet, 4 years ago