HivePHP — Custom PHP Framework

HivePHP is a lightweight, educational PHP framework built from scratch to understand the fundamentals of modern PHP application architecture.
It features a front controller, HTTP kernel, middleware support, routing, database migrations, CLI tooling, and a modular service container, inspired by modern frameworks like Laravel.

---

🚀 Features

• Front Controller (public/index.php) – Single entry point for all HTTP requests.
• Bootstrap Loader (bootstrap/app.php) – Initializes the application and registers core services.
• Service Container / IoC – Dependency injection via $app->singleton() and $app->make().
• Configurable Kernel (app/Kernel.php) – Define global middleware and bootstrap logic.
• Middleware Support – Global and route-specific middleware using a pipeline.
• Routing (Framework\Routing\Router) – Fluent API for GET, POST, PUT, DELETE routes.
• Controllers & Providers – Organized structure for controllers and service providers.
• Exception Handling – Centralized exception handler (app/Exceptions/Handler.php).
• Database Layer – Migration runner, database manager, and connection abstractions.
• CLI Tool (Hive) – Artisan-like CLI for generating code, running migrations, and starting the dev server.
• Code Generators – make:controller, make:middleware, make:migration.
• Development Server – Start a local PHP server with serve command.

---

📂 Project Structure

.
├── README.md
├── app
│   ├── Controllers         # Application controllers
│   ├── Exceptions          # Exception handlers
│   ├── Kernel.php          # Application kernel (global middleware)
│   ├── Middleware          # Core middleware
│   ├── Middlewares         # App-level middleware
│   ├── Migrations          # Database migrations
│   └── Providers           # Service providers
├── bootstrap
│   └── app.php             # Bootstraps the application
├── config                  # Configuration files
├── core/src                # Framework core source
│   ├── Application.php
│   ├── Auth                # Authentication drivers & interfaces
│   ├── Bootstrap           # Load configs, env, providers
│   ├── CLI                 # Hive CLI, commands, and stubs
│   ├── Config              # Config loader
│   ├── Container           # Dependency container
│   ├── Database            # DB manager, connections, migrations
│   ├── Exceptions          # Framework-level exception handling
│   ├── Interfaces          # Core interfaces
│   ├── Kernel              # Kernel logic & interfaces
│   ├── Middleware          # Middleware logic & interfaces
│   ├── Pipeline            # Pipeline for middleware processing
│   ├── Providers           # Service providers
│   ├── Repositories        # Example repository (UserRepository)
│   ├── Routing             # Router, route collection, dispatcher, response handling
│   └── Utils               # Helper functions
├── hive                    # CLI runner script
├── public
│   └── index.php           # Front controller
├── routes
│   └── routes.php          # Route definitions
├── server start.bat
└── vendor                  # Composer dependencies

---

⚡ How It Works

1. Front Controller (public/index.php)

• Loads Composer autoload.
• Bootstraps the app (bootstrap/app.php).
• Resolves the Kernel and sends a response.

2. Bootstrap (bootstrap/app.php)

• Creates the application container.
• Sets the base path.
• Registers singletons:
  • Kernel
  • Exception Handler
  • Router
• Returns $app.

3. Kernel (app/Kernel.php)

• Handles the HTTP lifecycle.
• Defines global middleware.
• Passes the request to the router.

4. Router (Framework\Routing\Router)

• Registers GET/POST/PUT/DELETE routes.
• Loads routes from a file (routes/routes.php).
• Applies route-specific middleware using a pipeline.
• Dispatches to controller actions.
• Returns a Symfony Response object.

Example Route File:

use App\Controllers\HomeController;

$router->get('/', [HomeController::class, 'index']);

5. Request Lifecycle

flowchart LR
A[HTTP Request] --> B[Kernel]
B --> C[Global Middleware]
C --> D[Router]
D --> E[Route Match?]
E -->|No| F[404 JSON Response]
E -->|Yes| G[Route-specific Middleware]
G --> H[Controller/Callback Execution]
H --> I[Response Sent]

Loading

---

🖥 Hive CLI

HivePHP includes a CLI runner (hive) for developer tooling:

Available Commands

Command	Description	Example
list	List all available commands	php hive list
serve [host] [port]	Start development server	php hive serve 127.0.0.1 8000
make:controller [name]	Generate a controller	php hive make:controller UserController
make:middleware [name]	Generate middleware	php hive make:middleware AuthMiddleware
make:migration [name]	Create a migration	php hive make:migration create_users_table
migrate	Run migrations	php hive migrate
migrate rollback	Rollback last batch	php hive migrate rollback

Example: Create Controller

php hive make:controller PostController

Generates app/Controllers/PostController.php.

Example: Run Migrations

php hive make:migration create_posts_table
php hive migrate

Example: Start Server

php hive serve localhost 8080

---

🔌 Middleware Example

namespace App\Middleware;

use Framework\Middleware\Interfaces\MiddlewareInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class TrimInputs implements MiddlewareInterface
{
    public function handle(Request $request, callable $next): Response
    {
        $request->request->replace(
            array_map('trim', $request->request->all())
        );
        return $next($request);
    }
}

---

🛠 Requirements

• PHP 8.1+
• Composer

---

🚀 Quick Start

# Install dependencies
composer install

# Start the dev server
php hive serve

# Run migrations
php hive migrate

# Create a new controller
php hive make:controller ExampleController

---

HivePHP is designed for learning, experimentation, and small projects, but its structure and tooling are inspired by production-ready frameworks like Laravel.

🗂 Why a Single Repository?

HivePHP combines both the framework core and the application code in a single repository. This design choice was intentional for several reasons:

1. Learning and Experimentation
   Keeping the core framework and the application together allows for rapid experimentation. You can immediately see how changes in the core affect the app without managing multiple repositories or package versions.

2. Simplicity
   For a learning project, splitting the core into a separate package and publishing it via Composer would add unnecessary complexity. A single repository keeps the workflow straightforward.

3. Ease of Bootstrapping
   New developers or reviewers can clone a single repository and immediately run the application. There is no need to install or link separate packages.

4. Rapid Iteration
   Since the framework is still under development, having everything in one repository allows fast iteration of features like routing, middleware, CLI tools, and migrations without worrying about backward compatibility with a separate package.

💡 In a production-ready setup, the core framework might be split into its own Composer package to be reusable across multiple projects. However, for learning, experimentation, and portfolio purposes, a single repository is the most practical choice.