README

A lightweight, modern PHP framework designed for building fast and scalable web applications.

Features

⚡ Fast: Optimized for performance with minimal overhead
🎯 Simple: Clean and intuitive API
🔧 Flexible: Easy to extend and customize
🛡️ Secure: Built-in security features
🎨 Modern: Built with PHP 8.1+ features
📦 Dependency Injection: Built-in DI container
🛣️ Routing: Simple and powerful routing system
🗃️ ORM: Doctrine ORM integration
📧 Mail: Symfony Mailer integration
🚦 Rate Limiting: Built-in rate limiting support

Requirements

PHP 8.1 or higher
PDO extension
JSON extension
Composer

Installation

Method 1: Via Composer (Recommended)

Create a new project using Composer:

composer create-project belinframework/framework my-project
cd my-project

Method 2: Manual Installation

Clone the repository and install dependencies:

git clone https://git.belin.uk/framework/belinframework.git my-project
cd my-project
composer install

Configuration

Copy the environment file:
```
cp .env.example .env
```

Edit .env and configure your application:

APP_NAME="Your App Name"
APP_ENV=development
APP_DEBUG=true

DB_HOST=localhost DB_PORT=3306 DB_NAME=your_database DB_USER=your_username DB_PASSWORD=your_password


3. Set up your web server to point to the `public` directory.

4. Start building! Use the `craft` CLI tool:

php craft list # See all available commands php craft make:controller User # Generate a controller php craft serve # Start development server


## Craft CLI Tool

Belin Framework includes **Craft**, a powerful command-line tool for scaffolding and managing your application.

### Available Commands

**Make Commands** (Generate code)

php craft make:controller # Create a new controller php craft make:model # Create a Doctrine entity/model php craft make:service # Create a service with interface php craft make:middleware # Create middleware php craft make:validation # Create validation class php craft make:error # Create custom exception php craft make:migration # Create database migration php craft make:event # Create event class php craft make:listener # Create event listener php craft make:test # Create test (--unit or --integration) php craft make:route # Create route definition php craft make:crud # Generate full CRUD scaffold


**Utility Commands**

php craft serve [host:port] # Start development server (default: localhost:8000) php craft tinker # Interactive PHP REPL console php craft list # List all commands php craft delete # Delete generated files php craft queue:worker # Start event queue worker


### Examples

Create a complete CRUD resource

php craft make:crud Product

This creates: ProductController, Product model, migration, and ProductService

Create a controller

php craft make:controller ApiController

Create a service with interface

php craft make:service PaymentService

Create a database migration

php craft make:migration CreateUsersTable

Create RESTful routes

php craft make:route --resource products ProductController

Start development server

php craft serve

or on custom port

php craft serve localhost:8080

Interactive console (tinker)

php craft tinker


## Quick Start

### Creating a Controller

**Using Craft CLI (Recommended):**

php craft make:controller UserController


**Or manually** create a new controller in `src/Controller`:

<?php

namespace App\Controller;

use App\Core\BaseController; use App\Core\Request; use App\Core\Response;

class UserController extends BaseController {

public function index(Request $request): Response
{
    return $this->success([
        'users' => ['John', 'Jane', 'Bob']
    ]);
}

}


### Adding Routes

Add your routes in `config/routes.php`:

return [

[
    'method' => 'GET',
    'path' => '/api/users',
    'controller' => [\App\Controller\UserController::class, 'index'],
],

];


### Creating Services

1. Create your service class in `src/Service`:

<?php

namespace App\Service;

class UserService {

public function getUsers(): array
{
    // Your logic here
    return ['John', 'Jane', 'Bob'];
}

}


2. Register it in `config/services.php`:

return [

'concrete' => [
    \App\Service\UserService::class,
],

];


3. Use dependency injection in your controller:

public function __construct(

private UserService $userService

) {}


## Project Structure

belinframework/ ├── config/ # Configuration files │ ├── app.php # Application configuration │ ├── cache.php # Cache configuration │ ├── cors.php # CORS configuration │ ├── database.php # Database configuration │ ├── mail.php # Mail configuration │ ├── routes.php # Route definitions │ ├── services.php # Service container configuration │ └── validation.php # Validation rules ├── public/ # Web server document root │ └── index.php # Application entry point ├── resources/ # Views, fonts, and other resources │ ├── fonts/ │ └── views/ ├── src/ # Application source code │ ├── Console/ # Console commands │ ├── Controller/ # HTTP controllers │ ├── Core/ # Framework core files │ ├── Data/ # Data transfer objects │ ├── Entity/ # Doctrine entities │ ├── Error/ # Exception classes │ ├── Event/ # Event classes │ ├── Listener/ # Event listeners │ ├── Middleware/ # HTTP middleware │ ├── Model/ # Business logic models │ ├── Service/ # Service layer │ ├── Validation/ # Validation classes │ ├── Config.php # Configuration loader │ └── helpers.php # Helper functions ├── tests/ # Test files ├── vendor/ # Composer dependencies ├── .env.example # Example environment file ├── .gitignore # Git ignore rules ├── composer.json # Composer dependencies └── README.md # This file


## Core Components

### Router
The router handles all HTTP requests and dispatches them to the appropriate controller.

### Container
Built-in dependency injection container for managing services and their dependencies.

### Request & Response
Elegant request and response objects for handling HTTP interactions.

### BaseController
All controllers extend BaseController which provides helpful methods:
- `success()` - Return success JSON response
- `error()` - Return error JSON response
- `json()` - Return custom JSON response
- `validate()` - Validate request data
- And more...

### Middleware
Support for HTTP middleware to process requests before they reach controllers.

### Error Handling
Comprehensive error handling with custom exception classes.

## Configuration

All configuration files are located in the `config` directory:

- `app.php` - Application settings
- `database.php` - Database connections
- `cache.php` - Cache configuration
- `cors.php` - CORS settings
- `mail.php` - Email configuration
- `routes.php` - Route definitions
- `services.php` - Service container bindings
- `validation.php` - Validation rules

## Environment Variables

Use the `.env` file to configure your application. Available variables:

- `APP_NAME` - Application name
- `APP_ENV` - Environment (development/production)
- `APP_DEBUG` - Enable debug mode
- `APP_TIMEZONE` - Application timezone
- `DB_HOST` - Database host
- `DB_PORT` - Database port
- `DB_NAME` - Database name
- `DB_USER` - Database username
- `DB_PASSWORD` - Database password
- `CACHE_DRIVER` - Cache driver (file/redis)
- `SMTP_*` - Mail server configuration

## Testing

Run the test suite:

composer test


## Code Style

Check code style:

composer phpcs


Fix code style:

composer phpcbf


## License

MIT License

## Author

Alberto Boschi - boschi.alberto1@gmail.com

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

belinframework / framework

Maintainers

Details