Development Rules

All developers working within the Chaos MVC ecosystem must follow these development standards.

These rules exist to maintain predictable behavior, architectural consistency, traceability, and long-term maintainability.

Chaos MVC Convention Precedence

Chaos MVC follows established PHP development standards where those standards are compatible with the framework's documented architecture and conventions.

When a general PHP standard conflicts with an explicit Chaos MVC convention, the documented Chaos MVC convention takes precedence.

This includes the framework's mandatory lowercase naming policy.

Lowercase Naming Policy

Chaos MVC enforces strict lowercase naming conventions.

• Controller files must be lowercase.
• Model files must be lowercase.
• View directories must be lowercase.
• Class names must be lowercase.

Uppercase file or class naming is not permitted.

This rule ensures predictable behavior across filesystems and maintains consistency with the architectural design of Chaos MVC.

Example

user/modules/example/controllers/example.php
user/modules/example/models/example_model.php
user/modules/example/views/

class example extends controller
class example_model extends model

PSR-12 Compliance

Chaos MVC uses PSR-12 as the general formatting standard for PHP source code.

PSR-12 applies where compatible with explicit Chaos MVC framework conventions.

The lowercase class naming policy is an intentional Chaos MVC convention and takes precedence over conflicting class-naming guidance.

PSR-12 Formatting Example

<?php

/**
 * Example Controller
 *
 * Demonstrates Chaos MVC structure and PSR-12 formatting.
 */
class example extends controller
{
    /**
     * Display the default example page.
     *
     * @return void
     */
    public function index()
    {
        $data = [
            'title' => 'Example Module',
        ];

        $this->view('public/example/index', $data);
    }
	
	/**
     * Display and process module administration.
     *
     * Core authenticates and delegates /admin/example to this exact method.
     * The module-local model is deliberately loaded here, after Core has
     * established module context, rather than in the constructor.
     *
     * @param array $params Route parameters.
     *
     * @return void
     */
    public function admin($params = []): void
    {
        $this->require_admin(7);

        $model = $this->model('example_model');
	}
}

DocBlock Requirement

All classes and public methods must include DocBlock documentation.

DocBlocks must describe the purpose of the code, applicable parameters, return values, and expected behavior.

<?php

/**
 * Retrieve a record by slug.
 *
 * @param string $slug Record slug.
 *
 * @return array|false
 */
public function get_by_slug(string $slug)
{
    return $this->fetch(
        "SELECT * FROM records WHERE slug = ? LIMIT 1",
        [$slug]
    );
}

Incomplete or missing documentation is considered a code-quality violation.

Mandatory AI Annotation Policy

Any code written or modified by an AI system must be annotated.

The annotation provides traceability and identifies the model responsible for the generated or modified code.

<?php

/* [AI:MODEL_NAME | YYYY-MM-DD HH:MM:SS UTC] */

modified code

/* [End AI:MODEL_NAME] */

Human approval annotations must accompany AI changes when approval is required for the affected architectural component.

<?php

/*
 * [AI:MODEL_NAME | YYYY-MM-DD HH:MM:SS UTC]
 * [HUMAN:YOU | YYYY-MM-DD HH:MM:SS UTC | APPROVE/DENY]
 */

modified code

/* [End AI:MODEL_NAME] */

MVC Separation

Chaos MVC uses strict separation of responsibilities.

Request
 ↓
Router
 ↓
Controller
 ↓
Model
 ↓
Database
 ↓
Controller
 ↓
View
 ↓
HTML Output

• Controllers coordinate application behavior.
• Models manage database interaction.
• Views present data.
• Views must not contain application or database logic.

Database Rules

Database operations belong inside models.

• Controllers must not directly query the database.
• Views must never query the database.
• Models must use the approved Chaos MVC database wrapper.

See the Database Wrapper documentation for implementation details.

Core Protection

Chaos MVC core infrastructure is protected.

Protected Directories

/app/core
/app/lib

Protected Components

/app/controllers/*.php with core protection enabled
/app/models/*_model.php corresponding to protected core controllers

Changes to protected core components require explicit authorization. Unauthorized modifications to core infrastructure are prohibited.

GitHub Requirement

Architectural changes must be tracked through the project's Git repository.

Core modifications require approval before they are accepted. Direct untracked production changes are not considered acceptable development practice.

Three-Strike Enforcement Policy

• Violation 1: Warning
• Violation 2: Final Warning
• Violation 3: Removal from the project

Enforcement exists to preserve a stable and predictable development environment.

Project Philosophy

Chaos MVC prioritizes:

• Clean architecture
• Predictable behavior
• Strict documentation
• Accountable development
• Minimal unnecessary complexity

Consistency and discipline keep the framework understandable and maintainable as it evolves.