PhoenixKitEntities.UrlResolver (PhoenixKitEntities v0.1.5)

@type routes_cache() :: %{
  optional(:all_routes) => list(),
  optional(:content_routes) => list(),
  optional(:index_routes) => list(),
  entity_patterns: map(),
  entity_index_paths: map()
}

Functions

add_public_locale_prefix(path, locale)

@spec add_public_locale_prefix(String.t(), String.t() | nil) :: String.t()

Adds a language prefix for public front-end URLs.

Policy:

Single-language mode → no prefix
Locale is nil, empty, or malformed → no prefix
Locale matches the primary language → no prefix
Otherwise → /<base> prefix (where <base> is a validated base code)

This matches the convention used by PhoenixKit.Utils.Routes.path/2 (default locale served from unprefixed URLs).

The base code is validated against ^[a-z]{2,3}$ before interpolation, so caller-supplied locales (for example from request params) cannot inject arbitrary path segments.

build_path(pattern, record)

@spec build_path(String.t(), map()) :: String.t()

Substitutes :slug and :id placeholders in a URL pattern with record data.

:slug falls back to the record UUID when the slug is nil. Patterns without placeholders are returned unchanged.

build_path_with_language(path, language, is_default \\ true)

@spec build_path_with_language(String.t(), String.t() | nil, boolean()) :: String.t()

Adds a language prefix to a path (sitemap policy: prefix every language in multilang mode).

Used by PhoenixKitEntities.SitemapSource for hreflang-aware sitemap entries. Consumers building public links should prefer add_public_locale_prefix/2, which omits the prefix for the primary language (matching PhoenixKit.Utils.Routes conventions).

build_routes_cache()

@spec build_routes_cache() :: routes_cache()

Builds a cache of all routes for efficient lookups.

For hot loops (e.g. rendering a listing of records), build the cache once via this function and pass it as :routes_cache to EntityData.public_path/3.

build_url(path, base_url \\ nil)

@spec build_url(String.t(), String.t() | nil) :: String.t()

Builds a full URL by prepending a base URL.

If base_url is nil, falls back to the site_url setting (or empty string).

get_index_path_cached(entity, routes_cache)

@spec get_index_path_cached(map(), routes_cache()) :: String.t() | nil

Resolves the index-page path for an entity using a pre-built routes cache.

Used by the sitemap source to emit index entries (e.g. /products alongside /products/:slug). Returns nil if no index path can be resolved.

get_url_pattern_cached(entity, routes_cache)

@spec get_url_pattern_cached(map(), routes_cache()) :: String.t() | nil

Resolves the URL pattern for an entity using a pre-built routes cache.

Resolution chain: entity.settings["sitemap_url_pattern"] → router introspection (explicit or catchall) → sitemap_entity_<name>_pattern setting → global sitemap_entities_pattern. Returns nil if none match.

single_language_mode?()

@spec single_language_mode?() :: boolean()

Returns true when the site is effectively single-language.

True when the Languages module is disabled or only one language is enabled; also true if the lookup fails (defensive fallback).