phoenix

1.4.1

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 4 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

  defstruct path: nil, alias: nil, as: nil, pipes: [], host: nil, private: %{}, assigns: %{}

  @doc """
  Initializes the scope.
  """
  def init(module) do
    Module.put_attribute(module, @stack, [%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
    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"))

    {path, host, alias, as, pipes, private, assigns} =
      join(module, path, plug, as, private, assigns)
    Phoenix.Router.Route.build(line, kind, verb, path, host, alias, plug_opts, as, pipes, private, assigns)
  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)
    stack_pipes =
      module
      |> get_stack()
      |> Enum.flat_map(fn scope -> scope.pipes end)

    update_stack(module, fn [scope | stack] ->
      pipes = collect_pipes(new_pipes, stack_pipes, scope.pipes)
      [put_in(scope.pipes, pipes) | stack]
    end)
  end
  defp collect_pipes([] = _new_pipes, _stack_pipes, acc), do: acc
  defp collect_pipes([pipe | new_pipes], stack_pipes, acc) do
    if pipe in new_pipes or pipe in stack_pipes do
      raise ArgumentError, """
      duplicate pipe_through for #{inspect pipe}.
      A plug may only be used once inside a scoped pipe_through
      """
    end
    collect_pipes(new_pipes, stack_pipes, acc ++ [pipe])
  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
    path = with path when not is_nil(path) <- Keyword.get(opts, :path),
                path <- validate_path(path),
                do: String.split(path, "/", trim: true)

    alias = Keyword.get(opts, :alias)
    alias = alias && Atom.to_string(alias)

    scope = %Scope{path: path,
                   alias: alias,
                   as: Keyword.get(opts, :as),
                   host: Keyword.get(opts, :host),
                   pipes: [],
                   private: Keyword.get(opts, :private, %{}),
                   assigns: Keyword.get(opts, :assigns, %{})}

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

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

  @doc """
  Returns true if the module's definition is currently within a scope block.
  """
  def inside_scope?(module), do: length(get_stack(module)) > 1

  @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

  defp expand_alias(module, alias) do
    if inside_scope?(module) do
      module
      |> get_stack()
      |> join_alias(alias)
    else
      alias
    end
  end

  defp join(module, path, alias, as, private, assigns) do
    stack = get_stack(module)
    {join_path(stack, path), find_host(stack), join_alias(stack, alias),
     join_as(stack, as), join_pipe_through(stack), join_private(stack, private),
     join_assigns(stack, assigns)}
  end

  defp join_path(stack, path) do
    "/" <>
      ([String.split(path, "/", trim: true) | extract(stack, :path)]
       |> Enum.reverse()
       |> Enum.concat()
       |> Enum.join("/"))
  end

  defp join_alias(stack, alias) when is_atom(alias) do
    [alias|extract(stack, :alias)]
    |> Enum.reverse()
    |> Module.concat()
  end

  defp join_as(_stack, nil), do: nil
  defp join_as(stack, as) when is_atom(as) or is_binary(as) do
    [as|extract(stack, :as)]
    |> Enum.reverse()
    |> Enum.join("_")
  end

  defp join_private(stack, private) do
    Enum.reduce stack, private, &Map.merge(&1.private, &2)
  end

  defp join_assigns(stack, assigns) do
    Enum.reduce stack, assigns, &Map.merge(&1.assigns, &2)
  end

  defp join_pipe_through(stack) do
    for scope <- Enum.reverse(stack),
        item <- scope.pipes,
        do: item
  end

  defp find_host(stack) do
    Enum.find_value(stack, & &1.host)
  end

  defp extract(stack, attr) do
    for scope <- stack,
        item = Map.fetch!(scope, attr),
        do: item
  end

  defp get_stack(module) do
    get_attribute(module, @stack)
  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 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