# MVC Framework Skill

## Purpose

Use this skill for MindVisionCode PHP framework architecture, routing, dispatching, controllers, actions, ViewModels, templates, and HTTP request/response flow.

---

## Project Identity

This project is a small PHP MVC framework called **MindVisionCode PHP**.

It is intentionally inspired by a Classic ASP MVC framework style:

- Central dispatcher
- Controllers and actions
- ViewModels
- Repository classes
- Simple validation
- Database migrations
- Small, readable files
- Minimal dependencies

Do not turn this into Laravel, Symfony, Slim, CakePHP, or another large framework.

---

## Request Flow

```text
Browser
  → public/index.php
  → Request
  → Dispatcher
  → Router
  → Route
  → Controller
  → ViewModel/Repository/Service
  → View
  → Response
```

---

## Project Structure

Preferred structure:

```text
project-root/
  public/
    index.php
  src/
    Controller/
    Service/
    Repository/
    Entity/
    ValueObject/
    ViewModel/
    Http/
    Routing/
    Validation/
    Database/
    Migration/
  templates/
  config/
  tests/
  var/
    cache/
    logs/
  vendor/
  composer.json
```

Rules:

- `public/` is the web root.
- Do not expose `src/`, `config/`, `tests/`, `vendor/`, `.ai/`, or `.env` files through the web server.
- Put application code under `src/`.
- Put generated cache/log files under `var/` or another ignored runtime directory.
- Keep secrets outside the web root.

---

## Development Commands

Install dependencies:

```bash
composer install
```

Regenerate autoload files:

```bash
composer dump-autoload
```

Run local server:

```bash
php -S localhost:8000 -t public
```

Run basic tests:

```bash
php tests/run.php
```

---

## Framework Coding Rules

- Keep code simple and readable.
- Prefer small classes.
- Use typed properties and return types where practical.
- Avoid hidden magic.
- Do not add dependencies without a clear reason.
- Preserve the framework style.
- Explain any architectural changes.

---

## Controller Rules

- Keep controllers thin.
- Validate request method and request shape at the boundary.
- Do not put database query details directly in controllers when a repository or service is more appropriate.
- Do not put template rendering logic inside business services.
- Return or produce a response through the framework’s response mechanism.

---

## ViewModel Rules

- Use ViewModels to shape data for views.
- Keep ViewModels simple and explicit.
- Avoid passing raw database rows directly into complex templates when a ViewModel would make the template clearer.
- Do not put database access inside ViewModels unless the existing project convention explicitly does that.

---

## Templates and Views

Keep presentation separate from business logic.

Rules:

- Do not query the database from templates.
- Do not place business rules in templates.
- Escape output by default.
- Prefer simple view models or arrays passed into templates.
- Use a template engine with automatic escaping only if it fits the project and does not make the framework unnecessarily large.

Plain PHP template example:

```php
<h1><?= e($pageTitle) ?></h1>

<ul>
    <?php foreach ($users as $user): ?>
        <li><?= e($user->name()) ?></li>
    <?php endforeach; ?>
</ul>
```

---

## HTTP and Web Application Rules

Rules:

- Use the front controller pattern where appropriate.
- Keep routing separate from business logic.
- Validate request methods.
- Use CSRF protection for state-changing forms.
- Use proper HTTP status codes.
- Redirect after successful POST to avoid duplicate form submission.
- Do not trust headers such as `X-Forwarded-For` unless configured behind a trusted proxy.

Example POST guard:

```php
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit('Method Not Allowed');
}
```

---

## Architecture Guardrail

When adding features, preserve the small-framework character:

- Prefer explicit code over hidden convention.
- Prefer simple routing over complex annotation systems.
- Prefer plain PHP views unless a project decision says otherwise.
- Prefer focused services and repositories over large framework abstractions.
- Do not introduce a large package just to solve a small problem.