Structure declaration

This is the official documentation of the forestadmin/laravel-forestadmin v2+ and forestadmin/symfony-forestadmin PHP agents.

Creating a custom data source always starts with declaring the structure of the data

• Which collections are present?

• What fields do they contain?

• What are their types?

Columns

Examples

<?php

use ForestAdmin\AgentPHP\DatasourceToolkit\Collection;
use ForestAdmin\AgentPHP\DatasourceToolkit\Components\Contracts\DatasourceContract;
use ForestAdmin\AgentPHP\DatasourceToolkit\Components\Query\ConditionTree\Operators;
use ForestAdmin\AgentPHP\DatasourceToolkit\Schema\ColumnSchema;
use ForestAdmin\AgentPHP\DatasourceToolkit\Schema\Relations\ManyToManySchema;
use ForestAdmin\AgentPHP\DatasourceToolkit\Schema\Relations\ManyToOneSchema;

class MovieCollection extends Collection
{
    public function __construct(DatasourceContract $datasource)
    {
        parent::__construct(
            $datasource,
            'Movie'
        );

        $this->addField('id', new ColumnSchema(
            columnType: 'Number',
            filterOperators: [],
            isPrimaryKey: true
        ));

        $this->addField('title', new ColumnSchema(
            columnType: 'String',
            filterOperators: [],
            validation: [
                ['operator' => Operators::PRESENT],
            ]
        ));

        $this->addField('mpa_rating', new ColumnSchema(
            columnType: 'Enum',
            defaultValue: 'G',
            enumValues: ['G', 'PG', 'PG-13', 'R', 'NC-17']
        ));

        $this->addField('stars', new ColumnSchema(
            columnType: [
                [
                    'firstName' => 'String',
                    'lastName'  => 'String',
                ],
            ]
        ));
    }
}

Typing

The typing system for columns is the same as the one used when declaring fields in the agent customization step.

You can read all about it in "Under the hood > Data Model > Typing".

Validation

When using primitive type fields, Forest Admin supports declaring a validation clause, which will be imported into the UI of the admin panel to validate records before creating/updating them.

The API for validation is the same as with condition trees, besides the fact that there is no "field" entry.

{
  "aggregator": "and",
  "conditions": [
    { "operator": "present" },
    { "operator": "like", "value": "found%" },
    { "operator": "today" }
  ]
}

Relationships

Only intra-data source relationships should be declared at the collection level.

For inter-data source relationships, you should use jointures at the customization step.

You can declare relationships at the collection level, but that means that the data source you are making is responsible for handling them.

This will work out of the box for data sources using the "local-cache" strategy, however, please read "Intra-data source Relationships", before starting with the "query translation" strategy.

Examples

<?php

use ForestAdmin\AgentPHP\DatasourceToolkit\Collection;
use ForestAdmin\AgentPHP\DatasourceToolkit\Components\Contracts\DatasourceContract;
use ForestAdmin\AgentPHP\DatasourceToolkit\Schema\ColumnSchema;
use ForestAdmin\AgentPHP\DatasourceToolkit\Schema\Relations\ManyToManySchema;
use ForestAdmin\AgentPHP\DatasourceToolkit\Schema\Relations\ManyToOneSchema;

class MovieCollection extends Collection
{
    public function __construct(DatasourceContract $datasource)
    {
        // [...]

        $this->addField('director', new ManyToOneSchema(
            foreignKey: 'directorId',
            foreignKeyTarget: 'id',
            foreignCollection: 'People'
        ));

        $this->addField('actors', new ManyToManySchema(
            originKey: 'movieId',
            originKeyTarget: 'id',
            foreignKey: 'actorId',
            foreignKeyTarget: 'id',
            foreignCollection: 'People',
            throughCollection: 'ActorsOnMovies'
        ));

Typing

The typing system for relationships is the same as the one used when declaring jointures in the agent customization step.

You can read all about it in "Under the hood > Data Model > Relationships".