Metadata

This page explains the concept of metadata in AtroCore and how developers can work with it to define and extend entity structures.

What Is Metadata?

Metadata in AtroCore describes the structure of an entity: its fields, relationships, indexes, and collection behavior. These definitions are stored in JSON files and used by the system to:

  • Generate database schemas and indexes
  • Understand which fields and links exist
  • Determine how fields are rendered in the UI
  • Enable filtering, sorting
  • Ensure consistency across modules

Example: Brand.json

In the Pim module, the entity Brand is defined in: /app/Resources/metadata/entityDefs/Brand.json

This file contains metadata like:

{
    "fields": {
        "name": {
            "type": "varchar",
            "required": true,
            "trim": true,
            "isMultilang": true
        },
        "description": {
            "type": "text",
            "required": false,
            "rowsMax": 4,
            "lengthOfCut": 400,
            "seeMoreDisabled": false,
            "readOnly": false,
            "tooltip": false,
            "isMultilang": true
        },
        "files": {
            "type": "linkMultiple",
            "layoutDetailDisabled": true,
            "massUpdateDisabled": true,
            "noLoad": true
        },
        "createdAt": {
            "type": "datetime",
            "readOnly": true
        },
        "modifiedAt": {
            "type": "datetime",
            "readOnly": true
        },
        "createdBy": {
            "type": "link",
            "readOnly": true,
            "view": "views/fields/user"
        },
        "modifiedBy": {
            "type": "link",
            "readOnly": true,
            "view": "views/fields/user"
        },
        "products": {
            "type": "linkMultiple",
            "layoutDetailDisabled": true,
            "layoutListDisabled": true,
            "massUpdateDisabled": true,
            "noLoad": true,
            "importDisabled": true
        },
        "code": {
            "type": "varchar",
            "trim": true,
            "unique": true
        }
    },
    "links": {
        "files": {
            "type": "hasMany",
            "relationName": "brandFile",
            "foreign": "brands",
            "entity": "File"
        },
        "createdBy": {
            "type": "belongsTo",
            "entity": "User"
        },
        "modifiedBy": {
            "type": "belongsTo",
            "entity": "User"
        },
        "products": {
            "type": "hasMany",
            "foreign": "brand",
            "entity": "Product"
        }
    },
    "collection": {
        "sortBy": "createdAt",
        "asc": false,
        "textFilterFields": [
            "name",
            "code"
        ]
    },
    "indexes": {
        "name": {
            "columns": [
                "name",
                "deleted"
            ]
        }
    }
}

How Metadata Is Used

AtroCore uses metadata in two main layers:

  • Database Layer: Metadata defines which fields and indexes should exist in the database.
  • Application Layer: Metadata tells the system how to render fields in the UI (e.g., varchar → input, text → textarea), how to filter/search, and how to manage relationships.

Merging Metadata

Metadata is merged into a single structure during system initialization:

  • Core metadata is loaded first.
  • Metadata from other modules is merged using array_merge, in the order modules are loaded.
  • Later modules can extend or override existing entity definitions. This means that the metadata you see in one file may not represent the full structure—other modules may add fields or links dynamically

Extending Metadata

There are two ways to extend metadata:

1. Static Extension

You can create a file with the same path in another module:

/app/Resources/metadata/entityDefs/Brand.json

This file will be merged with the original definition

2. Dynamic Extension via Listener

Use a Metadata.php listener to modify metadata programmatically. This is useful when:

  • Metadata should be added conditionally
  • Complex merging logic is required

Example: 🔗 Metadata.php in AtroPim module

Entity Manager and Custom Metadata

AtroCore includes an Entity Manager that allows users to:

  • Add fields and links to existing entities
  • Create entirely new entities

These changes are stored as metadata files in:

/data/metadata/entityDefs/

For example:

/data/metadata/entityDefs/Brand.json

These custom metadata files are loaded last, ensuring they override previous definitions. Developers should be aware of this loading order when debugging or extending entities.

Summary

  • Metadata defines entity structure for both DB and UI.
  • It is stored in JSON files and merged across modules.
  • You can extend metadata statically or dynamically.
  • Entity Manager-generated metadata is stored in /data/metadata and loaded last.
Table of contents