instance method match

Matches a URL pattern to one or more routes.

You should not use the match method in your router without specifying an HTTP method.

If you want to expose your action to both GET and POST, use:

# sets :controller, :action, and :id in params
match ':controller/:action/:id', via: [:get, :post]

Note that :controller, :action, and :id are interpreted as URL query parameters and thus available through params in an action.

If you want to expose your action to GET, use get in the router:

Instead of:

match ":controller/:action/:id"

Do:

get ":controller/:action/:id"

Two of these symbols are special, :controller maps to the controller and :action to the controller’s action. A pattern can also map wildcard segments (globs) to params:

get 'songs/*category/:title', to: 'songs#show'

# 'songs/rock/classic/stairway-to-heaven' sets
#  params[:category] = 'rock/classic'
#  params[:title] = 'stairway-to-heaven'

To match a wildcard parameter, it must have a name assigned to it. Without a variable name to attach the glob parameter to, the route can’t be parsed.

When a pattern points to an internal route, the route’s :action and :controller should be set in options or hash shorthand. Examples:

match 'photos/:id', to: 'photos#show', via: :get
match 'photos/:id', controller: 'photos', action: 'show', via: :get

A pattern can also point to a Rack endpoint i.e. anything that responds to call:

match 'photos/:id', to: -> (hash) { [200, {}, ["Coming soon"]] }, via: :get
match 'photos/:id', to: PhotoRackApp, via: :get
# Yes, controller actions are just rack endpoints
match 'photos/:id', to: PhotosController.action(:show), via: :get

Because requesting various HTTP verbs with a single action has security implications, you must either specify the actions in the via options or use one of the HttpHelpers instead match

Options

Any options not seen here are passed on as params with the URL.

:controller

The route’s controller.

:action

The route’s action.

:param

Overrides the default resource identifier :id (name of the dynamic segment used to generate the routes). You can access that segment from your controller using params[<:param>]. In your router:

    resources :users, param: :name

The `users` resource here will have the following routes generated for it:

    GET       /users(.:format)
    POST      /users(.:format)
    GET       /users/new(.:format)
    GET       /users/:name/edit(.:format)
    GET       /users/:name(.:format)
    PATCH/PUT /users/:name(.:format)
    DELETE    /users/:name(.:format)

You can override `ActiveRecord::Base#to_param` of a related model to
construct a URL:

    class User < ActiveRecord::Base
      def to_param
        name
      end
    end

    user = User.find_by(name: 'Phusion')
    user_path(user)  # => "/users/Phusion"

:path

The path prefix for the routes.

:module

The namespace for :controller.

    match 'path', to: 'c#a', module: 'sekret', controller: 'posts', via: :get
    # => Sekret::PostsController

See `Scoping#namespace` for its scope equivalent.

:as

The name used to generate routing helpers.

:via

Allowed HTTP verb(s) for route.

    match 'path', to: 'c#a', via: :get
    match 'path', to: 'c#a', via: [:get, :post]
    match 'path', to: 'c#a', via: :all

:to

Points to a Rack endpoint. Can be an object that responds to call or a string representing a controller’s action.

    match 'path', to: 'controller#action', via: :get
    match 'path', to: -> (env) { [200, {}, ["Success!"]] }, via: :get
    match 'path', to: RackApp, via: :get

:on

Shorthand for wrapping routes in a specific RESTful context. Valid values are :member, :collection, and :new. Only use within resource(s) block. For example:

    resource :bar do
      match 'foo', to: 'c#a', on: :member, via: [:get, :post]
    end

Is equivalent to:

    resource :bar do
      member do
        match 'foo', to: 'c#a', via: [:get, :post]
      end
    end

:constraints

Constrains parameters with a hash of regular expressions or an object that responds to matches?. In addition, constraints other than path can also be specified with any object that responds to === (e.g. String, Array, Range, etc.).

    match 'path/:id', constraints: { id: /[A-Z]\d{5}/ }, via: :get

    match 'json_only', constraints: { format: 'json' }, via: :get

    class PermitList
      def matches?(request) request.remote_ip == '1.2.3.4' end
    end
    match 'path', to: 'c#a', constraints: PermitList.new, via: :get

See `Scoping#constraints` for more examples with its scope equivalent.

:defaults

Sets defaults for parameters

    # Sets params[:format] to 'jpg' by default
    match 'path', to: 'c#a', defaults: { format: 'jpg' }, via: :get

See `Scoping#defaults` for its scope equivalent.

:anchor

Boolean to anchor a match pattern. Default is true. When set to false, the pattern matches any request prefixed with the given path.

    # Matches any request starting with 'path'
    match 'path', to: 'c#a', anchor: false, via: :get

:format

Allows you to specify the default value for optional format segment or disable it by supplying false.