Laravel agent upgrade to v3

The purpose of this note is to help developers to upgrade their Laravel agent from v2 to v3. Please read carefully and integrate the following breaking changes to ensure a smooth update.​

Upgrade the forestadmin/laravel-forestadmin agent to v3.

This upgrade allows users to cache their Laravel configuration with the native command php artisan config:cache

Upgrading to v3

To upgrade to version 3, follow these steps and then update your project as shown in the Breaking Changes section below.

Step 1: Install the new version

In your composer.json file specify the new package version:

"forestadmin/laravel-forestadmin": "^3.0"

Then update the package with the following command:

composer update forestadmin/laravel-forestadmin

Step 2: Publish the configuration files from our package to your application

php artisan vendor:publish --provider="ForestAdmin\LaravelForestAdmin\ForestServiceProvider" --tag=forest --tag=config

At this stage you should have 2 new files in your application:

  • config/forest.php

  • forest/forest_admin.php

Step 3: Remove the old configuration file

Take any customization you may have done in the old configuration file config/forest_admin.php and put it in the new one forest/forest_admin.php. Then delete the old configuration file config/forest_admin.php.

Step 4: Clear the cache

php artisan cache:clear && php artisan config:clear

Step 5: Launch your app

Restart your application.

Breaking Changes

The previous configuration prevented caching the configuration in Laravel with the command php artisan config:cache To comply with Laravel standards, agent configuration and settings are moved into 2 separate files.

Settings

The settings are loaded into the package using the Laravel env() helper.

Agent configuration

<?php

use ForestAdmin\AgentPHP\Agent\Builder\AgentFactory;
use ForestAdmin\AgentPHP\DatasourceEloquent\EloquentDatasource;

return static function () {
    $forestAgent = app()->make(AgentFactory::class);
    $forestAgent->addDatasource(
        new EloquentDatasource(
            [
                'driver'   => env('DB_CONNECTION'),
                'host'     => env('DB_HOST'),
                'port'     => env('DB_PORT'),
                'database' => env('DB_DATABASE'),
                'username' => env('DB_USERNAME'),
                'password' => env('DB_PASSWORD'),
                // OR
                // 'url' => env('DATABASE_URL'),
            ]
        ),
    );
};

Settings

The settings are loaded from this new file using the Laravel config() helper. In the Laravel ecosystem, if you use the env() helper outside a configuration file, it returns null if the configuration is cached.

<?php
# config/forest.php

return [
    'debug'                => env('FOREST_DEBUG', true),
    'authSecret'           => env('FOREST_AUTH_SECRET'),
    'envSecret'            => env('FOREST_ENV_SECRET'),
    'forestServerUrl'      => env('FOREST_SERVER_URL', 'https://api.forestadmin.com'),
    'isProduction'         => env('FOREST_ENVIRONMENT', 'dev') === 'prod',
    'prefix'               => env('FOREST_PREFIX', 'forest'),
    'permissionExpiration' => env('FOREST_PERMISSIONS_EXPIRATION_IN_SECONDS', 300),
    'cacheDir'             => storage_path('framework/cache/data/forest'),
    'schemaPath'           => base_path() . '/.forestadmin-schema.json',
    'projectDir'           => base_path(),
];

Agent configuration

<?php
# forest/forest_admin.php

use ForestAdmin\AgentPHP\Agent\Builder\AgentFactory;
use ForestAdmin\AgentPHP\DatasourceEloquent\EloquentDatasource;

return static function () {
    $defaultDB = config('database.default');
    $forestAgent = app()->make(AgentFactory::class);

    $forestAgent->addDatasource(
        new EloquentDatasource(config('database.connections.' . $defaultDB)),
    );
};

Last updated

Was this helpful?