php-framework/packages/core-php/README.md

Core PHP Framework

The core framework package providing event-driven architecture, module system, and foundational features for building modular Laravel applications.

Installation

composer require host-uk/core

Key Features

Event-Driven Module System

Modules declare lifecycle events they're interested in and are only loaded when needed:

class Boot
{
    public static array $listens = [
        WebRoutesRegistering::class => 'onWebRoutes',
        AdminPanelBooting::class => 'onAdmin',
    ];
}

Multi-Tenant Data Isolation

Automatic workspace scoping for Eloquent models:

use Core\Mod\Tenant\Concerns\BelongsToWorkspace;

class Product extends Model
{
    use BelongsToWorkspace;
}

// Automatically scoped to current workspace
$products = Product::all();

Actions Pattern

Single-purpose business logic classes with dependency injection:

use Core\Actions\Action;

class CreateOrder
{
    use Action;

    public function handle(User $user, array $data): Order
    {
        return Order::create($data);
    }
}

$order = CreateOrder::run($user, $validated);

Activity Logging

Built-in audit trails for model changes:

use Core\Activity\Concerns\LogsActivity;

class Order extends Model
{
    use LogsActivity;

    protected array $activityLogAttributes = ['status', 'total'];
}

Seeder Auto-Discovery

Automatic seeder ordering via attributes:

#[SeederPriority(10)]
#[SeederAfter(FeatureSeeder::class)]
class PackageSeeder extends Seeder
{
    public function run(): void
    {
        // ...
    }
}

HLCRF Layout System

Data-driven composable layouts:

use Core\Front\Components\Layout;

$page = Layout::make('HCF')
    ->h('<nav>Navigation</nav>')
    ->c('<article>Content</article>')
    ->f('<footer>Footer</footer>');

Lifecycle Events

Event	Purpose
WebRoutesRegistering	Public web routes
AdminPanelBooting	Admin panel routes
ApiRoutesRegistering	REST API endpoints
ClientRoutesRegistering	Authenticated client routes
ConsoleBooting	Artisan commands
McpToolsRegistering	MCP tool handlers
FrameworkBooted	Late-stage initialization

Configuration

Publish the configuration:

php artisan vendor:publish --tag=core-config

Configure in config/core.php:

return [
    'module_paths' => [
        app_path('Core'),
        app_path('Mod'),
    ],
    'workspace_cache' => [
        'enabled' => true,
        'ttl' => 3600,
    ],
];

Artisan Commands

php artisan make:mod Commerce      # Create module
php artisan make:website Marketing # Create website
php artisan make:plug Stripe       # Create plugin

Requirements

• PHP 8.2+
• Laravel 11+ or 12+

Documentation

• Main Documentation
• Patterns Guide
• HLCRF Layout System

Changelog

See changelog/2026/jan/features.md for recent changes.

License

EUPL-1.2 - See LICENSE for details.