Woles-Framework/README.md

# 🚀 Woles Framework v1.0

A minimalist, ultra-secure, high-performance PHP framework based on CleanLite HMVC architecture.

## ✨ Features

- **🔒 Security First**: Built-in CSRF protection, XSS filtering, and secure password hashing
- **⚡ High Performance**: Optimized for PHP 8.2+ with JIT compilation support
- **🏗️ Clean Architecture**: Modular HMVC structure with dependency injection
- **🎨 Modern UI**: Professional enterprise-style responsive design
- **🛡️ Ultra-Secure**: AES-256-GCM encryption, Argon2ID password hashing
- **📦 Lightweight**: No heavy dependencies, minimal core footprint

## 🚀 Quick Start

### Prerequisites

- PHP 8.2 or higher
- Composer
- Web server (Apache/Nginx) or PHP built-in server

### Installation

1. **Clone or download the framework**

   ```bash
   git clone <repository-url> woles
   cd woles
   ```

2. **Install dependencies**

   ```bash
   composer install
   ```

3. **Configure environment**

   ```bash
   cp env.example .env
   # Edit .env file with your configuration
   ```

4. **Set up database** (optional)

   ```bash
   # Create database and run migrations
   php woles migrate
   ```

5. **Start development server**

   ```bash
   composer serve
   # or
   php -S localhost:8000 -t public
   ```

6. **Visit your application**
   ```
   http://localhost:8000
   ```

## 📁 Project Structure

```
/app
   /Core                    # Framework core
      Bootstrap.php         # Application kernel
      Router.php            # Fast routing system
      Middleware.php        # Middleware pipeline
      Container.php         # Dependency injection
      Security.php          # Security utilities
      Controller.php        # Base controller
      Request.php           # Request handler
      Response.php          # Response handler
      View.php              # Template engine
   /Modules                 # HMVC modules
      /Auth                 # Authentication module
      /User                 # User management module
      /Home                 # Homepage module
   /Config                  # Configuration files
   /Domain                  # Domain layer
      /Entities
      /Repositories
      /Services
/public                     # Web root
   index.php               # Entry point
/storage                    # Storage directories
   /logs                   # Log files
   /cache                  # Cache files
   /sessions               # Session files
/database                   # Database files
   /migrations             # Database migrations
```

## 🛠️ Usage

### CLI (Woles)

Gunakan CLI `woles` untuk manajemen project:

```bash
# Bantuan
php woles help

# Server dev
php woles serve

# Migrasi database
php woles migrate
php woles migrate:status
php woles migrate:rollback

# Seeder
php woles seed
php woles seed UserSeeder

# Generate APP_KEY
php woles key:generate
```

### Creating a Module

1. **Create module directory**

   ```bash
   mkdir -p app/Modules/YourModule/view
   ```

2. **Create controller**

   ```php
   // app/Modules/YourModule/Controller.php
   namespace App\Modules\YourModule;
   use App\Core\Controller;

   class Controller extends Controller
   {
       public function index()
       {
           return $this->view('YourModule.view.index', [
               'title' => 'Your Module'
           ]);
       }
   }
   ```

3. **Create routes**

   ```php
   // app/Modules/YourModule/routes.php
   $router->get('/your-route', 'YourModule\Controller@index');
   ```

4. **Create view**
   ```php
   <!-- app/Modules/YourModule/view/index.php -->
   <h1>{{ $title }}</h1>
   ```

### Security Features

- **CSRF Protection**: Automatic token generation and validation
- **XSS Filtering**: All input automatically sanitized
- **Password Hashing**: Argon2ID algorithm
- **Encryption**: AES-256-GCM for sensitive data
- **Security Headers**: CSP, HSTS, and more

### Middleware

```php
// Create custom middleware
class CustomMiddleware
{
    public function handle(string $method, string $uri, callable $next): void
    {
        // Your middleware logic
        $next();
    }
}

// Register middleware
$middleware->add(new CustomMiddleware());
```

### Database Operations

```php
// Using the Model class
$model = new App\Modules\User\Model();
$users = $model->all();
$user = $model->findById(1);
$model->create(['name' => 'John', 'email' => 'john@example.com']);
```

## 🔧 Configuration

### Environment Variables

```env
APP_NAME="Woles Framework"
APP_ENV=development
APP_DEBUG=true
APP_URL=http://localhost:8000
APP_KEY=your-secret-key-here-32-chars-min

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=woles
DB_USERNAME=root
DB_PASSWORD=

CACHE_DRIVER=file
LOG_LEVEL=debug
```

### Security Configuration

The framework includes comprehensive security features:

- Automatic CSRF token generation
- XSS protection on all input
- Secure password hashing
- Encryption utilities
- Security headers

## 🧪 Testing

```bash
# Run tests
composer test

# Run with coverage
composer test -- --coverage
```

## 📚 API Documentation

### Core Classes

- **Bootstrap**: Application kernel and initialization
- **Router**: Fast route matching and parameter extraction
- **Container**: Dependency injection container
- **Security**: Security utilities and encryption
- **Controller**: Base controller with common methods
- **Request**: HTTP request wrapper
- **Response**: HTTP response handler
- **View**: Template engine with syntax processing

### Helper Functions

- `app($name)`: Get service from container
- `request()`: Get request instance
- `response()`: Get response instance
- `view($view, $data)`: Render view
- `redirect($url)`: Redirect response
- `env($key, $default)`: Get environment variable
- `csrf_token()`: Generate CSRF token
- `bcrypt($password)`: Hash password
- `e($value)`: Escape HTML

## 🚀 Performance

- Optimized for PHP 8.2+ JIT compilation
- Compatible with RoadRunner and FrankenPHP
- Minimal memory footprint
- Fast route matching
- Efficient template processing

## 🤝 Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 🙏 Acknowledgments

- Inspired by Laravel's elegant architecture
- Built with modern PHP best practices
- Security-first approach
- Clean code principles

---

**Woles Framework v1.0** - Built with ❤️ for modern PHP development