Dynamic entity system for PhoenixKit.
This module provides both the Ecto schema definition and business logic for managing custom content types (entities) with flexible field schemas.
Schema Fields
name: Unique identifier for the entity (e.g., "brand", "product")display_name: Human-readable singular name shown in UI (e.g., "Brand")display_name_plural: Human-readable plural name (e.g., "Brands")description: Description of what this entity representsicon: Icon identifier for UI display (hero icons)status: Workflow status string - one of "draft", "published", or "archived"fields_definition: JSONB array of field definitionssettings: JSONB map of entity-specific settingscreated_by: User ID of the admin who created the entitydate_created: When the entity was createddate_updated: When the entity was last modified
Field Definition Structure
Each field in fields_definition is a map with:
type: Field type (text, textarea, number, boolean, date, select, etc.)key: Unique field identifier (snake_case)label: Display label for the fieldrequired: Whether the field is requireddefault: Default valuevalidation: Map of validation rulesoptions: Array of options (for select, radio, checkbox types)
Core Functions
Entity Management
list_entities/0- Get all entitieslist_active_entities/0- Get only active entitiesget_entity!/1- Get an entity by ID (raises if not found)get_entity_by_name/1- Get an entity by its namecreate_entity/1- Create a new entityupdate_entity/2- Update an existing entitydelete_entity/1- Delete an entity (and all its data)change_entity/2- Get changeset for forms
System Settings
enabled?/0- Check if entities system is enabledenable_system/0- Enable the entities systemdisable_system/0- Disable the entities systemget_config/0- Get current system configurationget_max_per_user/0- Get max entities per user limitvalidate_user_entity_limit/1- Check if user can create more entities
Usage Examples
# Check if system is enabled
if PhoenixKit.Modules.Entities.enabled?() do
# System is active
end
# Create a brand entity
# Note: fields_definition requires string keys, not atom keys
{:ok, entity} = PhoenixKit.Modules.Entities.create_entity(%{
name: "brand",
display_name: "Brand",
display_name_plural: "Brands",
description: "Brand content type for company profiles",
icon: "hero-building-office",
created_by: admin_user.id,
fields_definition: [
%{"type" => "text", "key" => "name", "label" => "Name", "required" => true},
%{"type" => "textarea", "key" => "tagline", "label" => "Tagline"},
%{"type" => "rich_text", "key" => "description", "label" => "Description", "required" => true},
%{"type" => "select", "key" => "industry", "label" => "Industry",
"options" => ["Technology", "Manufacturing", "Retail"]},
%{"type" => "date", "key" => "founded_date", "label" => "Founded Date"},
%{"type" => "boolean", "key" => "featured", "label" => "Featured Brand"}
]
})
# Get entity by name
entity = PhoenixKit.Modules.Entities.get_entity_by_name("brand")
# List all active entities
entities = PhoenixKit.Modules.Entities.list_active_entities()Summary
Functions
Returns an %Ecto.Changeset{} for tracking entity changes.
Creates a changeset for entity creation and updates.
Counts the total number of entity data records across all entities.
Counts the total number of entities in the system.
Counts the total number of entities created by a user.
Creates an entity.
Deletes an entity.
Disables data mirroring for all entities.
Disables definition mirroring for all entities.
Disables the entities system.
Enables data mirroring for all entities.
Enables definition mirroring for all entities.
Enables the entities system.
Checks if the entities system is enabled.
Gets the current entities system configuration.
Gets a single entity by integer ID or UUID.
Gets a single entity by integer ID or UUID.
Gets a single entity by its unique name.
Gets the maximum number of entities a single user can create.
Gets the mirror settings for an entity.
Gets summary statistics for the entities system.
Returns the list of active (published) entities.
Returns the list of entities ordered by creation date.
Lists all entities with their mirror status and data counts.
Checks if data mirroring is enabled for this entity.
Checks if definition mirroring is enabled for this entity.
Updates an entity.
Updates the mirror settings for an entity.
Validates that a user hasn't exceeded their entity creation limit.
Functions
Returns an %Ecto.Changeset{} for tracking entity changes.
Examples
iex> PhoenixKit.Modules.Entities.change_entity(entity)
%Ecto.Changeset{data: %PhoenixKit.Entities{}}Creates a changeset for entity creation and updates.
Validates that name is unique, fields_definition is valid, and all required fields are present. Automatically sets date_created on new records.
Counts the total number of entity data records across all entities.
Examples
iex> PhoenixKit.Modules.Entities.count_all_entity_data()
243Counts the total number of entities in the system.
Examples
iex> PhoenixKit.Modules.Entities.count_entities()
15Counts the total number of entities created by a user.
Examples
iex> PhoenixKit.Modules.Entities.count_user_entities(1)
5Creates an entity.
Examples
iex> PhoenixKit.Modules.Entities.create_entity(%{name: "brand", display_name: "Brand"})
{:ok, %PhoenixKit.Entities{}}
iex> PhoenixKit.Modules.Entities.create_entity(%{name: ""})
{:error, %Ecto.Changeset{}}Note: created_by is auto-filled with the first admin or user ID if not provided,
but only if at least one user exists in the system. If no users exist, the changeset
will fail with a validation error on created_by.
Deletes an entity.
Note: This will also delete all associated entity_data records due to the ON DELETE CASCADE constraint defined in the database migration (V17).
Examples
iex> PhoenixKit.Modules.Entities.delete_entity(entity)
{:ok, %PhoenixKit.Entities{}}
iex> PhoenixKit.Modules.Entities.delete_entity(entity)
{:error, %Ecto.Changeset{}}Disables data mirroring for all entities.
Examples
iex> PhoenixKit.Modules.Entities.disable_all_data_mirror()
{:ok, count}Disables definition mirroring for all entities.
Examples
iex> PhoenixKit.Modules.Entities.disable_all_definitions_mirror()
{:ok, count}Disables the entities system.
Sets the "entities_enabled" setting to false.
Examples
iex> PhoenixKit.Modules.Entities.disable_system()
{:ok, %Setting{}}Enables data mirroring for all entities.
Examples
iex> PhoenixKit.Modules.Entities.enable_all_data_mirror()
{:ok, count}Enables definition mirroring for all entities.
Examples
iex> PhoenixKit.Modules.Entities.enable_all_definitions_mirror()
{:ok, count}Enables the entities system.
Sets the "entities_enabled" setting to true.
Examples
iex> PhoenixKit.Modules.Entities.enable_system()
{:ok, %Setting{}}Checks if the entities system is enabled.
Returns true if the "entities_enabled" setting is true.
Examples
iex> PhoenixKit.Modules.Entities.enabled?()
falseGets the current entities system configuration.
Returns a map with the current settings.
Examples
iex> PhoenixKit.Modules.Entities.get_config()
%{enabled: false, max_per_user: 100, allow_relations: true, file_upload: false, entity_count: 0, total_data_count: 0}Gets a single entity by integer ID or UUID.
Returns the entity if found, nil otherwise.
Accepts:
- Integer ID (e.g., 123)
- UUID string (e.g., "550e8400-e29b-41d4-a716-446655440000")
- Integer string (e.g., "123")
Examples
iex> PhoenixKit.Modules.Entities.get_entity(123)
%PhoenixKit.Entities{}
iex> PhoenixKit.Modules.Entities.get_entity("550e8400-e29b-41d4-a716-446655440000")
%PhoenixKit.Entities{}
iex> PhoenixKit.Modules.Entities.get_entity(456)
nilGets a single entity by integer ID or UUID.
Raises Ecto.NoResultsError if the entity does not exist.
Examples
iex> PhoenixKit.Modules.Entities.get_entity!(123)
%PhoenixKit.Entities{}
iex> PhoenixKit.Modules.Entities.get_entity!(456)
** (Ecto.NoResultsError)Gets a single entity by its unique name.
Returns the entity if found, nil otherwise.
Examples
iex> PhoenixKit.Modules.Entities.get_entity_by_name("brand")
%PhoenixKit.Entities{}
iex> PhoenixKit.Modules.Entities.get_entity_by_name("invalid")
nilGets the maximum number of entities a single user can create.
Returns the system-wide limit for entity creation per user. Defaults to 100 if not set.
Examples
iex> PhoenixKit.Modules.Entities.get_max_per_user()
100Gets the mirror settings for an entity.
Returns a map with mirror_definitions and mirror_data booleans. Defaults to false if not explicitly set.
Examples
iex> PhoenixKit.Modules.Entities.get_mirror_settings(entity)
%{mirror_definitions: true, mirror_data: false}Gets summary statistics for the entities system.
Returns counts and metrics useful for admin dashboards.
Examples
iex> PhoenixKit.Modules.Entities.get_system_stats()
%{total_entities: 5, active_entities: 4, total_data_records: 150}Returns the list of active (published) entities.
Examples
iex> PhoenixKit.Modules.Entities.list_active_entities()
[%PhoenixKit.Entities{status: "published"}, ...]Returns the list of entities ordered by creation date.
Examples
iex> PhoenixKit.Modules.Entities.list_entities()
[%PhoenixKit.Entities{}, ...]Lists all entities with their mirror status and data counts.
Returns a list of maps suitable for the settings UI.
Examples
iex> PhoenixKit.Modules.Entities.list_entities_with_mirror_status()
[%{id: 1, name: "test", display_name: "Test", data_count: 8, mirror_definitions: true, mirror_data: false}, ...]Checks if data mirroring is enabled for this entity.
Examples
iex> PhoenixKit.Modules.Entities.mirror_data_enabled?(entity)
falseChecks if definition mirroring is enabled for this entity.
Examples
iex> PhoenixKit.Modules.Entities.mirror_definitions_enabled?(entity)
trueUpdates an entity.
Examples
iex> PhoenixKit.Modules.Entities.update_entity(entity, %{display_name: "Updated"})
{:ok, %PhoenixKit.Entities{}}
iex> PhoenixKit.Modules.Entities.update_entity(entity, %{name: ""})
{:error, %Ecto.Changeset{}}Updates the mirror settings for an entity.
Parameters
entity- The entity to updatemirror_settings- Map with keys "mirror_definitions" and/or "mirror_data"
Examples
iex> PhoenixKit.Modules.Entities.update_mirror_settings(entity, %{"mirror_definitions" => true})
{:ok, %PhoenixKit.Entities{}}Validates that a user hasn't exceeded their entity creation limit.
Checks the current number of entities created by the user against the system limit.
Returns {:ok, :valid} if within limits, {:error, reason} if limit exceeded.
Examples
iex> PhoenixKit.Modules.Entities.validate_user_entity_limit(1)
{:ok, :valid}
iex> PhoenixKit.Modules.Entities.validate_user_entity_limit(1)
{:error, "You have reached the maximum limit of 100 entities"}