php-commerce/GEMINI.md

Core PHP Framework - AI Assistant Context

For Gemini Code Assist, Jules, and other Google AI tools.

Project Type

Laravel 12 application using Core PHP Framework - a modular monolith with event-driven architecture.

Directory Structure

app/
├── Mod/              # Feature modules (your code)
│   └── {Name}/
│       ├── Boot.php  # Event listeners
│       ├── Models/
│       ├── Routes/
│       ├── Views/
│       └── Livewire/
├── Core/             # Local framework overrides (EUPL-1.2)
└── Providers/

config/core.php       # Framework configuration

Module Pattern

Every module has a Boot.php with static $listens array:

<?php

declare(strict_types=1);

namespace App\Mod\Shop;

use Core\Events\WebRoutesRegistering;
use Core\Events\ApiRoutesRegistering;
use Core\Events\AdminPanelBooting;

class Boot
{
    public static array $listens = [
        WebRoutesRegistering::class => 'onWebRoutes',
        ApiRoutesRegistering::class => 'onApiRoutes',
        AdminPanelBooting::class => 'onAdminPanel',
    ];

    public function onWebRoutes(WebRoutesRegistering $event): void
    {
        $event->routes(fn() => require __DIR__.'/Routes/web.php');
        $event->views('shop', __DIR__.'/Views');
    }

    public function onApiRoutes(ApiRoutesRegistering $event): void
    {
        $event->routes(fn() => require __DIR__.'/Routes/api.php');
    }

    public function onAdminPanel(AdminPanelBooting $event): void
    {
        $event->navigation('Shop', 'shop.admin.index', 'shopping-cart');
    }
}

Code Style Requirements

Language: UK English

• colour (not color)
• organisation (not organization)
• centre (not center)
• behaviour (not behavior)
• licence (noun), license (verb)

PHP Standards

• declare(strict_types=1); in all files
• Full type hints (parameters + return types)
• PSR-12 formatting (use Laravel Pint)
• Pest for testing

Naming Conventions

Type	Convention	Example
Model	Singular PascalCase	Product
Table	Plural snake_case	products
Controller	{Model}Controller	ProductController
Livewire Page	{Feature}Page	ProductListPage
Livewire Modal	{Feature}Modal	EditProductModal

UI Stack

• Livewire 3 - Server-side reactivity
• Flux Pro - UI component library (NOT vanilla Alpine)
• Tailwind CSS - Utility-first styling
• Font Awesome Pro - Icons (NOT Heroicons)

Common Commands

php artisan make:mod Blog --all    # Create module with all features
php artisan serve                   # Development server
vendor/bin/pint --dirty            # Format changed files
vendor/bin/pest                    # Run tests

Packages

Package	Namespace	Purpose
host-uk/core	Core\	Framework core
host-uk/core-admin	Core\Admin\	Admin panel
host-uk/core-api	Core\Api\	REST API
host-uk/core-mcp	Core\Mcp\	AI agent tools

Avoid

• American English spellings
• Heroicons (use Font Awesome)
• Vanilla Alpine components (use Flux)
• Over-engineering / premature abstraction
• PHPUnit syntax (use Pest)