commit b53a97574add5baa1f8890fc0f8446cbc1560c27 Author: Virgil Date: Wed Mar 11 12:14:42 2026 +0000 Add wiki pages diff --git a/Go-CLI.md b/Go-CLI.md new file mode 100644 index 0000000..b7922ad --- /dev/null +++ b/Go-CLI.md @@ -0,0 +1,83 @@ +# Go CLI + +Module: `forge.lthn.ai/core/php` +Binary: `core-php` + +## Architecture + +The Go side provides CLI commands for PHP/Laravel development. Commands are registered via `AddPHPCommands(root)` (subcommand of `core php`) or `AddPHPRootCommands(root)` (standalone `core-php` binary). + +Workspace-aware: when run inside a workspace with `workspace.yaml`, commands auto-chdir to the active package directory. + +## Commands + +### Development + +| Command | File | Description | +|---------|------|-------------| +| `php dev` | cmd_dev.go | Start FrankenPHP + Vite + Horizon + Reverb + Redis with live reload | +| `php logs` | cmd_dev.go | Tail service logs | +| `php stop` | cmd_dev.go | Stop all dev services | +| `php status` | cmd_dev.go | Show service status | +| `php ssl` | ssl.go | SSL certificate management | +| `php shell` | cmd_commands.go | Interactive shell | + +### Build & Deploy + +| Command | File | Description | +|---------|------|-------------| +| `php build` | cmd_build.go | Production build (npm, composer, assets) | +| `php serve` | cmd_serve_frankenphp.go | FrankenPHP production server (CGO) | +| `php ci` | cmd_ci.go | CI pipeline execution | +| `php deploy` | cmd_deploy.go | Deployment operations | + +### Package Management + +| Command | File | Description | +|---------|------|-------------| +| `php packages` | cmd_packages.go | Package workspace management | + +## Key Files + +| File | Description | +|------|-------------| +| cmd.go | Command registration, workspace detection, style definitions | +| handler.go | FrankenPHP request handler | +| bridge.go | Go-PHP bridge | +| services.go | Service process management (FrankenPHP, Vite, Horizon, Reverb, Redis) | +| services_unix.go | Unix-specific service code | +| services_windows.go | Windows-specific service code | +| container.go | Docker container management | +| coolify.go | Coolify deployment integration | +| deploy.go | Deployment logic | +| detect.go | Project/framework detection | +| dockerfile.go | Dockerfile generation | +| env.go | Environment variable management | +| extract.go | Archive extraction | +| i18n.go | Internationalisation | +| packages.go | Composer package operations | +| php.go | PHP binary detection and execution | +| quality.go | Code quality (qa.yaml config) | +| ssl.go | SSL certificate generation/management | +| testing.go | Test helpers | +| workspace.go | Workspace config loading | + +## Service Management + +The `dev` command orchestrates multiple long-running processes: + +- **FrankenPHP** — PHP application server (worker mode). +- **Vite** — Frontend asset bundler with HMR. +- **Horizon** — Laravel queue worker. +- **Reverb** — Laravel WebSocket server. +- **Redis** — Cache/queue backend. + +Each service has styled log output with colour-coded prefixes. + +## FrankenPHP Integration + +When built with CGO enabled (`cmd_serve_frankenphp.go`), the binary embeds FrankenPHP for serving PHP applications directly from Go. The `handler.go` file implements the request handler. + +## Dependencies + +Direct: `core/cli`, `go-i18n`, `go-io`. diff --git a/Home.md b/Home.md new file mode 100644 index 0000000..2a28af4 --- /dev/null +++ b/Home.md @@ -0,0 +1,12 @@ +# PHP + +Module: `forge.lthn.ai/core/php` (Go) +Composer: `lthn/php` (PHP) +Binary: `core-php` + +Dual-purpose repository. The PHP side is the foundation Laravel framework package providing event-driven module loading, lifecycle events, lazy module listener, and core services (actions, bouncer, CDN, crypt, database, headers, i18n, mail, media, search, SEO, storage). The Go side provides a CLI for PHP development: FrankenPHP dev server, Vite, Horizon, Reverb, Redis process management, build/deploy pipelines, SSL management, CI integration, and package workspace management. + +## Topic Pages + +- [Go-CLI](Go-CLI) — Go CLI commands, FrankenPHP handler, services +- [PHP-Framework](PHP-Framework) — Laravel package, lifecycle events, module loading diff --git a/PHP-Framework.md b/PHP-Framework.md new file mode 100644 index 0000000..1ffbc85 --- /dev/null +++ b/PHP-Framework.md @@ -0,0 +1,93 @@ +# PHP Framework + +Composer: `lthn/php` +Provider: `Core\LifecycleEventProvider`, `Core\Lang\LangServiceProvider`, `Core\Bouncer\Gate\Boot` + +## Architecture + +Event-driven modular monolith framework for Laravel. Modules declare interest in lifecycle events via static `$listens` arrays and are only instantiated when those events fire. The `LazyModuleListener` defers module loading until the subscribed event is dispatched. + +### Module Loading + +1. `ModuleScanner` discovers modules from configured namespace paths. +2. `ModuleRegistry` tracks discovered modules and their event subscriptions. +3. `LifecycleEventProvider` registers the `LazyModuleListener` that intercepts lifecycle events and instantiates modules on demand. + +### Lifecycle Events + +Defined in `src/Core/Events/`: + +| Event | Purpose | +|-------|---------| +| `WebRoutesRegistering` | Public web routes | +| `AdminPanelBooting` | Admin panel registration | +| `ApiRoutesRegistering` | REST API routes | +| `ClientRoutesRegistering` | Authenticated SaaS routes | +| `ConsoleBooting` | Artisan commands | +| `McpToolsRegistering` | MCP tool handlers | + +## Namespace Mapping + +| Path | Namespace | +|------|-----------| +| `src/Core/` | `Core\` | +| `src/Mod/` | `Core\Mod\` | +| `src/Plug/` | `Core\Plug\` | +| `src/Website/` | `Core\Website\` | + +## Core Services + +| Directory | Description | +|-----------|-------------| +| Actions/ | Single-purpose action classes with `Action` trait | +| Activity/ | Activity logging integration | +| Boot.php | Core boot provider | +| Bouncer/ | Authorisation gates | +| Cdn/ | CDN integration (asset serving) | +| Config/ | Configuration management | +| Console/ | Core artisan commands | +| Crypt/ | Encryption/decryption services | +| Database/ | Database extensions, migrations | +| Events/ | Lifecycle event classes | +| Front/ | Front-end service layer | +| Headers/ | HTTP header management | +| Helpers/ | Utility functions | +| Input/ | Input validation | +| Lang/ | Internationalisation (LangServiceProvider) | +| Mail/ | Mail templates and sending | +| Media/ | Media handling, thumbnails | +| Rules/ | Validation rules | +| Search/ | Search integration | +| Seo/ | SEO meta management | +| Storage/ | Storage abstraction | + +## Key Classes + +- **`LifecycleEventProvider`** — Registers lazy module listener, dispatches lifecycle events. +- **`LazyModuleListener`** — Intercepts events, instantiates modules that declared interest via `$listens`. +- **`ModuleScanner`** — Discovers module classes from configured paths. +- **`ModuleRegistry`** — Tracks modules and their event subscriptions. +- **`Init`** — Core initialisation. +- **`Pro`** — Pro/premium feature gates. + +## Actions Pattern + +Single-purpose business logic with static `run()` helper: + +```php +class CreateOrder +{ + use Action; + + public function handle(User $user, array $data): Order + { + return Order::create($data); + } +} +// Usage: CreateOrder::run($user, $validated); +``` + +## Dependencies + +PHP: `laravel/framework ^11.0|^12.0`, `laravel/pennant ^1.0`, `livewire/livewire ^3.0|^4.0`. +Dev: `larastan`, `phpstan`, `psalm`, `pest`, `pint`, `rector`, `infection`, `orchestra/testbench`.