refactor: Implement core architectural improvements

This commit introduces a major architectural refactoring to improve the framework's robustness and align it with modern PHP best practices, making it a better educational tool.

Key changes include:

- **Request/Response Objects:** Abstracted the HTTP layer by creating `Core\Http\Request` and `Core\Http\Response`. The application now uses these objects instead of relying on global variables like `$_SERVER`, `$_POST`, etc. This improves testability and code clarity.

- **Service Container:** Added a simple `Core\Container` for dependency injection. Core services, such as the Router, are now registered as singletons and resolved from the container, which centralizes dependency management and increases flexibility.

- **Exception Handling:** Overhauled the error handling mechanism. The Router now throws exceptions (e.g., `Core\Exception\NotFoundException`) for errors like missing routes. A centralized `Core\ExceptionHandler` catches these exceptions and renders appropriate user-friendly error pages (404, 500). Also added the corresponding view files for the error pages.

Author: google-labs-jules[bot]

.gitignore

@@ -21,3 +21,4 @@ public/assets/*
 public/storage/*
 
 .php-cs-fixer.cache
+server.log

app/Controllers/HomeController.php

@@ -3,12 +3,14 @@
 namespace App\Controllers;
 
 use Core\Controller;
+use Core\Http\Request;
+use Core\Http\Response;
 
 class HomeController extends Controller
 {
-    public function index(): void
+    public function index(Request $request): Response
     {
-        $this->render('home', [
+        return $this->render('home', [
           'title' => 'Home - PHPure',
           'message' => 'Welcome to PHPure Framework!',
         ]);

app/routes.php

@@ -1,10 +1,20 @@
 <?php
 
+use Core\App;
+use Core\Http\Request;
 use Core\Http\Router;
 
-$router = new Router();
+// Resolve the router from the container
+$router = App::container()->resolve(Router::class);
 
-// TODO: Define routes here
+// Define routes here
 $router->get('', ['HomeController', 'index']);
 
-$router->dispatch();
+// Create a request from globals
+$request = new Request();
+
+// Dispatch the router and get a response
+$response = $router->dispatch($request);
+
+// Send the response to the browser
+$response->send();

core/App.php

@@ -7,10 +7,25 @@
 
 class App
 {
+    protected static Container $container;
+
+    public function __construct(Container $container)
+    {
+        static::$container = $container;
+    }
+
+    /**
+     * Get the service container.
+     */
+    public static function container(): Container
+    {
+        return static::$container;
+    }
+
     /**
      * Bootstrap the application
      */
-    public static function bootstrap(): void
+    public function bootstrap(): void
     {
         // 1. Load environment variables
         loadEnv();
@@ -20,21 +35,17 @@ public static function bootstrap(): void
 
         // 3. Enable Whoops if debug mode is enabled
         if (config('app.debug', true)) {
-            self::enableWhoops();
+            $this->enableWhoops();
         }
 
         // 4. Start the session
         Session::start();
-
-        // 5. Load the event and route configuration files
-        require_once BASE_PATH . '/app/events.php';
-        require_once BASE_PATH . '/app/routes.php';
     }
 
     /**
      * Enable Whoops
      */
