README

Directavel helps using Directus as an administrative backend for Laravel. It provides some commands to programmatically define and version Directus collections, and sync them without touching your data tables.

Installation

Directavel requires PHP 8.0+, Laravel 10.x+ and Directus 9.x+. To get the latest version, simply require the project using Composer:

composer require 7ute/directavel

Once installed, if you are not using automatic package discovery, then you need to register the SevenUte\Directavel\DirectavelServiceProvider service provider in your config/app.php. You can also alias the facade:

        'Directavel' => SevenUte\Directavel\Facades\Directavel::class,

Directus must be installed and bootstraped, and the migrations must have been run already. You can bootstrap it by running the following in the directus project directory :

npx directus bootstrap
npx directus database migrate:latest

Configuration

To customize the directus configuration, you first must publish the config.

$ php artisan vendor:publish

This will create a config/directavel.php file in your app that you can modify to set your configuration. Make sure you check for changes to the original config file in this package between releases.

Collections

Each collection is defined by a PHP file named after the table we want to configure. The collections sits at the path set in the directavel.collections_path_pattern config entry.

A configuration files is composed as following :

// database/directus/collections/some_table.php

/**
 * That file will help generating a `some_table`
 * entry in the `directus_collections` table
 * with only the collection column filled.
 **/
return [
    /** The other columns of this `directus_collection` entry. */
    'attributes' => [],

    /** Each field will be its own row in the `directus_fields` table */
    'fields' => [],

    /**
     * The relationships that are not set in the fields
     * can be defined here. They will be inserted at
     * the end of the `directus_relations` table.
     **/
    'relations' => [],
]

To see an example, check the sample.php file in this package. You can also refer to the DirectusFields model for a list of available fields and some typing for your IDE, and the DirectusCollections and DirectusRelations for the available columns.

Presets

The general presets can be defined in a file at the path set in the directavel.presets_path config entry. Some default config for the directus_activity, directus_presets and directus_users views are included in the presets.php file of this project.

Usage

Once the collections are configured, you can use the facade in a migration, or use the command to trigger a full refresh of Directus collections / fields without touching your non-directus data tables.

Warning All your existing Activityn Collections, Fields, Presets, Relations and Revisions might be wiped, depending on your settings in the config file.

Commands

php artisan directavel:sync: Update the admin user, settings and presets, and synchronises the collections and fields
php artisan directavel:cache:clear: Clears Directus inner cache

Facade

use SevenUte\Directavel\Facades\Directavel;

Directavel::updateProjectAdmin()
    ->updateProjectPresets()
    ->updateThemeCss()
    ->synchronizeDatabase()
    ->clearCache();

updateProjectAdmin: Updates the Directus admin user ;
updateProjectLog: Updates the Directus logo ;
updateProjectPresets: Reload the non-user presets from the file defined in the directus.presets_path config ;
updateThemeCss: Applies the theme color and extra CSS ;
synchronizeDatabase: Loads the collections, fields and relations into the directus tables, wiping those set in the directus.wipe config before ;
clearCache: Clears Directus collection cache to prevent "inexistant field" errors ;
loadTailwindThemeColors: Reloads the Tailwind theme colors ;
loadCurrentAdminId: Reloads the Directus admin user ID.

Tests

This package is tested with Pest. To run the tests, use composer tests.

Contributions

Pull requests are welcome. Pull requests with tests are even more welcome.

Security

If you discover a security vulnerability within this package, please send an e-mail to Julien Cauvin at contact@7ute.fr. All security vulnerabilities will be promptly addressed.

License

Directavel is licensed under The MIT License (MIT).

7ute / directavel

Maintainers

Details