type

Knowledge Pack

title

CorePHP Framework

description

Reference for CorePHP — the PHP framework for Lethean PHP applications

author

Mistral Vibe

version

1.0.0

created

2026-06-17 14:50:00 UTC

CorePHP knowledge pack

Module: dappco.re/php/* Repository: core-php + core-{module} per module

CorePHP is the PHP framework for the Lethean ecosystem, providing a modular architecture with Laravel-like conventions. Everything is a module. Every module is self-contained. Every module has one Boot.php.

Overview

From the CorePHP RFC (plans/code/core/php/RFC.md):

CorePHP provides the framework architecture for PHP development in the Lethean ecosystem.

Key principles:

Everything is a module
Every module is self-contained
Every module has one Boot.php (ServiceProvider entry point)
Modules are only instantiated when their events fire — lazy loading

Module architecture

app/Mod/{ModuleName}/
├── Boot.php              # Single ServiceProvider entry point
├── Console/              # Artisan Commands
├── Controllers/          # HTTP Controllers (Web & API)
├── Database/             # Migrations, Factories, Seeders
├── Events/               # Events & Listeners
├── Jobs/                 # Queueable Jobs
├── Mcp/                  # MCP Tools & Servers
├── Models/               # Eloquent Models (Namespace: Mod\{Mod}\Models)
├── Services/             # Business Logic
├── Tests/                # Pest Tests
└── View/                 # UI Layer (MVVM)
    ├── Modal/            # Livewire Components (ViewModels)
    │   ├── Admin/        # Admin-facing
    │   └── Web/          # Public-facing
    ├── Blade/            # Dumb templates (no logic)
    │   ├── admin/
    │   └── web/
    ├── Components/       # Reusable Blade Components
    └── routes/           # Route definitions

Event-driven boot

class Boot extends ServiceProvider
{
    public static array $listens = [
        AdminPanelBooting::class => 'onAdminPanel',
        WebRoutesRegistering::class => 'onWebRoutes',
        ApiRoutesRegistering::class => 'onApiRoutes',
        ConsoleBooting::class => 'onConsole',
        McpToolsRegistering::class => 'onMcpTools',
    ];
}

Modules are only instantiated when their events fire — lazy loading.

MVVM view protocol (Modern Flexy)

Controller = traffic cop (delegates, never touches HTML)
View Modal = the interface (Livewire Component — formats, prepares, manages state)
Template = dumb (HTML + simple interpolation, no @php blocks, no DB queries)

Rule: Modules provide DATA, Core provides RENDERING.

Three-tier frontend

Core/Front/Web    → Public (anonymous, read-only)
Core/Front/Client → SaaS customer (authenticated, namespace owner)
Core/Front/Admin  → Backend admin (privileged)
Core/Hub          → SaaS operator (Host.uk.com control plane)

Namespace = identity, tied to URI/handle (lt.hn/you, you.lthn). Workspace = management container (org that can own multiple namespaces).

Sub-specs

The CorePHP RFC includes these sub-specifications:

Architecture (plans/code/core/php/RFC.architecture.md)
Commands (plans/code/core/php/RFC.commands.md)
Endpoints (plans/code/core/php/RFC.endpoints.md)
Events (plans/code/core/php/RFC.events.md)
Models (plans/code/core/php/RFC.models.md)
Patterns (plans/code/core/php/RFC.patterns.md)
Release (plans/code/core/php/RFC.release.md)
Scaffolding (plans/code/core/php/RFC.scaffolding.md)
UI (plans/code/core/php/RFC.ui.md)

Repository details

Repository: github.com/dappcore/php
Module: dappco.re/php/*
PHP Version: 8.2+
Total Repos: 25+ (php-* ecosystem)
Framework: Custom (Laravel-inspired)
Testing: Pest PHP framework
Total Modules: 25+ (see INDEX.md)

Component pattern

Anonymous (no PHP class) — pure presentation (<admin:panel>, <admin:nav-item>)
Class-backed — when logic needed (<admin:data-table>, <admin:sidemenu>)

Rule: Modules provide DATA, Core provides RENDERING.

Table naming convention

[module_snake_case]_[table_name] — e.g., agentic_plans, social_posts, analytics_visitors.

Enforcement rules

No Eloquent in Blade — template uses View Modal getters
No @php blocks with business logic
Modules don't query other modules' tables directly — use Service contracts or Events
A module should be extractable as a Composer package with minimal effort

Shared services

Cross-cutting services available to all modules:

Service	Purpose
`DeviceDetectionService`	Device type, OS, browser, bot detection, in-app browser detection (15 platforms)
`GeoIpService`	IP geolocation from CDN headers or MaxMind
`PrivacyHelper`	IP anonymisation and hashing
`UtmHelper`	UTM parameter extraction

In-app browser detection

Detects social media in-app browsers (Instagram, TikTok, Facebook, Twitter, Snapchat, LinkedIn, Threads, Pinterest, Reddit, WeChat, LINE, Telegram, Discord, WhatsApp).

$dd = app(DeviceDetectionService::class);
$dd->isInAppBrowser($ua);          // any in-app browser
$dd->isStrictContentPlatform($ua); // platforms that enforce content policies
$dd->isMetaPlatform($ua);          // Instagram, Facebook, Threads
$dd->getPlatformDisplayName($ua);  // "Instagram", "TikTok", etc.

Used by BioHost for 18+ content warnings when accessed from strict platforms.

Inter-module communication

Modules communicate via Laravel events — lifecycle events (WebRoutesRegistering, AdminPanelBooting, etc.) for route/panel registration, and domain events (DomainResolving) for cross-module data flows.

// Fire a domain event (not lifecycle)
event(new MemoryStored($memory));

// Any module can listen
MemoryStored::class => [UpdateTrainingData::class, TrackRecallLatency::class]

Shared event types in Core\Events\ namespace:

// src/Core/Events/DataEvents.php
namespace Core\Events;

class MemoryStored { public function __construct(public BrainMemory $memory) {} }
class MemoryRecalled { public function __construct(public string $query, public array $results) {} }
class WorkspaceCreated { public function __construct(public Workspace $workspace) {} }
class SubscriptionActivated { public function __construct(public Workspace $workspace, public Plan $plan) {} }
class ApiRequestCompleted { public function __construct(public string $endpoint, public float $duration) {} }

Testing strategy

Tests use Pest with Orchestra Testbench and in-memory SQLite. Tests are co-located in src/Core/{Package}/Tests/ and src/Mod/{Module}/Tests/.

CI matrix covers PHP 8.2/8.3/8.4 × Laravel 11/12.

Every module has:

Unit tests for Actions and Services
Feature tests for API endpoints (happy path, 401, 403, 422)
Livewire component tests
Migration tests (up + down)

Source of truth

Primary Spec: plans/code/core/php/RFC.md
Implementation: core/php/
Agent Guide: core/php/AGENTS.md
Index: plans/code/core/php/INDEX.md

Architecture

CorePHP (PHP Framework)
├── Core Packages
│   ├── php-admin
│   ├── php-agent
│   ├── php-analytics
│   ├── php-api
│   ├── php-bio
│   ├── php-client
│   ├── php-commerce
│   ├── php-config
│   ├── php-content
│   ├── php-developer
│   ├── php-filehost
│   ├── php-framework
│   └── php-tenant
├── Plugins
│   ├── php-plug-altum
│   ├── php-plug-business
│   ├── php-plug-cdn
│   ├── php-plug-chat
│   ├── php-plug-content
│   ├── php-plug-social
│   ├── php-plug-stock
│   ├── php-plug-storage
│   └── php-plug-web3
└── Services
    ├── php-service
    ├── php-shield
    ├── php-template
    ├── php-uptelligence
    ├── php-vapphost
    └── php-vaulthost

Core components

1. Framework core (`php-framework`)

Routing — RESTful routes
Middleware — Request/response processing
Controllers — Business logic
Models — Data access
Views — Template rendering
Blade-like templates — GrammarImprint integration

2. API package (`php-api`)

Resource controllers
Request validation
Response formatting
Authentication — JWT, OAuth2
Rate limiting

3. Agent package (`php-agent`)

MCP (Model Context Protocol) support
Workspace management
Tool execution
Fleet coordination

4. Plugins system

Plugin	Purpose
php-plug-altum	Altum integration
php-plug-business	Business logic
php-plug-cdn	CDN management
php-plug-chat	Chat functionality
php-plug-content	Content management
php-plug-social	Social features
php-plug-stock	Stock/asset management
php-plug-storage	Storage backends
php-plug-web3	Web3/blockchain

5. Services layer

Service	Purpose
php-service	Core service framework
php-shield	Security/protection
php-template	Template management
php-uptelligence	Uptime intelligence
php-vapphost	VAPP hosting
php-vaulthost	Vault hosting

How-tos

1. Creating a new module

# Create module directory
mkdir -p app/Mod/MyModule

# Create Boot.php
cat > app/Mod/MyModule/Boot.php <<EOF
<?php

namespace App\Mod\MyModule;

use Core\ServiceProvider;
use Core\Events\WebRoutesRegistering;

class Boot extends ServiceProvider
{
    public static array \$listens = [
        WebRoutesRegistering::class => 'onWebRoutes',
    ];
    
    public function onWebRoutes(WebRoutesRegistering \$event): void
    {
        // Register routes
    }
}
EOF

2. Creating a Livewire component

// app/Mod/MyModule/Modal/Web/MyComponent.php
namespace App\Mod\MyModule\Modal\Web;

use Livewire\Component;

class MyComponent extends Component
{
    public string \$name = '';
    
    public function render()
    {
        return view('mymodule::web.my-component');
    }
}

3. Using device detection

// In a controller or service
\$dd = app(DeviceDetectionService::class);

if (\$dd->isInAppBrowser(request()->userAgent())) {
    // Show warning for in-app browser
    return view('warnings.in-app-browser');
}

if (\$dd->isStrictContentPlatform(request()->userAgent())) {
    // Show 18+ content warning
    return view('warnings.strict-platform');
}

4. Firing domain events

// In a service
use Core\Events\MemoryStored;

event(new MemoryStored($memory));

// Listeners are registered in Boot.php
MemoryStored::class => [
    UpdateTrainingData::class,
    TrackRecallLatency::class,
]

Getting started

For agents

Read the RFC: plans/code/core/php/RFC.md
Check index: plans/code/core/php/INDEX.md
Explore code: ls core/php/

For developers

Clone the framework: git clone github.com/dappcore/php-framework
Install dependencies: composer install
Run development server: php artisan serve
Build for production: php artisan optimize

Quick reference

Module structure

Directory	Purpose	Namespace
`Boot.php`	ServiceProvider entry	`App\Mod\{Module}`
`Console/`	Artisan Commands	`App\Mod\{Module}\Console`
`Controllers/`	HTTP Controllers	`App\Mod\{Module}\Controllers`
`Database/`	Migrations, Factories	`App\Mod\{Module}\Database`
`Events/`	Events & Listeners	`App\Mod\{Module}\Events`
`Jobs/`	Queueable Jobs	`App\Mod\{Module}\Jobs`
`Mcp/`	MCP Tools	`App\Mod\{Module}\Mcp`
`Models/`	Eloquent Models	`App\Mod\{Module}\Models`
`Services/`	Business Logic	`App\Mod\{Module}\Services`
`Tests/`	Pest Tests	`App\Mod\{Module}\Tests`
`View/`	UI Layer	`App\Mod\{Module}\View`

Frontend tiers

Tier	Audience	Access
`Core/Front/Web`	Public	Anonymous, read-only
`Core/Front/Client`	SaaS customer	Authenticated, namespace owner
`Core/Front/Admin`	Backend admin	Privileged
`Core/Hub`	SaaS operator	Host.uk.com control plane

Device detection methods

Method	Returns	Example
`isInAppBrowser($ua)`	`bool`	Detect any in-app browser
`isStrictContentPlatform($ua)`	`bool`	Strict content policy platforms
`isMetaPlatform($ua)`	`bool`	Instagram, Facebook, Threads
`getPlatformDisplayName($ua)`	`string`	"Instagram", "TikTok"

Testing strategy

Test type	Purpose	Location
Unit tests	Actions and Services	`Tests/Unit/`
Feature tests	API endpoints	`Tests/Feature/`
Livewire tests	Component tests	`Tests/Livewire/`
Migration tests	Database migrations	`Tests/Migration/`

Use cases

When to use CorePHP

PHP web applications
Laravel-like patterns
Plugin architecture
PHP-based infrastructure

When not to use CorePHP

Go applications — use CoreGo instead
TypeScript frontends — use CoreTS instead
Desktop applications — use CoreGUI instead
CLI tools — use CoreCLI instead

Related knowledge packs

CoreGo — Go framework
CoreTS — TypeScript framework
CoreGUI — GUI framework
CoreCLI — CLI framework
CorePlay — Play framework (Go + TS)

Agent tips

Use GrammarImprint — For semantic HTML generation
Laravel conventions — Follow familiar patterns
Plugin system — Use plugins for modularity
Protobuf where possible — For type-safe communication
CorePHP-first — Always check if a package exists

Maintenance

This knowledge pack is maintained by Mistral Vibe. Updates triggered by:

Changes to plans/code/core/php/
Changes to core/php* repositories
New PHP packages
Framework updates

Knowledge Pack v1.0.0 Created: 2026-06-17T14:50:00Z Author: Mistral Vibe Source: Lethean CorePHP Framework

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

CorePHP knowledge pack

Overview

Module architecture

Event-driven boot

MVVM view protocol (Modern Flexy)

Three-tier frontend

Sub-specs

Repository details

Component pattern

Table naming convention

Enforcement rules

Shared services

In-app browser detection

Inter-module communication

Testing strategy

Source of truth

Architecture

Core components

1. Framework core (php-framework)

2. API package (php-api)

3. Agent package (php-agent)

4. Plugins system

5. Services layer

How-tos

1. Creating a new module

2. Creating a Livewire component

3. Using device detection

4. Firing domain events

Getting started

For agents

For developers

Quick reference

Module structure

Frontend tiers

Device detection methods

Testing strategy

Use cases

When to use CorePHP

When not to use CorePHP

Related knowledge packs

Agent tips

Maintenance

1. Framework core (`php-framework`)

2. API package (`php-api`)

3. Agent package (`php-agent`)