Scope and context

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

Actions can have 3 different scopes: Single, Bulk, and Global.

The scope of an action defines how it can be triggered and which records it will target.

-	Single	Bulk	Global
Targeted records	One at a time	All selected and matching the current segment / search	Your choice among all matching the current segment / search
Can be triggered from the List View	When a single record is selected	When one or more records are selected	✅
Can be triggered from the Details View or Summary View	✅	✅	🚫

The context object

The context object is central to writing Actions controllers in Forest Admin. There are two different object context. The first ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\Context\ActionContext is used for the actions of type Bulk or Global. And the second ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\Context\ActionContextSingle is only used with the actions of type Single

It is the bridge between all the data that your agent has access to and the action's execution. It is passed to the execute function as the first argument and provides access to the following properties:

• getRecord(fieldNames) (or getRecords(fieldNames) for Bulk and Global Actions)

• getRecordId() (or getRecordIds() for Bulk and Global Actions)

• getCollection() the collection on which the action is declared, which can be queried using the Forest Admin Query Interface.

• getDatasource() the composite data source who contains all your collections, which can be queried using the Forest Admin Query Interface

• getFilter() a filter that can be used to query the collection, and which is based on action scope and the list of selected records.

• getCaller() an object containing information about the user who is performing the action (including email, username, timezone, team, role …)

• hasFieldChanged(fieldName) the name of the field who has changed in the UI. See an example of usage

changedField was deprecated in favor of hasFieldChanged($fieldName) starting from forestadmin/php-datasource-customizer 1.7.2

Example 1: Getting data from the selected records

We can simply use the getRecord(fieldNames) method to get any column from the selected record or a relation.

use ForestAdmin\AgentPHP\DatasourceCustomizer\CollectionCustomizer;
use ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\BaseAction;
use ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\Context\ActionContextSingle;
use ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\ResultBuilder;
use ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\Types\ActionScope;

$forestAgent->customizeCollection(
    'User',
    function (CollectionCustomizer $builder) {
        $builder->addAction(
       	    'Call me John in the server logs',
       	    new BaseAction(
       	        scope: ActionScope::SINGLE,
       	        execute: function (ActionContextSingle $context) {
       	            $record = $context->getRecord(['name']);
       	            if ($record['name'] === 'John') {
       	                // log with your favorite logger => 'hi John'
       	            } else {
       	                // log with your favorite logger => 'You are not John!'
       	            }
       	        }
       	    )
       	);
    }
);

Example 2: Updating a field of the selected record

For simple queries, use $context->getCollection() and $context->getFilter() to query the collection.

Those are instances of objects from the Forest Admin Query Interface.

use ForestAdmin\AgentPHP\DatasourceCustomizer\CollectionCustomizer;
use ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\BaseAction;
use ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\Context\ActionContextSingle;
use ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\ResultBuilder;
use ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\Types\ActionScope;

$forestAgent->customizeCollection(
    'User',
    function (CollectionCustomizer $builder) {
    	$builder->addAction(
    	    'Mark as live',
    	    new BaseAction(
    	        scope: ActionScope::SINGLE,
    	        execute: function(ActionContextSingle $context) {
    	            $context->getCollection()->update($context->getFilter(), ['name' => 'foo']);
    	        }
    	    )
    	);
    }
);

Example 3: Coding any business logic

Forest Admin does not impose any restriction on the handler: you are free to write the execute handler to fit your use case.

You are free to call external APIs, query your database, or perform any work in action handlers.

use ForestAdmin\AgentPHP\DatasourceCustomizer\CollectionCustomizer;
use ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\BaseAction;
use ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\Context\ActionContextSingle;
use ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\ResultBuilder;
use ForestAdmin\AgentPHP\DatasourceCustomizer\Decorators\Actions\Types\ActionScope;

$forestAgent->customizeCollection(
    'User',
    function (CollectionCustomizer $builder) {
    	$builder->addAction(
    	    'Mark as live',
    	    new BaseAction(
    	        scope: ActionScope::SINGLE,
    	        execute: function(ActionContextSingle $context) {
    	            $client = new GuzzleHttp\Client();
    	            $res = $client->get('http://my-api.com/mark-as-live');
    	        }
            )
        );
    }
);