Configuration

The CMS Framework provides flexible configuration options to customize its behavior for your specific application needs.

Configuration Files

The framework publishes five configuration files. Publish all of them with the umbrella tag:

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

The main configuration file is config/artisanpack/cms-framework.php, which carries user_model and openapi. The "Advanced Configuration" sections below describe code-level customization rather than keys in that file.

The four cms-*-config tags each publish exactly the one file beside them. artisanpack-package-config is shared across the whole ArtisanPack UI ecosystem — it publishes this framework's config and the config of every other installed ArtisanPack UI package.

Configuration Options

User Model

The most important configuration option is specifying your application's User model:

<?php
return [
    /*
    |--------------------------------------------------------------------------
    | User Model
    |--------------------------------------------------------------------------
    |
    | This is the model that your application uses for users. It will be used
    | by the CMS framework to establish relationships and handle user logic.
    | You should update this value to point to your app's User model.
    |
    */
    'user_model' => \App\Models\User::class,
];

Requirements for User Model

Your User model must:

1. Include the HasRolesAndPermissions trait:

use ArtisanPackUI\CMSFramework\Modules\Users\Models\Concerns\HasRolesAndPermissions;

class User extends Authenticatable
{
    use HasRolesAndPermissions;
    // ...
}

2. Have the required fillable fields:

protected $fillable = [
    'name',
    'email',
    'password',
    // other fields...
];

3. Use password hashing (usually already included in Laravel's User model):

protected $hidden = [
    'password',
    'remember_token',
];

protected function casts(): array
{
    return [
        'email_verified_at' => 'datetime',
        'password' => 'hashed',
    ];
}

Admin Page Middleware

Since 2.13.0. Every admin page registered through AdminPageManager, including pages added by plugins, sits behind the cms.admin.middleware stack, with the page's can:{capability} gate appended:

// config/cms/admin.php
return [
    'middleware' => [
        'web',
        'auth',
        'verified',
        'two-factor',
    ],
];

Set it to match the stack your own admin routes use, so plugin pages can't be reached by users who haven't verified their email or completed two-factor enrolment. Keep an authentication middleware ( auth or auth:<guard> ) in the list. An empty list, or one with no non-empty strings, falls back to web + auth, but a non-empty list without auth ( e.g. ['web'] ) is used as-is and leaves admin pages unauthenticated. The ap.cmsFramework.admin.middleware filter can change the stack at runtime. See Admin Authorization.

Plugin Framework Cache Clearing

cms.plugins.autoClearFrameworkCaches ( env PLUGINS_AUTO_CLEAR_FRAMEWORK_CACHES, default false ) runs route:clear, config:clear and view:clear after a plugin is activated, deactivated or deleted, and since 2.13.0 after an inactive plugin is updated ( an active plugin's update already clears through its deactivate/activate ). It's convenient in development, but in production it deletes the compiled caches that route:cache / config:cache built.

Host Application Version

cms.plugins.appVersion ( env CMS_APP_VERSION, default null ), 2.14.0, is the host application's own semver version. A plugin's min_app_version manifest key is compared against it on activation. The framework cannot detect it, so set CMS_APP_VERSION, or set the key from a service provider's register() method: config( [ 'cms.plugins.appVersion' => config( 'keystone.version' ) ] ). Don't read another file's key with config() inside config/cms/plugins.php: config files load in name order, so the value may not exist yet and resolves to null. While it is null, min_app_version checks are skipped with a logged warning and the ap.cmsFramework.plugin.versionCheckSkipped action. See Versioning & host compatibility.

Plugin Asset Route

cms.plugins.assetRoute ( env CMS_PLUGINS_ASSET_ROUTE, default true ), 2.14.0, registers the public GET /plugins/{slug}/assets/{path} route ( plugins.assets ) that serves the build of a plugin whose federated_module.entry is a relative path. Set it to false when the host serves plugin assets itself. A host with a GET catch-all route must exclude the plugins/ prefix from it. See Serving your bundle.

Advanced Configuration

Custom Route Prefix

By default, the framework registers routes under /api/v1. To customize this, you can disable auto-discovery and manually register routes in your RouteServiceProvider:

// In your RouteServiceProvider
use ArtisanPackUI\CMSFramework\Modules\Users\Http\Controllers\UserController;

Route::prefix('api/v2')->group(function () {
    Route::apiResource('users', UserController::class);
});

Database Table Names

The framework uses Laravel's default naming conventions:

• users - Your existing users table
• roles - Created by framework migration
• permissions - Created by framework migration
• role_user - Pivot table for user-role relationships
• permission_role - Pivot table for role-permission relationships

To customize table names, you can modify the migrations before running them or extend the models.

Validation Rules

The UserController uses built-in validation rules:

For user creation:

• name: required, string, max 255 characters
• email: required, string, email format, max 255 characters, unique in users table
• password: required, string, minimum 8 characters

For user updates:

• All fields are optional (using sometimes rule)
• Email uniqueness excludes the current user being updated

To customize validation, extend the UserController or create your own controller.

Environment Variables

While the framework doesn't define specific environment variables, you can reference them in your configuration:

// config/artisanpack/cms-framework.php
return [
    'user_model' => env('CMS_USER_MODEL', \App\Models\User::class),
];

Then in your .env file:

CMS_USER_MODEL="App\\Models\\CustomUser"

Multiple User Types

If your application has multiple user types, you can create different configurations:

// config/artisanpack/cms-framework.php
return [
    'user_model' => \App\Models\User::class,
    'admin_model' => \App\Models\Admin::class, // Custom configuration
];

Service Provider Configuration

The framework's service provider automatically:

• Loads migrations from database/migrations
• Registers API routes under /api/v1
• Publishes configuration files
• Merges configuration with application config

Testing Configuration

For testing, the framework uses the configured user model. In your tests, ensure you're using the same model:

// In your test setup
$userModel = config('cms-framework.user_model');
$user = $userModel::factory()->create();

Next Steps

• Quick Start - Get started with basic usage
• User Management - Learn about user management features
• Developer Guide - Advanced customization options

Configuration Examples

Basic Setup

return [
    'user_model' => \App\Models\User::class,
];

Custom User Model

return [
    'user_model' => \App\Models\CustomUser::class,
];

For more advanced configuration options, see the Developer Guide.