Merge pull request phoenixframework#935 from jxs/master

deprecate resource in favor of using resources with singleton: true

lib/phoenix/router.ex

@@ -237,21 +237,34 @@ defmodule Phoenix.Router do
       end
 
       var!(add_resources, Phoenix.Router) = fn resource ->
-        parm = resource.param
         path = resource.path
         ctrl = resource.controller
         opts = resource.route
 
-        Enum.each resource.actions, fn
-          :index   -> get    path,                            ctrl, :index, opts
-          :show    -> get    path <> "/:" <> parm,            ctrl, :show, opts
-          :new     -> get    path <> "/new",                  ctrl, :new, opts
-          :edit    -> get    path <> "/:" <> parm <> "/edit", ctrl, :edit, opts
-          :create  -> post   path,                            ctrl, :create, opts
-          :delete  -> delete path <> "/:" <> parm,            ctrl, :delete, opts
-          :update  ->
-            patch path <> "/:" <> parm, ctrl, :update, opts
-            put   path <> "/:" <> parm, ctrl, :update, Keyword.put(opts, :as, nil)
+        if !resource.singular do
+          parm = resource.param
+          Enum.each resource.actions, fn
+            :index   -> get    path,                            ctrl, :index, opts
+            :show    -> get    path <> "/:" <> parm,            ctrl, :show, opts
+            :new     -> get    path <> "/new",                  ctrl, :new, opts
+            :edit    -> get    path <> "/:" <> parm <> "/edit", ctrl, :edit, opts
+            :create  -> post   path,                            ctrl, :create, opts
+            :delete  -> delete path <> "/:" <> parm,            ctrl, :delete, opts
+            :update  ->
+              patch path <> "/:" <> parm, ctrl, :update, opts
+              put   path <> "/:" <> parm, ctrl, :update, Keyword.put(opts, :as, nil)
+          end
+        else
+          Enum.each resource.actions, fn
+            :show    -> get    path,            ctrl, :show, opts
+            :new     -> get    path <> "/new",  ctrl, :new, opts
+            :edit    -> get    path <> "/edit", ctrl, :edit, opts
+            :create  -> post   path,            ctrl, :create, opts
+            :delete  -> delete path,            ctrl, :delete, opts
+            :update  ->
+              patch path, ctrl, :update, opts
+              put   path, ctrl, :update, Keyword.put(opts, :as, nil)
+          end
         end
       end
     end
@@ -462,6 +475,15 @@ defmodule Phoenix.Router do
       is automatically derived from the controller name, i.e. `UserController` will
       have name `"user"`
     * `:as` - configures the named helper exclusively
+    * `:singleton` - Defines "RESTful" routes for a resource that client's lookup without referencing an ID, which will include the following routes instead:
+
+    * `GET /user` => `:show`
+    * `GET /user/new` => `:new`
+    * `POST /user` => `:create`
+    * `GET /user/edit` => `:edit`
+    * `PATCH /user` => `:update`
+    * `PUT /user` => `:update`
+    * `DELETE /user` => `:delete`
 
   """
   defmacro resources(path, controller, opts, do: nested_context) do
@@ -475,6 +497,9 @@ defmodule Phoenix.Router do
     add_resources path, controller, [], do: nested_context
   end
 
+  @doc """
+  See `resources/4`.
+  """
   defmacro resources(path, controller, opts) do
     add_resources path, controller, opts, do: nil
   end
@@ -487,49 +512,42 @@ defmodule Phoenix.Router do
   end
 
   @doc """
-  Defines "RESTful" routes for a resource that client's lookup without referencing an ID.
-
-  The given definition:
-
-      resource "/account", UserController
-
-  will include routes to the following actions:
-
-    * `GET /account` => `:show`
-    * `GET /account/new` => `:new`
-    * `POST /account` => `:create`
-    * `GET /account/edit` => `:edit`
-    * `PATCH /account` => `:update`
-    * `PUT /account` => `:update`
-    * `DELETE /account` => `:delete`
-
-  ## Options
-
-  This macro accepts the same options as `resources/4`
-
+  Deprecated, please use `resource/4` with option `singleton: true` instead
   """
   defmacro resource(path, controller, opts, do: nested_context) do
+    stacktrace = __CALLER__ |> Macro.Env.stacktrace |> Exception.format_stacktrace
+    IO.write :stderr, "[warning] resource/4 in Phoenix router is deprecated, please use " <>
+      "resources/3 with the singleton option instead.\n" <> stacktrace
     add_resource path, controller, opts, do: nested_context
   end
 
   @doc """
   See `resource/4`.
   """
   defmacro resource(path, controller, do: nested_context) do
+    stacktrace = __CALLER__ |> Macro.Env.stacktrace |> Exception.format_stacktrace
+    IO.write :stderr, "[warning] resource/4 in Phoenix router is deprecated, please use " <>
+      "resources/3 with the singleton option instead.\n" <> stacktrace
     add_resource path, controller, [], do: nested_context
   end
 
   @doc """
   See `resource/4`.
   """
   defmacro resource(path, controller, opts) do
+    stacktrace = __CALLER__ |> Macro.Env.stacktrace |> Exception.format_stacktrace
+    IO.write :stderr, "[warning] resource/4 in Phoenix router is deprecated, please use " <>
+      "resources/3 with the singleton option instead.\n" <> stacktrace
     add_resource path, controller, opts, do: nil
   end
 
   @doc """
   See `resource/4`.
   """
   defmacro resource(path, controller) do
+    stacktrace = __CALLER__ |> Macro.Env.stacktrace |> Exception.format_stacktrace
+    IO.write :stderr, "[warning] resource/4 in Phoenix router is deprecated, please use " <>
+      "resources/3 with the singleton option instead.\n" <> stacktrace
     add_resource path, controller, [], do: nil
   end
 
@@ -542,7 +560,7 @@ defmodule Phoenix.Router do
       end
 
     quote do
-      resource = Resource.plural(unquote(path), unquote(controller), unquote(options))
+      resource = Resource.build(unquote(path), unquote(controller), unquote(options))
       var!(add_resources, Phoenix.Router).(resource)
       unquote(scope)
     end

lib/phoenix/router/resource.ex

@@ -21,30 +21,27 @@ defmodule Phoenix.Router.Resource do
     * :collection - the context for collection routes
 
   """
