Contribution Guide

Thank you for your interest in contributing to mouse-php!

mouse-php is an open-source, ultra-lightweight, API-first PHP framework designed around zero vendor bloat, high execution speed, and transparent developer ergonomics.

To maintain the architectural integrity, performance, and simplicity of the framework, all contributions must adhere to the guidelines outlined below.

Core Principles & Philosophy

Before opening an issue or submitting a Pull Request (PR), keep these core principles in mind:

1. Zero Unnecessary Dependencies: mouse-php ships with a clean slate. vlucas/phpdotenv is the single Composer dependency permitted in the core framework. PRs that attempt to introduce third-party Composer packages into the core framework will be rejected.

2. No Forced Bloat: Features must be opt-in, lightweight, and tailored for performance. If a feature can live as a downstream user utility, it should not be in mouse-php core.

3. Non-Destructive Tooling: Any changes or additions to the squeak CLI tool must strictly obey the No Destructive Commands policy. squeak is never permitted to delete or overwrite user business logic.

4. Final Architectural Review: All merges into master are strictly governed by the maintainer. Code quality, performance benchmarks, and alignment with framework goals take precedence over feature quantity.

Code Style & Formatting Conventions

To keep the codebase uniform and readable, all PHP code must follow these exact formatting conventions:

Indentation & Structure

• 4-Space Indentation: Use 4 spaces for indentation (no hard tabs).

• Attached Braces: Open braces { must always be attached on the same line for classes, methods, if statements, switch cases, and loops alike:

// CORRECT (Attached Braces Throughout)
class User_Controller {
    public $DB;

    public function get_user() {
        if ($user_id > 0) {
            // Logic
        }
    }
}

// INCORRECT (Do not break braces onto new lines)
class User_Controller
{
    public function get_user()
    {
        if ($user_id > 0)
        {
            // Logic
        }
    }
}

Naming Conventions

• Classes & Namespaces: Use Pascal_Snake_Case with initial capitals (Like_So). Example: Database_Handler, User_Controller, Env_Bootstrap.

• Methods & Functions: Use lowercase snake_case. Example: make_query(), fetch_profile_by_id(), get_var().

• Variables & Arguments: Use lowercase snake_case. Example: $user_id, $request_data, $auth_token.

• Class Properties: Use ALL_CAPS or CAPS_SNAKE_CASE for class properties injected by the framework core. Example: $this->DB, $this->SQLITE, $this->REQUEST_DATA.

Branching & PR Workflow

The master branch is reserved strictly for stable release versions. All development happens on the development branch.

┌─────────────────────────────────────────────────────────────┐
│                      CONTRIBUTION FLOW                      │
├─────────────────────────────────────────────────────────────┤
│ 1. Fork Repository                                          │
│ 2. Create Feature Branch from `development`                 │
│ 3. Implement & Test Manually                                │
│ 4. Submit Pull Request against `development` Branch         │
└─────────────────────────────────────────────────────────────┘

Steps to Submit a Feature or Bug Fix

1. Fork the Repository: Create your own fork of mouse-php on GitHub.

2. Branch from development:

git checkout -b feature/my-new-feature origin/development

3. Implement Changes: Write clean, documented code following the formatting style.

4. Manual Verification: Ensure your changes run cleanly without errors (see Testing Guidelines below).

5. Open a Pull Request: Submit your PR targeting the development branch (PRs targeted against master will be closed or requested to rebase). Provide a clear, detailed explanation of what your code changes, why it is necessary, and how it was tested.

Manual Testing Requirements

Unit test suites are currently on the development roadmap. In the meantime, contributors are expected to perform thorough manual testing before submitting a PR:

1. Dev Server Verification: Launch php squeak and run > serve to ensure the core routing, middleware, and controller execution pipelines run without throwing warnings or fatal errors.

2. Log Verification: Run > tail inside squeak to verify that system events and database queries are correctly logged to mouse.db.

3. Scaffolding Checks: If modifying squeak, run scaffolding commands (add-route, add-controller, add-model, add-middleware, add-utility) to confirm that files are generated in the correct paths with proper syntax and namespace bindings.

4. Collision Testing: Verify that squeak properly halts execution when attempting to scaffold over an existing file, preventing clobbering of business logic.

Security & Disclosure

If you discover a security vulnerability within mouse-php (such as a bypass in the PDO wrapper, SQL injection vector, or routing exploit), please do not open a public issue.

Instead, report it directly to the repository maintainer via email or private security advisory so it can be patched prior to public release.