Diagnosis and Adaptation Plan to PHP 8.5.1 - Alxarafe

This document summarizes the current state of the Alxarafe core and proposes a roadmap to leverage the capabilities of PHP 8.5.1.

1. General Architecture Diagnosis

The microframework core presents a solid base but with technical debt accumulated in patterns that PHP 8.x allows modernizing.

Critical Points Identified

• Dependence on Static States: Extensive use of static methods in Database, Trans, Debug, and Routes hinders testability and decoupling.
• Abuse of stdClass: Configuration and data handling rely on anonymous objects, losing the benefits of strong PHP typing.
• Magic in DTOs: The DtoTrait uses magic methods (__get, __set) that can be replaced by more efficient native features.
• Lifecycle Management: Usage of die() and header() within library functions interrupts the controlled application flow.

---

2. Improvement Recommendations for PHP 8.5.1

A. Implementation of Property Hooks (PHP 8.4+)

Replace the magic method logic in DtoTrait with native hooks. This allows data validations and transformations directly in the property definition, improving performance and readability.

B. Readonly Classes and Typed DTOs

Migrate all configuration structures (currently in Config.php) and data objects to readonly classes.

• Benefit: Guaranteed immutability and full IDE autocompletion without relying on PHPDoc comments for stdClass.

C. Constructor Property Promotion

Simplify controller and service constructors by eliminating repetitive property declarations.

D. Routing System and Dispatcher Modernization

• Route Cache: The current system scans directories with glob on every request. It is recommended to implement a cache generator that produces a route map in a static PHP file.
• Middleware: Introduce a middleware layer to handle authentication and initialization, eliminating manual redirection logic in controller constructors.

E. Strict Typing and Returns

Ensure all files include declare(strict_types=1); and all methods have defined return types, eliminating the use of mixed where possible.

---

3. Suggested Roadmap

1. Phase 1: DTO and Model Modernization
   • Refactor DtoTrait to use Property Hooks.
   • Introduce data classes for configurations.
2. Phase 2: Dependency Cleanup
   • Update Illuminate components to version 11.
   • Evaluate replacing jenssegers/blade with the native Illuminate\View engine.
3. Phase 3: Execution Flow Refactoring
   • Migrate the Dispatcher to an event-based or middleware model.
   • Eliminate die() calls and centralize HTTP response management.

---

Document generated by Junie (JetBrains AI) on February 1, 2026.