Installation

Epsicube is a modular application framework built on top of Laravel. It provides a robust architecture for building extensible systems composed of isolated modules, shared integrations, and configurable execution pipelines.

Global Requirements

Before installing Epsicube, ensure your environment meets these core requirements:

• PHP 8.4+
• Composer
• PHP Extensions:
  • intl: Required for advanced localization and string handling.
  • pcntl: Required for the Epsicube Worker to manage process signals.

---

Installation Guide

Choose the method that best fits your project needs:

New App (Starter Kit)

The fastest way to start. This uses the official Laravel installer to scaffold a project pre-configured with Epsicube.

1. Install Laravel Installer

   If you haven’t already, install the installer globally:

   composer global require laravel/installer

2. Scaffold Project

   Create a new project using the --using flag to pull the Epsicube starter kit:

   laravel new my-modular-app --using=epsicube/epsicube

3. Run with Docker (Optional)

   The starter kit includes a docker-compose.yml. To lift your environment:

   # Start containers
   docker compose up -d
   
   # Run migrations inside the container
   docker compose exec epsicube php artisan migrate
   
   # Access the container shell
   docker compose exec epsicube bash

Existing Application

Follow these steps to integrate Epsicube into an existing Laravel 12.x project.

1. Install via Composer

   Add the framework to your dependencies:

   composer require epsicube/framework

2. Inject Epsicube before Laravel bootstraps providers

   Epsicube now hooks into the native Laravel application lifecycle before provider registration. Update your bootstrap/app.php file:

   use Epsicube\Foundation\Actions\InjectEpsicube;
   use Illuminate\Foundation\Application;
   use Illuminate\Foundation\Bootstrap\LoadEnvironmentVariables;
   use Illuminate\Foundation\Configuration\Exceptions;
   use Illuminate\Foundation\Configuration\Middleware;
   
   return tap(Application::configure(basePath: dirname(__DIR__))
       ->withRouting(
           web: __DIR__.'/../routes/web.php',
           commands: __DIR__.'/../routes/console.php',
           health: '/up',
       )
       ->withMiddleware(function (Middleware $middleware): void {
           //
       })
       ->withExceptions(function (Exceptions $exceptions): void {
           //
       })->create(), function (Application $app) {
           $app->beforeBootstrapping(LoadEnvironmentVariables::class, InjectEpsicube::configure(...));
       });

3. Run Migrations

   Epsicube requires internal tables to manage the module registry and options store:

   php artisan migrate

Scheduler & Queue Configuration

Epsicube does not change how Laravel runs the scheduler and queues. Configure them as usual, following the Laravel documentation:

• Task Scheduling
• Queues

Some modules may register their own long-running processes, supervised by epsicube:work. See Manage Processes if you use such modules.

Verify Installation

Epsicube injects its metadata directly into the native Laravel about command. Run the following to ensure everything is operational:

php artisan about --only Epsicube

You should see an output similar to this:

Epsicube
Version	1.0.x

Next Steps

• Architectural Overview: Understand the modular philosophy.
• Writing a Module: Use the CLI to generate your first module.