-  defstruct [:path, :actions, :param, :route, :controller, :route, :member, :collection]
+  defstruct [:path, :actions, :param, :route, :controller, :route, :member, :collection, :singular]
   @type t :: %Resource{}
 
-  @doc """
-  Builds a plural resource struct.
-  """
-  def plural(path, controller, options) do
-    build(path, controller, options)
-  end
-
   @doc """
   Builds a singular resource struct.
+  deprecated please use `build/3` with `singleton: true` instead.
   """
   def singular(path, controller, options) do
     build(path, controller, Keyword.put(options, :singular, true))
   end
 
-  defp build(path, controller, options) when
+  @doc """
+  Builds a resource struct.
+  """
+  def build(path, controller, options) when
       is_binary(path) and is_atom(controller) and is_list(options) do
     alias    = Keyword.get(options, :alias)
     param    = Keyword.get(options, :param, @default_param_key)
     name     = Keyword.get(options, :name, Phoenix.Naming.resource_name(controller, "Controller"))
     as       = Keyword.get(options, :as, name)
-    singular = Keyword.get(options, :singular)
+    singular = Keyword.get(options, :singular) || Keyword.get(options, :singleton)
     private  = Keyword.get(options, :private, %{})
     assigns  = Keyword.get(options, :assigns, %{})
     actions  = extract_actions(options, singular)
@@ -55,7 +52,7 @@ defmodule Phoenix.Router.Resource do
     member      = [path: member_path, as: as, alias: alias, private: private, assigns: assigns]
 
     %Resource{path: path, actions: actions, param: param, route: route,
-              member: member, collection: collection, controller: controller}
+              member: member, collection: collection, controller: controller, singular: singular}
   end
 
   defp extract_actions(opts, singular) do

test/phoenix/router/console_formatter_test.exs

@@ -44,6 +44,23 @@ defmodule Phoenix.Router.ConsoleFormatterTest do
     """
   end
 
+  defmodule RouterTestResource do
+    use Phoenix.Router
+    resources "/image", Phoenix.ImageController, singleton: true
+  end
+
+  test "format single resource routes" do
+    assert draw(RouterTestResource) == """
+    image_path  GET     /image/edit  Phoenix.ImageController.edit/2
+    image_path  GET     /image/new   Phoenix.ImageController.new/2
+    image_path  GET     /image       Phoenix.ImageController.show/2
+    image_path  POST    /image       Phoenix.ImageController.create/2
+    image_path  PATCH   /image       Phoenix.ImageController.update/2
+                PUT     /image       Phoenix.ImageController.update/2
+    image_path  DELETE  /image       Phoenix.ImageController.delete/2
+    """
+  end
+
   defp draw(router) do
     ConsoleFormatter.format(router)
   end

test/phoenix/router/helpers_test.exs

@@ -68,8 +68,8 @@ defmodule Phoenix.Router.HelpersTest do
 
     resources "/files", FileController
 
-    resource "/account", UserController, as: :account do
-      resource "/page", PagesController, as: :page, only: [:show]
+    resources "/account", UserController, as: :account, singleton: true do
+      resources "/page", PagesController, as: :page, only: [:show], singleton: true
     end
 
     scope "/admin", alias: Admin do

test/phoenix/router/resource_test.exs

@@ -15,12 +15,12 @@ defmodule Phoenix.Router.ResourceTest do
   defmodule Router do
     use Phoenix.Router
 
-    resource "/account", Api.GenericController, alias: Api do
+    resources "/account", Api.GenericController, alias: Api, singleton: true do
       resources "/comments", GenericController
-      resource "/session", GenericController, except: [:delete]
+      resources "/session", GenericController, except: [:delete], singleton: true
     end
 
-    resource "/session", Api.GenericController, only: [:show]
+    resources "/session", Api.GenericController, only: [:show], singleton: true
   end
 
   setup do