⚡ BareMetalPHP

🎯 Introduction

BareMetalPHP is a modern, lightweight PHP framework built for speed, simplicity, and developer happiness. It's powered by an optional Go application server that enables persistent PHP workers, hot reload, multi-pool concurrency, and static file acceleration.

📦 Installation

Create a New Project

composer create-project baremetalphp/baremetalphp myapp
cd myapp

Start the Development Server

php mini serve

Your application is now running at http://localhost:8000

🚀 Go Application Server

The BareMetalPHP Go Application Server is a high-performance, production-ready runtime that replaces traditional PHP-FPM with persistent PHP workers.

✨ Key Features

• Persistent PHP workers (no cold starts)
• Fast/slow worker classification for optimal load balancing
• Automatic hot reload via fsnotify
• Static asset acceleration
• JSON bridge protocol between Go and PHP

Installation

Install the Go server scaffold:

php mini go:install
go mod tidy

Start the Go Runtime

php mini go:serve

Configuration

Edit config/appserver.php:

return [
    'enabled'      => env('APPSERVER_ENABLED', false),
    'fast_workers' => env('APPSERVER_FAST_WORKERS', 4),
    'slow_workers' => env('APPSERVER_SLOW_WORKERS', 2),
    'hot_reload'   => env('APPSERVER_HOT_RELOAD', true),
];

Generated JSON Config

{
  "FastWorkers": 4,
  "SlowWorkers": 2,
  "HotReload": true,
  "Static": [
    {"Prefix": "/css/", "Dir": "public/css"},
    {"Prefix": "/js/", "Dir": "public/js"},
    {"Prefix": "/images/", "Dir": "public/images"}
  ]
}

Architecture Overview

┌──────────────┐     Request     ┌─────────────────────────┐
│ Browser/CLI  │ ───────────────▶ │ BareMetalPHP Go Server │
└──────────────┘                 │ • Static files          │
                                 │ • Hot reload            │
                                 │ • Worker scheduling     │
                                 └─────────────┬───────────┘
                                               │ Dispatch
                                               ▼
                                 ┌──────────────────────────┐
                                 │ Persistent PHP Workers  │
                                 │ • bootstrap_app.php     │
                                 │ • bridge.php            │
                                 └─────────────┬───────────┘
                                               ▼
                                 ┌──────────────────────────┐
                                 │  BareMetalPHP Framework  │
                                 │ • Router                 │
                                 │ • Kernel                 │
                                 │ • DI Container           │
                                 │ • Controllers/Views      │
                                 └──────────────────────────┘

🧠 PHP Kernel

The Kernel is the heart of BareMetalPHP. It receives requests from the Go server, resolves routes, executes controllers, and returns responses.

In persistent mode, the kernel bootstraps once and handles multiple requests, dramatically improving performance over traditional request-per-process models.

🛣 Routing

Define your application routes with a clean, expressive syntax:

// Simple closure route
$router->get('/', function () {
    return "Hello world";
});

// Route with parameters
$router->get('/user/{id}', 'UserController@show');

// Named routes
$router->get('/posts', 'PostController@index')->name('posts.index');

// Route groups
$router->group(['prefix' => 'api'], function ($router) {
    $router->get('/users', 'UserController@index');
    $router->post('/users', 'UserController@store');
});

📍 Controllers

Controllers handle your application logic with automatic dependency injection:

namespace App\Controllers;

class UserController
{
    public function show(\App\Models\User $user)
    {
        return view('user.show', ['user' => $user]);
    }

    public function store(Request $request)
    {
        $user = User::create($request->all());
        
        return redirect()->route('users.show', $user->id);
    }
}

Create a Controller

php mini make:controller UserController

🧩 Dependency Injection

BareMetalPHP includes a powerful DI container for managing dependencies:

// Bind an interface to a concrete implementation
$app->bind(LoggerInterface::class, FileLogger::class);

// Bind a singleton
$app->singleton(Database::class, function ($app) {
    return new Database($app['config']['database']);
});

// Resolve from container
$logger = $app->make(LoggerInterface::class);

Controllers automatically resolve dependencies from the container, making testing and maintainability simple.

🎨 Views & Templates

Render views with a simple, intuitive API:

// Return a view
return view('welcome', ['name' => 'Elliot']);

// View with data
return view('posts.index', [
    'posts' => Post::all(),
    'title' => 'All Posts'
]);

Template Example

<!-- resources/views/welcome.php -->
<!DOCTYPE html>
<html>
<head>
    <title>Welcome</title>
</head>
<body>
    <h1>Hello, <?= htmlspecialchars($name) ?>!</h1>
</body>
</html>

🗄 Database & Migrations

Manage your database schema with version-controlled migrations:

Create a Migration

php mini make:migration create_users_table

Run Migrations

php mini migrate

Rollback Migrations

php mini migrate:rollback

Migration Example

use Database\Migration;

return new class extends Migration
{
    public function up()
    {
        $this->schema->create('users', function ($table) {
            $table->id();
            $table->string('name');
            $table->string('email')->unique();
            $table->timestamps();
        });
    }

    public function down()
    {
        $this->schema->drop('users');
    }
};

🧪 Testing

BareMetalPHP includes PHPUnit for testing out of the box:

vendor/bin/phpunit

Test Example

namespace Tests\Feature;

use Tests\TestCase;

class ExampleTest extends TestCase
{
    public function test_homepage()
    {
        $response = $this->get('/');
        
        $response->assertStatus(200);
        $response->assertSee('Welcome');
    }
}

🔧 CLI Commands

The mini CLI provides useful commands for development:

# Start development server
php mini serve

# Go server commands
php mini go:install
php mini go:serve

# Generate code
php mini make:controller UserController
php mini make:migration create_posts_table

# Database
php mini migrate
php mini migrate:rollback

# Run tests
php mini test

🏗 Project Structure

BareMetalPHP follows a clean, intuitive directory structure:

myapp/
├── app/                    # Application code
│   ├── Controllers/        # HTTP controllers
│   ├── Models/            # Data models
│   └── Middleware/        # HTTP middleware
├── config/                # Configuration files
│   ├── app.php
│   ├── database.php
│   └── appserver.php      # Go server config
├── database/              # Database files
│   └── migrations/        # Database migrations
├── public/                # Web root
│   ├── index.php         # Entry point
│   ├── css/
│   ├── js/
│   └── images/
├── routes/                # Route definitions
│   └── web.php
├── server/                # Go runtime source
│   └── main.go
├── php/                   # PHP worker files
│   ├── bootstrap_app.php
│   └── bridge.php
├── resources/             # Views and assets
│   └── views/
├── tests/                 # Test suite
└── vendor/                # Composer dependencies