-    public static function enableWhoops(): void
+    public function enableWhoops(): void
     {
         $whoops = new Run();
         $whoops->pushHandler(new PrettyPageHandler());

core/Container.php

@@ -0,0 +1,75 @@
+<?php
+
+namespace Core;
+
+use Closure;
+use Exception;
+
+class Container
+{
+    protected array $bindings = [];
+    protected array $instances = [];
+
+    /**
+     * Bind a resolver into the container.
+     *
+     * @param string $key The abstract key (e.g., 'router' or Router::class).
+     * @param Closure|string|null $concrete The concrete resolver or class name.
+     * @param bool $singleton Whether the binding should be a singleton.
+     */
+    public function bind(string $key, Closure|string|null $concrete = null, bool $singleton = false): void
+    {
+        if (is_null($concrete)) {
+            $concrete = $key;
+        }
+
+        $this->bindings[$key] = compact('concrete', 'singleton');
+    }
+
+    /**
+     * Register a shared (singleton) binding in the container.
+     *
+     * @param string $key
+     * @param Closure|string|null $concrete
+     */
+    public function singleton(string $key, Closure|string|null $concrete = null): void
+    {
+        $this->bind($key, $concrete, true);
+    }
+
+    /**
+     * Resolve the given type from the container.
+     *
+     * @param string $key
+     * @return mixed
+     * @throws Exception
+     */
+    public function resolve(string $key): mixed
+    {
+        // If the instance already exists as a singleton, return it.
+        if (isset($this->instances[$key])) {
+            return $this->instances[$key];
+        }
+
+        if (!isset($this->bindings[$key])) {
+            throw new Exception("No binding found for '{$key}'");
+        }
+
+        $resolver = $this->bindings[$key]['concrete'];
+
+        // If the resolver is not a closure, it's a class name.
+        if (!$resolver instanceof Closure) {
+            // Here you could add auto-wiring with reflection, but for a simple container, we'll keep it basic.
+            return new $resolver();
+        }
+
+        $instance = $resolver($this);
+
+        // If it's a singleton, store the instance.
+        if ($this->bindings[$key]['singleton']) {
+            $this->instances[$key] = $instance;
+        }
+
+        return $instance;
+    }
+}

core/Controller.php

@@ -2,6 +2,7 @@
 
 namespace Core;
 
+use Core\Http\Response;
 use Twig\Error\LoaderError;
 use Twig\Error\RuntimeError;
 use Twig\Error\SyntaxError;
@@ -15,8 +16,10 @@ class Controller
      * @throws RuntimeError
      * @throws LoaderError
      */
-    protected function render(string $view, array $data = []): void
+    protected function render(string $view, array $data = []): Response
     {
-        echo Twig::getInstance()->render($view . '.html.twig', $data);
+        $content = Twig::getInstance()->render($view . '.html.twig', $data);
+
+        return new Response($content);
     }
 }

core/Exception/NotFoundException.php

@@ -0,0 +1,11 @@
+<?php
+
+namespace Core\Exception;
+
+use Exception;
+
+class NotFoundException extends Exception
+{
+    protected $message = 'Page Not Found';
+    protected $code = 404;
+}

core/ExceptionHandler.php

