thaiphuong/laravel-brain-cms

Dynamic CMS for managing any Eloquent model via JSON configuration

dev-main 2026-04-13 17:47 UTC

Requires

• php: ^8.1
• illuminate/cache: ^9.0|^10.0|^11.0
• illuminate/database: ^9.0|^10.0|^11.0
• illuminate/filesystem: ^9.0|^10.0|^11.0
• illuminate/routing: ^9.0|^10.0|^11.0
• illuminate/support: ^9.0|^10.0|^11.0
• illuminate/validation: ^9.0|^10.0|^11.0
• spatie/laravel-permission: ^5.0|^6.0

MIT

• Thai Phuong

README

Dynamic CMS package for managing any Eloquent model via JSON configuration. Define your model's list view, form fields, actions, and permissions — all stored as JSON in the database.

Requirements

• PHP >= 8.1
• Laravel >= 9.0
• spatie/laravel-permission >= 5.0

Installation

1. Install via Composer

From a local path (during development):

Add the repository to your project's composer.json:

{
    "repositories": [
        {
            "type": "path",
            "url": "../laravel-brain-cms"
        }
    ]
}

Then install:

composer require thaiphuong/laravel-brain-cms

From a Git repository:

{
    "repositories": [
        {
            "type": "vcs",
            "url": "https://github.com/thaiphuong/laravel-brain-cms.git"
        }
    ]
}

2. Publish Config

php artisan vendor:publish --tag=brain-cms-config

This publishes config/brain.php where you can configure:

• guard — Authentication guard (default: admin)
• master_role — Role name that bypasses all permission checks
• route_prefix — API route prefix (default: adminpt/api/brain)
• middleware — Route middleware (default: ['web', 'auth:admin'])
• storage_disk — File upload disk
• model_scan_path — Directory to scan for Eloquent models
• model_namespace — Namespace prefix for models
• user_models — User model classes for audit log relationships
• cache_ttl — Config cache duration in seconds
• export_path — Directory for config export/import

3. Run Migrations

php artisan migrate

This creates brains and brain_audit_logs tables.

4. Publish Vue Frontend Assets (optional)

php artisan vendor:publish --tag=brain-cms-assets

This publishes Vue components to resources/js/vendor/brain-cms/. You can then import them in your Vue app.

Frontend Integration

The package provides Vue 3 components that expect these peer dependencies in your host application:

• Vue 3 with Composition API
• PrimeVue 4.x (DataTable, Dialog, InputText, Button, etc.)
• Pinia 2.x (state management)
• Tailwind CSS 3.x
• TipTap (for EditorField)

Required Host App Composables/Stores

The published Vue files import from @/ paths and expect:

• @/composables/useApi — Axios wrapper with CSRF and base URL
• @/stores/notification — useNotificationStore() with showSuccess(), showError()
• @/stores/app — useAppStore() with storageLink, dateFormats
• @/utils/format — formatDate(), capitalizeFirst()
• @/utils/xss — escapeHtml(), escapeAttr()

Vue Router Setup

Add the Brain list page route in your router:

import BrainListPage from '@/vendor/brain-cms/pages/BrainListPage.vue';

const routes = [
    {
        path: '/brain/:alias',
        name: 'brain-list',
        component: BrainListPage,
    },
];

Making Models Brain-Compatible

Basic Usage

Any Eloquent model can be managed by Brain. Just register it via the Brain admin UI or import a config JSON.

Lifecycle Hooks

Implement BrainCompatible for custom behavior:

use Phuong\BrainCms\Contracts\BrainCompatible;
use Phuong\BrainCms\Traits\BrainCompatibleTrait;

class Product extends Model implements BrainCompatible
{
    use BrainCompatibleTrait;

    public function brainBeforeCreate(array $data): array
    {
        $data['slug'] = Str::slug($data['name']);
        return $data;
    }

    public function brainBeforeDelete(): bool
    {
        return $this->orders()->count() === 0;
    }
}

Custom List Data

Implement BrainListable for custom list queries:

use Phuong\BrainCms\Contracts\BrainListable;

class User extends Model implements BrainListable
{
    public function getList(array $inputs, array $config): array
    {
        // Custom query logic
        return [
            'data' => $items,
            'recordsTotal' => $total,
            'recordsFiltered' => $filtered,
        ];
    }
}

Events

Listen to Brain CRUD events in your application:

• Phuong\BrainCms\Events\BrainRecordCreating — Before create (data modifiable)
• Phuong\BrainCms\Events\BrainRecordCreated — After create
• Phuong\BrainCms\Events\BrainRecordUpdating — Before update (data modifiable)
• Phuong\BrainCms\Events\BrainRecordUpdated — After update
• Phuong\BrainCms\Events\BrainRecordDeleting — Before delete (cancellable)
• Phuong\BrainCms\Events\BrainRecordDeleted — After delete

Artisan Commands

# Export Brain configs to JSON files
php artisan brain:export {alias?}

# Import Brain configs from JSON files
php artisan brain:import {alias?} {--dry}

# Show differences between DB and files
php artisan brain:diff {alias?}

API Routes

All routes are registered under the configured prefix (default: adminpt/api/brain):

Method	URI	Description
GET	/	List records (DataTables format)
GET	/get-table-config	Get table/form configuration
GET	/get-record-detail	Get record for editing
GET	/get-relationship-options	Get relationship field options
GET	/search-field-options	Search options (AJAX pagination)
POST	/create	Create record
POST	/update	Update record
DELETE	/delete	Delete record
POST	/create-update-feature	Create/update Brain config
GET	/get-table-column-list	Get model's table columns
GET	/get-feature-form-data	Get Brain feature form data

License

MIT