Installation

Installing Blackcube CMS in a Yii2 project

Integrating Blackcube into an existing or new Yii2 project is done entirely via Composer. The installation process includes adding two packages (core and admin), configuring modules in your application, then running migrations to create all the necessary database structure. Blackcube commands then allow you to initialize the RBAC system and create your first administrator account to access the backoffice. The entire process takes a few minutes and does not modify your Yii2 project structure.

This guide covers the complete installation of Blackcube, from adding Composer packages to verifying functionality and initial configuration.

Prerequisites

  1. PHP 8.2 or higher
  2. MySQL 5.7+ or MariaDB 10.2+ (PostgreSQL also supported)
  3. Composer installed globally
  4. A Yii2 project existing (basic or advanced) or new
  5. Apache or Nginx configured

Installation via Composer

Blackcube consists of two packages:

  1. blackcube/core: The CMS core (required)
  2. blackcube/admin: The administration interface (optional but recommended)

In your Yii2 project, install the packages:

    composer require blackcube/core
composer require blackcube/admin

Module Configuration

Add the Blackcube modules in your webapp configuration:

    'modules' => [
    // Core module (required)
    'blackcube' => [
        'class' => blackcube\core\Module::class,
        'slugSensitive' => false, // false = /général and /general are identical
    ],
    
    // Admin module (optional but recommended)
    'bo' => [
        'class' => blackcube\admin\Module::class,
        'adminTemplatesAlias' => '@app/admin',
        'additionalAssets' => [],
        'modules' => [],
    ],
]

Core Module Options

    'blackcube' => [
    'class' => blackcube\core\Module::class,
    
    // URL accent sensitivity
    'slugSensitive' => false, // false = /général and /general are identical
    
    // Custom cache component (optional)
    // 'cache' => 'cache',
]

Admin Module Options

    'bo' => [
    'class' => blackcube\admin\Module::class,
    
    // Alias to your custom administration templates
    'adminTemplatesAlias' => '@app/admin',
    
    // Additional CSS/JS assets for the backoffice
    'additionalAssets' => [],
    
    // Admin sub-modules (for plugins)
    'modules' => [],
    
    // Custom cache component (optional)
    // 'cache' => 'cache',
]

Creating the Base Structure

Run migrations to create Blackcube tables:

    # Database migration
php yii.php migrate
# RBAC rights initialization
php yii.php bc:init
# Initial administrator creation
php yii.php bc:admin/create

Info

These commands create all necessary tables (nodes, composites, blocs, slugs, etc.) and initialize Blackcube. Only necessary at startup.

Web Server Configuration

Apache

Create or modify your .htaccess file in the public folder:

    RewriteEngine on
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
RewriteRule . index.php

Nginx

Minimal configuration:

    location / {
    try_files $uri $uri/ /index.php?$args;
}

Installation Verification

Backoffice Access

Access the administration interface:

    http://your-site.local/bo

Log in with the created credentials.

Frontend Verification

Create a test controller:

    <?php
namespace app\controllers;

use blackcube\core\components\BlackcubeController;

class SiteController extends BlackcubeController
{
    public function actionIndex()
    {
        return $this->render('index');
    }
}

Warning

Blackcube integrates into any Yii2 structure: basic, advanced or custom. Your project structure remains unchanged.

Key Points to Remember

  1. Quick installation: A few Composer commands and migrations are enough to install Blackcube in any Yii2 project
  2. Two packages: Core is required, admin is recommended to access the backoffice
  3. Preserved structure: Blackcube does not impose any modification to your Yii2 project structure
  4. Minimal configuration: Only the two modules (core and admin) need to be added to your configuration
  5. Integrated RBAC: The permissions system is initialized automatically with bc:init

Troubleshooting

Migration Error

Problem: The migrate command fails

Solutions:

  1. Check your database configuration
  2. Make sure the database exists and the user has necessary rights
  3. Check that PHP has the MySQL/PDO extension enabled

404 Error on /bo

Problem: The /bo page returns a 404 error

Solutions:

  1. Check that the bo module is properly configured
  2. Check the web server configuration
  3. Clear the cache: php yii.php cache/flush-all

"Table not found" Error

Problem: SQL error indicating a table does not exist

Solutions:

  1. Make sure you ran the migrations
  2. Check that all Blackcube migrations have been applied
  3. When in doubt, check the logs

bc:init command not found

Problem: The bc:init command returns "Unknown command"

Solutions:

  1. Check that blackcube/core is properly installed via Composer
  2. Check that the blackcube module is configured
  3. Run composer dump-autoload

Support

If you encounter unresolved issues:

  1. Consult the complete documentation
  2. Open an issue on GitHub
  3. Check existing issues to see if the problem is known

<< Yii2/Blackcube Configuration >>