ArtisanPack UI Docs

This guide will walk you through installing and setting up the CMS Framework in your Laravel application. - PHP 8.3 or higher - Laravel 12.0 or higher -...

This guide will walk you through installing and setting up the CMS Framework in your Laravel application.

Requirements

PHP 8.3 or higher
Laravel 12.0 or higher
MySQL 8.0+ or PostgreSQL 10.0+

Installation Steps

1. Install via Composer

composer require artisanpack-ui/cms-framework

2. Publish Configuration

Publish the configuration files to customize the framework settings:

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

This creates four files in your application:

config/artisanpack/cms-framework.php — core framework settings
config/cms/themes.php — theme discovery and caching
config/cms/plugins.php — plugin discovery and loading
config/cms/updates.php — self-updater settings

To take one module's config in isolation, use cms-themes-config, cms-plugins-config or cms-updates-config instead — each publishes exactly one file. (artisanpack-package-config also publishes the main config file, but it is shared across the ArtisanPack UI ecosystem and will publish every other installed ArtisanPack UI package's config alongside it.)

3. Run Migrations

The package includes migrations for roles, permissions, and pivot tables:

php artisan migrate

This will create the following tables:

roles - Store user roles
permissions - Store individual permissions
permission_role - Many-to-many relationship between permissions and roles
role_user - Many-to-many relationship between roles and users

4. Configure Your User Model

Add the HasRolesAndPermissions trait to your User model:

<?php

namespace App\Models;

use ArtisanPackUI\CMSFramework\Modules\Users\Models\Concerns\HasRolesAndPermissions;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasRolesAndPermissions;
    
    // Your existing User model code...
}

5. Update Configuration

Edit the config/artisanpack/cms-framework.php file to point to your User model:

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

6. Register API Routes

The package automatically registers API routes under the /api/v1 prefix. If you need to customize this, you can disable auto-discovery and manually register routes.

Verification

To verify the installation was successful:

Check that the tables were created:

php artisan tinker
>>> \Schema::hasTable('roles')
=> true
>>> \Schema::hasTable('permissions')
=> true

Test the API endpoints:

# List users (should return empty pagination)
curl -X GET http://your-app.test/api/v1/users

Next Steps

Configuration - Learn about configuration options
Quick Start - Create your first user and role
User Management - Understand user management features

Troubleshooting

Common Issues

Migration Errors If you encounter migration errors, ensure your database connection is properly configured and the database exists.

Route Conflicts If you have existing /api/v1/users routes, you may need to customize the route prefix or disable auto-registration.

User Model Issues Make sure your User model includes the HasRolesAndPermissions trait and is properly configured in the config file.

Manual Installation

If you prefer to manually register the service provider:

// config/app.php
'providers' => [
    // Other providers...
    ArtisanPackUI\CMSFramework\CMSFrameworkServiceProvider::class,
],

Need help? Check the Developer Guide for advanced configuration options.

Installation Guide