PhoenixSelect.Helpers.URI (PhoenixSelect v1.0.0)

Helpers for reading and writing URL query parameters.

In :url_params mode, PhoenixSelect stores the selection in the URL query string so it survives navigation and refreshes and can be shared as a link. These helpers manipulate query params on a URI string and return paths suitable for Phoenix.LiveView.push_patch/2.

Keys support single-level bracket notation (e.g. "filter[genre]"), which encodes to nested query params.

Summary

Functions

create_or_update_or_delete_query_param(uri, key, value)

Sets a query param, or removes it when the value is nil, "", or [].

create_or_update_query_param(uri, key, value)

Sets a query param on the given URI string, replacing any existing value.

delete_query_param(uri, key)

Removes a query param from the given URI string.

extract_full_path(value)

Returns the path, query, and fragment of a URI as a single string, stripping scheme and host. Suitable for push_patch/2.

get_query_param(uri, key)

Returns the decoded value of a query param, or nil when absent.

param_path(key)

Parses a bracket-notation key like "filter[genre]" into a list of access keys. Simple keys return a single-element list.

Functions

create_or_update_or_delete_query_param(uri, key, value)

@spec create_or_update_or_delete_query_param(String.t(), String.t() | atom(), any()) ::
  String.t()

Sets a query param, or removes it when the value is nil, "", or [].

create_or_update_query_param(uri, key, value)

@spec create_or_update_query_param(String.t(), String.t() | atom(), any()) ::
  String.t()

Sets a query param on the given URI string, replacing any existing value.

Examples

iex> PhoenixSelect.Helpers.URI.create_or_update_query_param("/books", "sort", "title")
"/books?sort=title"

iex> PhoenixSelect.Helpers.URI.create_or_update_query_param("/books?sort=title", "sort", "year")
"/books?sort=year"

iex> PhoenixSelect.Helpers.URI.create_or_update_query_param("/books", "filter[genre]", ["scifi", "horror"])
"/books?filter[genre][]=scifi&filter[genre][]=horror"

delete_query_param(uri, key)

@spec delete_query_param(String.t(), String.t() | atom()) :: String.t()

Removes a query param from the given URI string.

Examples

iex> PhoenixSelect.Helpers.URI.delete_query_param("/books?sort=title&page=2", "sort")
"/books?page=2"

iex> PhoenixSelect.Helpers.URI.delete_query_param("/books?sort=title", "sort")
"/books"

extract_full_path(value)

@spec extract_full_path(String.t()) :: String.t()

Returns the path, query, and fragment of a URI as a single string, stripping scheme and host. Suitable for push_patch/2.

Examples

iex> PhoenixSelect.Helpers.URI.extract_full_path("https://example.com/books?sort=title#top")
"/books?sort=title#top"

get_query_param(uri, key)

@spec get_query_param(String.t(), String.t()) :: String.t() | list() | map() | nil

Returns the decoded value of a query param, or nil when absent.

Array params (genre[]=a&genre[]=b) decode to lists, bracket params decode to maps.

Examples

iex> PhoenixSelect.Helpers.URI.get_query_param("/books?sort=title", "sort")
"title"

iex> PhoenixSelect.Helpers.URI.get_query_param("/books?genre[]=scifi&genre[]=horror", "genre")
["scifi", "horror"]

iex> PhoenixSelect.Helpers.URI.get_query_param("/books", "sort")
nil

param_path(key)

@spec param_path(String.t() | atom()) :: [String.t() | atom()]

Parses a bracket-notation key like "filter[genre]" into a list of access keys. Simple keys return a single-element list.

Examples

iex> PhoenixSelect.Helpers.URI.param_path("filter[genre]")
["filter", "genre"]

iex> PhoenixSelect.Helpers.URI.param_path("genre")
["genre"]