Phred/README.md

# Phred

A PHP MVC framework intended for projects of all sizes, designed for both solo and team development.

## Requirements

* **PHP**: 8.2+
* **Web Server**: Apache/Nginx (recommended)
* **Package Manager**: Composer

## Installation

Install Phred via Composer:

```bash
composer create-project getphred/phred
```

## Getting Started

### Creating a Module

Phred uses a modular (Django-style) architecture. All your application logic lives inside modules.

To scaffold a new module:

```bash
php phred create:module Shop
```

This will create the module structure under `modules/Shop`, register the service provider, and mount the routes.

After creating a module, update your `composer.json` to include the new namespace:

```json
{
  "autoload": {
    "psr-4": {
      "Modules\\\\Shop\\\\": "modules/Shop/"
    }
  }
}
```

Then run:
```bash
composer dump-autoload
```

### Running the Application

Start the local development server:

```bash
php phred run
```

The application will be available at `http://localhost:8000`.

## Configuration

Phred uses a `.env` file for configuration. Key settings include:

*   `API_FORMAT`: The default API format (`rest` or `jsonapi`).
*   `MODULE_NAMESPACE`: The base namespace for your modules (default: `Modules`).
*   `APP_DEBUG`: Enable debug mode (`true` or `false`).
*   `COMPRESSION_ENABLED`: Enable response compression (Gzip/Brotli).

## CLI Usage (phred)

The `phred` binary provides several utility and scaffolding commands.

### Generators
* `php phred create:module <name>` — Create a new module.
* `php phred create:command <name>` — Create a custom CLI command.
* `php phred create:<module>:controller <name>` — Create a controller.
* `php phred create:<module>:view <name>` — Create a view and template.
* `php phred create:<module>:model <name>` — Create a domain model.
* `php phred create:<module>:migration <name>` — Create a migration.
* `php phred create:<module>:seed <name>` — Create a database seeder.
* `php phred create:<module>:test <name>` — Create a test.

### Database
* `php phred migrate` — Run database migrations.
* `php phred migration:rollback` — Rollback migrations.
* `php phred seed` — Seed the database.
* `php phred db:backup` — Backup the database.
* `php phred db:restore` — Restore the database.

### Testing & Utilities
* `php phred test` — Run tests for the entire project.
* `php phred test:<module>` — Run tests for a specific module.
* `php phred module:list` — List all discovered and registered modules.
* `php phred module:sync-ns` — Sync `composer.json` PSR-4 with `MODULE_NAMESPACE`.
* `php phred list` — List all available commands.

## Routing

Routes are defined in `routes/web.php`, `routes/api.php`, or within your module's `Routes/` directory. Phred uses `nikic/fast-route` for high-performance routing.

### Basic Routes

You can define routes using the `$router` instance:

```php
// routes/web.php
$router->get('/welcome', WelcomeController::class);
$router->post('/submit', SubmitFormController::class);
```

### Route Groups

Groups allow you to share prefixes and middleware:

```php
$router->group(['prefix' => '/api', 'middleware' => 'api'], function ($router) {
    $router->get('/users', ListUsersController::class);
    $router->get('/users/{id}', ShowUserController::class);
});
```

### Module Auto-Mounting

Phred automatically mounts module routes based on folder name:
- `modules/Shop/Routes/web.php` → mounted at `/shop`
- `modules/Shop/Routes/api.php` → mounted at `/api/shop` (with `api` middleware)

### Route Listing & Caching

View all registered routes:
```bash
php phred route:list
```

In production, cache your routes for maximum performance:
```bash
php phred route:cache
php phred route:clear # To clear cache
```

## Technical Specifications

For detailed information on the framework architecture, service providers, configuration, and MVC components, please refer to:

👉 **[SPECS.md](./SPECS.md)** | [MILESTONES.md](./MILESTONES.md)

## License

Phred is open-source software licensed under the MIT license.