README

An educational PHP MVC framework designed to teach how modern frameworks work internally.

📚 Read the Documentation

Installation

composer require lighthouse/framework

Requirements

• PHP 8.2 or higher

Quick Start

Create Your Application

public/index.php:

<?php

require __DIR__ . '/../vendor/autoload.php';

use Lighthouse\Application;

$app = new Application(
    basePath: dirname(__DIR__),
    debug: true
);

// Configure views
$app->useViews(__DIR__ . '/../views');

// Define routes
$app->get('/', function () {
    return 'Hello, Lighthouse!';
});

$app->get('/users/{id}', function ($id) {
    return "User: {$id}";
});

// Run the application
$app->run();

Routing

// Basic routes
$app->get('/users', 'UserController@index');
$app->post('/users', 'UserController@store');
$app->put('/users/{id}', 'UserController@update');
$app->delete('/users/{id}', 'UserController@destroy');

// Route groups
$app->group('/api', function ($router) {
    $router->get('/users', 'Api\UserController@index');
    $router->get('/posts', 'Api\PostController@index');
});

// Named routes
$app->get('/users/{id}', 'UserController@show')->name('users.show');

// Generate URLs
$url = $app->url('users.show', ['id' => 123]); // /users/123

Controllers

<?php

namespace App\Controllers;

use Lighthouse\Controller;
use Psr\Http\Message\ServerRequestInterface;

class UserController extends Controller
{
    public function index()
    {
        $users = [
            ['id' => 1, 'name' => 'John'],
            ['id' => 2, 'name' => 'Jane'],
        ];

        return $this->view('users.index', ['users' => $users]);
    }

    public function show(ServerRequestInterface $request, string $id)
    {
        return $this->json(['id' => $id, 'name' => 'John']);
    }

    public function store(ServerRequestInterface $request)
    {
        $data = $request->getParsedBody();
        
        // ... create user
        
        return $this->redirect('/users');
    }
}

Views

views/users/index.php:

<?php $view->extends('layouts.main'); ?>

<?php $view->section('content'); ?>
<h1>Users</h1>
<ul>
    <?php foreach ($users as $user): ?>
        <li><?= $view->e($user['name']) ?></li>
    <?php endforeach; ?>
</ul>
<?php $view->endSection(); ?>

Middleware

use Psr\Http\Message\ServerRequestInterface;
use Psr\Http\Message\ResponseInterface;
use Psr\Http\Server\RequestHandlerInterface;
use Psr\Http\Server\MiddlewareInterface;

class AuthMiddleware implements MiddlewareInterface
{
    public function process(
        ServerRequestInterface $request,
        RequestHandlerInterface $handler
    ): ResponseInterface {
        // Check authentication
        if (!$this->isAuthenticated($request)) {
            return new Response(401);
        }

        return $handler->handle($request);
    }
}

// Add middleware
$app->pipe(new AuthMiddleware());
$app->pipe(function ($request, $handler) {
    // Callable middleware
    $response = $handler->handle($request);
    return $response->withHeader('X-Powered-By', 'Lighthouse');
});

Dependency Injection

// Bind services
$container = $app->getContainer();

$container->bind(UserRepository::class, DatabaseUserRepository::class);
$container->singleton(Logger::class, function ($container) {
    return new FileLogger('/var/log/app.log');
});

// Auto-injection in controllers
class UserController extends Controller
{
    public function __construct(
        Application $app,
        private UserRepository $users,
        private Logger $logger
    ) {
        parent::__construct($app);
    }
}

Error Handling

use Lighthouse\ErrorHandler\Exception\NotFoundException;
use Lighthouse\ErrorHandler\Exception\ForbiddenException;

$app->get('/admin', function () {
    if (!isAdmin()) {
        throw new ForbiddenException('Admin access required');
    }
    
    return 'Admin Panel';
});

$app->get('/users/{id}', function ($id) {
    $user = findUser($id);
    
    if (!$user) {
        throw new NotFoundException("User {$id} not found");
    }
    
    return $user;
});

JSON Responses

// Return array - automatically converted to JSON
$app->get('/api/users', function () {
    return [
        ['id' => 1, 'name' => 'John'],
        ['id' => 2, 'name' => 'Jane'],
    ];
});

// Or use the json helper
$app->get('/api/users/{id}', function ($id) use ($app) {
    return $app->json(['id' => $id], 200);
});

Redirects

$app->post('/login', function () use ($app) {
    // ... authenticate
    
    return $app->redirect('/dashboard');
});

// Redirect to named route
$app->post('/users', function () use ($app) {
    // ... create user
    
    return $app->redirect($app->url('users.index'));
});

Application Structure

my-app/
├── public/
│   └── index.php        # Entry point
├── src/
│   └── Controllers/     # Your controllers
├── views/
│   ├── layouts/         # Layout templates
│   └── users/           # View templates
├── config/
│   └── app.php          # Configuration
├── vendor/
└── composer.json

Architecture

Lighthouse is built from these independent packages:

Each package can be used independently or as part of the full framework.

Educational Purpose

This framework is designed to be read and understood. It accompanies an educational book that teaches:

• How HTTP request/response works
• What dependency injection really does
• How routing matches URLs to code
• Why middleware is powerful
• How view engines work
• Best practices for error handling

The goal is not to replace Laravel or Symfony, but to make them understandable.

API Reference

Application

Controller

Testing

composer test

License

MIT License. See LICENSE for details.

Part of the Lighthouse Project

This is the main framework package of the Lighthouse Project, an educational PHP framework designed to teach how modern frameworks work internally.

Happy learning! 🚀