phoenix

1.6.15

1.8.9 1.8.8 1.8.7 1.8.6 1.8.5 1.8.4 1.8.3 1.8.2 1.8.1 1.8.0 1.8.0-rc.4 1.8.0-rc.3 1.8.0-rc.2 1.8.0-rc.1 1.8.0-rc.0 1.7.24 1.7.23 1.7.22 1.7.21 1.7.20 1.7.19 1.7.18 1.7.17 1.7.16 1.7.15 1.7.14 1.7.13 1.7.12 1.7.11 1.7.10 1.7.9 1.7.8 1.7.7 1.7.6 1.7.5 1.7.4 1.7.3 1.7.2 1.7.1 1.7.0 1.7.0-rc.3 1.7.0-rc.2 1.7.0-rc.1 1.7.0-rc.0 1.6.17 1.6.16 1.6.15 1.6.14 1.6.13 1.6.12 1.6.11 1.6.10 1.6.9 1.6.8 1.6.7 1.6.6 1.6.5 1.6.4 1.6.3 1.6.2 1.6.1 1.6.0 1.6.0-rc.1 1.6.0-rc.0 1.5.15 1.5.14 1.5.13 1.5.12 1.5.11 1.5.10 1.5.9 1.5.8 1.5.7 1.5.6 1.5.5 1.5.4 1.5.3 1.5.2 1.5.1 1.5.0 1.5.0-rc.0 1.4.18 1.4.17 1.4.16 1.4.15 1.4.14 1.4.13 1.4.12 1.4.11 1.4.10 1.4.9 1.4.8 1.4.7 1.4.6 1.4.5 1.4.4 1.4.3 1.4.2 1.4.1 1.4.0 1.4.0-rc.3 1.4.0-rc.2 1.4.0-rc.1 1.4.0-rc.0 1.3.5 1.3.4 1.3.3 1.3.2 1.3.1 1.3.0 1.3.0-rc.3 1.3.0-rc.2 1.3.0-rc.1 1.3.0-rc.0 1.2.5 1.2.4 1.2.3 1.2.2 1.2.1 1.2.0 1.2.0-rc.1 1.2.0-rc.0 1.1.9 1.1.8 1.1.7 1.1.6 1.1.5 1.1.4 1.1.3 1.1.2 1.1.1 1.1.0 1.0.6 1.0.5 1.0.4 1.0.3 1.0.2 1.0.1 1.0.0 0.17.1 0.17.0 0.16.1 0.16.0 0.15.0 0.14.0 0.13.1 0.13.0 0.12.0 0.11.0 0.10.0 0.9.0 0.8.0 0.7.2 0.7.1 0.7.0 0.6.2 0.6.1 0.6.0 0.5.0 0.4.1 0.4.0 0.3.1 0.3.0 0.2.11 0.2.10 0.2.9 0.2.8 0.2.7 0.2.6 0.2.5 0.2.4 0.2.3 0.2.2 0.2.1 0.2.0 0.1.0

Productive. Reliable. Fast. A productive web framework that does not compromise speed or maintainability.

Security advisory: This version has known vulnerabilities. View advisories

HexDocs

Current section

Files

Jump to

Readme 176 Versions 8 Dependencies Dependants 5 Advisories Files Activity

phoenix lib phoenix router scope.ex

Raw

lib/phoenix/router/scope.ex