@@ -20,12 +20,21 @@ public static function handleException(\Throwable $exception): void
     {
         // Log the error
         Logger::error($exception->getMessage(), [
-          'file' => $exception->getFile(),
-          'line' => $exception->getLine(),
-          'trace' => $exception->getTraceAsString(),
+            'file' => $exception->getFile(),
+            'line' => $exception->getLine(),
+            'trace' => $exception->getTraceAsString(),
         ]);
 
-        // Display the error page
+        // Handle NotFoundException specifically
+        if ($exception instanceof \Core\Exception\NotFoundException) {
+            http_response_code(404);
+            // In a real app, you'd want a nice 404 page.
+            // We assume one exists in Twig. If not, this will error.
+            echo Twig::getInstance()->render('errors/404.html.twig', ['message' => $exception->getMessage()]);
+            return;
+        }
+
+        // Display the generic error page for all other exceptions
         if (getenv('APP_ENV') === 'production') {
             http_response_code(500);
             echo Twig::getInstance()->render('errors/500.html.twig');

core/Http/Request.php

@@ -4,73 +4,46 @@
 
 class Request
 {
-    /**
-     * Get data from input
-     */
-    public static function input(string $key, $default = null)
-    {
-        return $_POST[$key] ?? $_GET[$key] ?? $default;
-    }
+    public readonly array $query;
+    public readonly array $data;
+    public readonly array $server;
 
-    /**
-     * Get data from query string
-     */
-    public static function query(string $key, $default = null)
+    public function __construct()
     {
-        return $_GET[$key] ?? $default;
+        $this->query = $_GET;
+        $this->data = $_POST;
+        $this->server = $_SERVER;
     }
 
     /**
-     * Get all data sent to the server
+     * Get the request URI path.
      */
-    public static function all(): array
+    public function getPath(): string
     {
-        return array_merge($_GET, $_POST);
+        return trim(parse_url($this->server['REQUEST_URI'], PHP_URL_PATH), '/');
     }
 
     /**
-     * Get the request method
+     * Get the request method.
      */
-    public static function method(): string
+    public function getMethod(): string
     {
-        return strtoupper($_SERVER['REQUEST_METHOD'] ?? 'GET');
-    }
-
-    /**
-     * Get the URI
-     */
-    public static function uri(): string
-    {
-        return $_SERVER['REQUEST_URI'] ?? '/';
-    }
-
-    /**
-     * Get the sanitized data
-     */
-    public static function sanitize(string $key, $default = null)
-    {
-        $value = self::input($key, $default);
-        if (is_string($value)) {
-            return htmlspecialchars($value, ENT_QUOTES, 'UTF-8');
-        }
-
-        return $value;
+        return $this->server['REQUEST_METHOD'];
     }
 
     /**
-     * Check if the request is an Ajax request
+     * Get a value from the POST data.
      */
-    public static function isAjax(): bool
+    public function get(string $key, $default = null)
     {
-        return isset($_SERVER['HTTP_X_REQUESTED_WITH']) &&
-          strtolower($_SERVER['HTTP_X_REQUESTED_WITH']) === 'xmlhttprequest';
+        return $this->data[$key] ?? $default;
     }
 
     /**
-     * Get the IP address of the user
+     * Get a value from the GET query string.
      */
-    public static function ip(): string
+    public function query(string $key, $default = null)
     {
-        return $_SERVER['REMOTE_ADDR'] ?? '0.0.0.0';
+        return $this->query[$key] ?? $default;
     }
 }

core/Http/Response.php

@@ -4,40 +4,57 @@
 
 class Response
 {
+    protected mixed $content;
+    protected int $statusCode;
+    protected array $headers;
+
+    public function __construct(mixed $content = '', int $statusCode = 200, array $headers = [])
+    {
+        $this->content = $content;
+        $this->statusCode = $statusCode;
+        $this->headers = $headers;
+    }
+
     /**
-     * Send a JSON response
+     * Set the HTTP status code.
      */
-    public static function json(array $data, int $status = 200): void
+    public function setStatusCode(int $code): self
     {
-        http_response_code($status);
-        header('Content-Type: application/json');
-        echo json_encode($data);
+        $this->statusCode = $code;
+        return $this;
     }
 
     /**
-     * Redirect to a URL
+     * Add a header to the response.
      */
-    public static function redirect(string $url, int $status = 302): void
+    public function addHeader(string $name, string $value): self
     {
-        http_response_code($status);
-        header("Location: $url");
-        exit;
+        $this->headers[$name] = $value;
+        return $this;
     }
 
     /**
-     * Send a response
+     * Send the response to the client.
      */
-    public static function send(string $content, int $status = 200): void
+    public function send(): void
     {
-        http_response_code($status);
-        echo $content;
+        // Send status code
+        http_response_code($this->statusCode);
+
+        // Send headers
+        foreach ($this->headers as $name => $value) {
+            header("$name: $value");
+        }
+
+        // Send content
+        echo $this->content;
     }
 
     /**
-     * Set a header
+     * Factory method to create a new Response.
      */
-    public static function setHeader(string $name, string $value): void
+    public static function create(mixed $content = '', int $statusCode = 200, array $headers = []): self
     {
-        header("$name: $value");
+        return new static($content, $statusCode, $headers);
     }
 }