defmodule Phoenix.Router.Scope do
  alias Phoenix.Router.{Scope, Route}
  @moduledoc false

  @stack :phoenix_router_scopes
  @pipes :phoenix_pipeline_scopes
  @top :phoenix_top_scopes

  defstruct path: [], alias: [], as: [], pipes: [], host: nil, private: %{}, assigns: %{}, log: :debug, trailing_slash?: false

  @doc """
  Initializes the scope.
  """
  def init(module) do
    Module.put_attribute(module, @stack, [])
    Module.put_attribute(module, @top, %Scope{})
    Module.put_attribute(module, @pipes, MapSet.new())
  end

  @doc """
  Builds a route based on the top of the stack.
  """
  def route(line, module, kind, verb, path, plug, plug_opts, opts) do
    top = get_top(module)
    path    = validate_path(path)
    private = Keyword.get(opts, :private, %{})
    assigns = Keyword.get(opts, :assigns, %{})
    as      = Keyword.get(opts, :as, Phoenix.Naming.resource_name(plug, "Controller"))
    alias?  = Keyword.get(opts, :alias, true)
    trailing_slash? = Keyword.get(opts, :trailing_slash, top.trailing_slash?) == true

    if to_string(as) == "static"  do
      raise ArgumentError, "`static` is a reserved route prefix generated from #{inspect plug} or `:as` option"
    end

    {path, alias, as, private, assigns} =
      join(top, path, plug, alias?, as, private, assigns)

    metadata =
      opts
      |> Keyword.get(:metadata, %{})
      |> Map.put(:log, Keyword.get(opts, :log, top.log))

    Phoenix.Router.Route.build(line, kind, verb, path, top.host, alias, plug_opts, as, top.pipes, private, assigns, metadata, trailing_slash?)
  end

  @doc """
  Validates a path is a string and contains a leading prefix.
  """
  def validate_path("/" <> _ = path), do: path
  def validate_path(path) when is_binary(path) do
    IO.warn """
    router paths should begin with a forward slash, got: #{inspect path}
    #{Exception.format_stacktrace()}
    """

    "/" <> path
  end
  def validate_path(path) do
    raise ArgumentError, "router paths must be strings, got: #{inspect path}"
  end

  @doc """
  Defines the given pipeline.
  """
  def pipeline(module, pipe) when is_atom(pipe) do
    update_pipes module, &MapSet.put(&1, pipe)
  end

  @doc """
  Appends the given pipes to the current scope pipe through.
  """
  def pipe_through(module, new_pipes) do
    new_pipes = List.wrap(new_pipes)
    %{pipes: pipes} = top = get_top(module)

    if pipe = Enum.find(new_pipes, & &1 in pipes) do
      raise ArgumentError,
            "duplicate pipe_through for #{inspect pipe}. " <>
              "A plug may only be used once inside a scoped pipe_through"
    end

    put_top(module, %{top | pipes: pipes ++ new_pipes})
  end

  @doc """
  Pushes a scope into the module stack.
  """
  def push(module, path) when is_binary(path) do
    push(module, path: path)
  end

  def push(module, opts) when is_list(opts) do
    top = get_top(module)

    path =
      if path = Keyword.get(opts, :path) do
        path |> validate_path() |> String.split("/", trim: true)
      else
        []
      end

    alias = append_unless_false(top, opts, :alias, &Atom.to_string(&1))
    as = append_unless_false(top, opts, :as, & &1)
    host = Keyword.get(opts, :host)
    private = Keyword.get(opts, :private, %{})
    assigns = Keyword.get(opts, :assigns, %{})

    update_stack(module, fn stack -> [top | stack] end)

    put_top(module, %Scope{
      path: top.path ++ path,
      alias: alias,
      as: as,
      host: host || top.host,
      pipes: top.pipes,
      private: Map.merge(top.private, private),
      assigns: Map.merge(top.assigns, assigns),
      log: Keyword.get(opts, :log, top.log),
      trailing_slash?: Keyword.get(opts, :trailing_slash, top.trailing_slash?) == true
    })
  end

  defp append_unless_false(top, opts, key, fun) do
    case opts[key] do
      false -> []
      nil -> Map.fetch!(top, key)
      other -> Map.fetch!(top, key) ++ [fun.(other)]
    end
  end

  @doc """
  Pops a scope from the module stack.
  """
  def pop(module) do
    update_stack(module, fn [top | stack] ->
      put_top(module, top)
      stack
    end)
  end

  @doc """
  Add a forward to the router.
  """
  def register_forwards(module, path, plug) when is_atom(plug) do
    plug = expand_alias(module, plug)
    phoenix_forwards = Module.get_attribute(module, :phoenix_forwards)
    path_segments = Route.forward_path_segments(path, plug, phoenix_forwards)
    phoenix_forwards = Map.put(phoenix_forwards, plug, path_segments)
    Module.put_attribute(module, :phoenix_forwards, phoenix_forwards)
    plug
  end

  def register_forwards(_, _, plug) do
    raise ArgumentError, "forward expects a module as the second argument, #{inspect plug} given"
  end

  @doc """
  Expands the alias in the current router scope.
  """
  def expand_alias(module, alias) do
    join_alias(get_top(module), alias)
  end

  defp join(top, path, alias, alias?, as, private, assigns) do
    joined_alias =
      if alias? do
        join_alias(top, alias)
      else
        alias
      end

    {join_path(top, path), joined_alias, join_as(top, as),
     Map.merge(top.private, private), Map.merge(top.assigns, assigns)}
  end

  defp join_path(top, path) do
    "/" <> Enum.join(top.path ++ String.split(path, "/", trim: true), "/")
  end

  defp join_alias(top, alias) when is_atom(alias) do
    Module.concat(top.alias ++ [alias])
  end

  defp join_as(_top, nil), do: nil
  defp join_as(top, as) when is_atom(as) or is_binary(as), do: Enum.join(top.as ++ [as], "_")

  defp get_top(module) do
    get_attribute(module, @top)
  end

  defp update_stack(module, fun) do
    update_attribute(module, @stack, fun)
  end

  defp update_pipes(module, fun) do
    update_attribute(module, @pipes, fun)
  end

  defp put_top(module, value) do
    Module.put_attribute(module, @top, value)
    value
  end

  defp get_attribute(module, attr) do
    Module.get_attribute(module, attr) ||
      raise "Phoenix router scope was not initialized"
  end

  defp update_attribute(module, attr, fun) do
    Module.put_attribute(module, attr, fun.(get_attribute(module, attr)))
  end
end

Operator	Description	Example
name:	Match package name. Supports * wildcards and repo/package form	name:phx* or name:hexpm/phoenix
description:	Full-text search of package descriptions	description:auth
depends:	Packages depending on a given package. Supports repo:package form	depends:ecto or depends:hexpm:ecto
build_tool:	Filter by build tool	build_tool:mix
updated_after:	Packages updated after an ISO8601 datetime	updated_after:2025-01-01T00:00:00Z
extra:	Match custom metadata (key,value). Nested keys are separated by commas	extra:license,MIT