Skip to content

TODO.md

Latest commit

 

History

History
366 lines (291 loc) · 16.9 KB

TODO.md

File metadata and controls

366 lines (291 loc) · 16.9 KB
Raw

SilverEngine Core Package Migration

Goal

Extract System/ into a standalone Composer package silverengine/core living in Packages/silverengine/core/, the same way silverengine/error-handler already works. Modernise every migrated file to PHP 8.4+ idioms as it moves.

Strategy: incremental migration — move files to package, modernize to PHP 8.4+, delete from System/. Unmigrated files stay in System/ via root PSR-4 fallback. Framework stays bootable at every step.

Dependencies added: vlucas/phpdotenv, nejcc/php-datatypes

Naming: Blueprints renamed to Contracts, MigrationCore to MigrationInterface

Phase 0 — Scaffold the package [DONE]

  • Create Packages/silverengine/core/composer.json (php >=8.4, vlucas/phpdotenv)
  • Create Packages/silverengine/core/src/ directory tree
  • Add silverengine/core + nejcc/php-datatypes as deps in root composer.json
  • Run composer update — autoload resolves from package
  • Root Silver\\ PSR-4 kept as fallback for unmigrated files

Phase 1 — Core kernel [DONE]

  • Core/Env.php — rewritten for vlucas/phpdotenv, typed properties
  • Core/Config.php — typed returns
  • Core/App.php — typed properties, implements InstanceInterface
  • Core/Instances.php — fully typed container
  • Core/DI.php — ReflectionNamedType (replaces deprecated getClass())
  • Core/Kernel.php — never return, arrow fn middleware chain
  • Core/Route.php — str_starts_with/str_ends_with, throw expressions
  • Core/Controller.php — declared $controllerName, fixed types
  • Core/Model.php — declared all subclass properties, removed unused
  • Core/Library.php — typed params, never return on dd()
  • Core/ErrorHandler.php — handles \Throwable, never on finalize()
  • Core/Bootstrap.php — readonly property
  • Core/AppInstanceTrait.php — static return type
  • Core/helpers.php — env() helper with match expression
  • Old System/Core/ files deleted, package loads confirmed
  • .env file created (replaces local.env.php approach)
  • public/index.php rewritten (dotenv, first-class callables for error handlers)
  • silver CLI entry point modernized

Phase 2 — Contracts (was Blueprints) [DONE]

  • Core/Contracts/InstanceInterface.php — static return type
  • Core/Contracts/MiddlewareInterface.php — : mixed return
  • Core/Contracts/RenderInterface.php — : string, : array returns
  • Core/Contracts/Http/RequestInterface.php — typed returns
  • Core/Contracts/Http/ResponseInterface.php
  • Core/Contracts/Database/MigrationInterface.php — renamed from MigrationCore
  • All System/ and App/ implementors updated to use Contracts namespace
  • Old System/Core/Blueprints/ deleted

Phase 3 — Bootstrap & Facades [DONE]

  • Core/Bootstrap/Autoload.php — str_starts_with()
  • Core/Bootstrap/ServiceProvider.php — typed params
  • Core/Bootstrap/Facades/Request.php — final, typed return
  • Core/Bootstrap/Facades/Response.php — final, typed return
  • Core/Bootstrap/Facades/Log.php — final, typed return
  • Core/Bootstrap/Facades/FakeFactory.php — final, typed return
  • Core/Storage/Cache.php — final, typed properties, fixed $time_or_predictor bug
  • Core/Http/Lang.php — final, null-safe

Phase 8 — Exceptions [DONE — moved early, no deps]

  • Exception/Exception.php — ?\Throwable previous param
  • Exception/ErrorException.php — final
  • Exception/NotFoundException.php — final

final keyword applied to [DONE]

Env, Config, DI, Instances, Bootstrap, ErrorHandler, Cache, Lang, all 4 Facades, ErrorException, NotFoundException

Phase 4 — HTTP layer [DONE]

  • Http/Request.php — typed properties, str_starts_with, ?Route return
  • Http/Response.php — nested match for content dispatch, RenderInterface
  • Http/Session.php — final, removed side-effect auto-call
  • Http/Cookie.php — final, match for return types
  • Http/Curl.php — final, removed deprecated curl_close()
  • Http/Redirect.php — final, never return types
  • Http/Validator.php — final, string|false return types
  • Http/View.php — DRY template extension loop, str_starts_with

Phase 5 — Database / Query Builder [DONE]

  • 55 files migrated: Db, Query, Model, Compiler, QueryObject, Relation, Source, DBCreator
  • Parts/* (20 files), Query/* (10 files), Traits/* (8 files), Source/* (3 files)
  • DB-specific variants: Mysql/, Pgsql/, Sqlite/
  • declare(strict_types=1) added to all files
  • Fixed $self::isDebug() typo in Db.php
  • SQLite connection verified

Phase 6 — Support & Helpers [DONE]

  • Support/Facade.php — abstract base, lazy singleton ??=
  • Support/Fake.php — final, DRY via __callStatic + const array
  • Support/FakeFactory.php — const array data, random_int()
  • Support/Log.php — final, typed const array TYPES
  • Support/Crypter.php — final, match for alphabet, random_int()
  • Support/Git.php — final, readonly branch property
  • Support/SMail.php — final, typed properties, fluent builder
  • Helpers/Str.php — renamed from String (reserved word), wraps builtins
  • Helpers/Path.php — final, str_starts_with
  • Helpers/URL.php — str_starts_with/str_ends_with
  • Helpers/HTMLElement.php — typed constructor, union types

Phase 7 — Engines [DONE]

  • Engine/CLI.php — match expressions, never return, DRY resolvePaths
  • Engine/Events/EventManager.php — fixed namespace, typed, removed debug echo
  • Engine/Ghost/Template.php — DRY processLines() helper, arrow fns

Phase 9 — System App (framework defaults) [DONE]

  • App/Controllers/SystemController.php — typed return
  • App/Controllers/MigrationsController.php — string|false union type
  • App/Middlewares/* — all final, MiddlewareInterface, \Throwable catch
  • App/Routes.php — strict comparison
  • App/Views/* — copied to package
  • Config/Routes.php updated to point to package path

Phase 10 — Cleanup & finalize [DONE]

  • System/ directory deleted entirely
  • "Silver\\": "System/" removed from root composer.json
  • Config/Providers.php — removed stale Silver => System mapping
  • Config/Routes.php — updated system routes path
  • Clean boot verified (zero warnings)
  • Run full test suite (Tests/) — PHPUnit ^12 added as require-dev (dev-only, runtime stays dependency-light). Suite green: 14 tests, 19 assertions, 1 skipped (network-only Curl test).
  • Update error-handler to php >=8.4 — resolved by removal: package absorbed into silverengine/core (Silver\ErrorHandler\Reporter), second path repo dropped
  • Tag silverengine/core v0.1.0 — intentionally deferred (tag step skipped by request; code is tag-ready)

Future Enhancements

  • Shared view data — unified View::share() store, available in Ghost views AND Wisp pages (Wisp::share() delegates to it)
  • View composers — View::composer($pattern, $cb), exact + fnmatch wildcard, merged at render via View::sharedFor()
  • Request improvements — typed headerValue(), hasHeader(), query(), json(), bool(), int(), wantsJson(); WispResponse + Wisp middleware refactored off raw $_SERVER

Frontend (Wisp) — DONE

  • Vite + Vue 3 + TypeScript + Tailwind 4, official @inertiajs/vue3 client
  • First-party Silver\Engine\Ghost\{Wisp,WispResponse,Vite,LazyProp,DeferProp}, {{ wisp() }} / {{ vite() }} directives, wisp() helper
  • Inertia wire protocol (X-Inertia headers), version 409 / 303 handshake middleware
  • Lazy + deferred props, partial reloads, prefetch-ready deferredProps
  • composer dev runs PHP + Vite concurrently; composer serve = PHP only

PHP 8.4+ Refactoring Checklist (apply to every migrated file)

  • declare(strict_types=1);
  • Typed / readonly properties
  • Constructor promotion
  • match instead of switch
  • str_starts_with / str_ends_with / str_contains
  • Union / intersection / nullable types
  • final on leaf classes
  • First-class callable syntax ($this->method(...))
  • never return type
  • Enums for finite value sets — Silver\Http\HttpMethod, Silver\Database\DbDriver, Silver\Support\LogType, Silver\Support\PasswordCharset
  • array_find, array_any, array_all (PHP 8.4+) — Response::send() (array_find), View::sharedFor() (array_any); remaining loops are accumulation/transform, not idiomatic candidates
  • [~] Property hooks where they simplify getters/setters — no behaviour-preserving application in core: every get/set is public method API (converting breaks callers), and the only magic accessors (QueryObject) are a dynamic property bag hooks can't model. Deferred to Phase B (where API changes are in scope).
  • Remove remaining legacy phpdoc that duplicates native types — Db/Query/Model/DBCreator stripped of zero-info tags; provably-safe native return types added; informative phpdoc kept

Phase A — Quality pass (checklist completion) [DONE, untagged]

Mechanical-first, behaviour-preserving. PHPUnit ^12 dev-only baseline. 5 commits. Flagged for follow-up (Phase B / separate fix):

  • Database/DBCreator.php — dead code, zero references; candidate for deletion
  • ColumnDef::compileReference() ON UPDATE spacing bug — fixed (fix(db)); referential actions still an enum candidate for Phase B
  • Ambiguous return types left untyped: Db::{toSql,isDebug,quote,commit, transaction,driverName,fetch}, QueryObject::__get/__set

Phase B — Design-pattern audit (full audit, API changes allowed)

Test-first: characterization tests pin observable behaviour BEFORE each structural change. Per-batch gate (tests → refactor → suite green → commit). PHPUnit baseline grew 8 → 35 tests, 62 assertions, 1 skipped.

Done

  • B6 — drop legacy $_ member prefix. Route private/static members $_foo → $foo ($jails/static→$jailStack; PHP forbids same-name instance+static). QueryObject::$_table/$_primary → $table/$primaryKey (typed ?string, kept static — static active-record needs table/PK without an instance); migrated App/Models/Users.php. Tests: RouteTest, QueryObjectTest.

  • B1 — dialect Strategy. Extracted Silver\Database\Dialect (segment()/classFor()) from the inline Compiler::toSql() ucfirst+substr_replace+class_exists; uses DbDriver enum, identical fallback. Tests: DialectCompileTest (SQL pinned pre-refactor), DialectTest.

  • B2 — Query factory + QueryType enum. Replaced stringly Query::instance(); queryClass()/make() resolve the identical FQN. Test: QueryTypeTest (enum map + insert/update/delete/drop SQL pinned).

  • B3 — CLI Command enum. Replaced match($this->cmd) literals; alias-aware parse() (c→Generate, unknown→null). Proportionate — no class-per-command framework. Test: CommandTest.

  • B4 — split the Db God class. Extracted ConnectionManager (registry/lazy-PDO/raw/exec/quote/lastInsertId/driverName) and TransactionManager (depth counter + nested BEGIN/COMMIT/ROLLBACK + SAVEPOINT levels, savepoint SQL still via Db::exec() for the debug echo). Db is now a thin BC facade keeping only the per-instance fetch/debug side; every Db::/Query::/Model:: static entry point unchanged. Found + fixed a pre-existing bug first (separate fix(db)): class_exists($style) before a string check threw TypeError under strict_types — all builder result-fetch with default style was broken. Tests: DbBehaviorTest (10, characterization pinned pre-refactor), DbFetchTest (5, TDD red→green for the bug). Ambiguous returns (Db::{toSql,isDebug,quote,commit,transaction,driverName,fetch}) left untyped — separate optional polish, see backlog.

Remaining — large, high-blast-radius (checkpoint: do as focused sessions)

  • B5 — real IoC container. Today Instances is a registry, not a container. Add bind() / singleton() / interface→impl / closure factories / recursive autowiring + constructor injection for controllers & middleware. Plan: (1) characterization of the current shallow DI::call contract (method injection by class name + route vars); (2) introduce Container (autowiring + bindings) keeping DI::call semantics as the method-injection front end; (3) constructor-inject controllers in Kernel::findCallable and new $mw() in loadMiddlewares; (4) unify the 3 singleton mechanisms; route Facade through the container; (5) fix the ServiceProvider contract.

Findings backlog (surfaced during A/B, not silently changed)

  • Database/DBCreator.php — dead code, zero refs; delete candidate.
  • Builder fetch class_exists(int) TypeError — fixed (fix(db), TDD, DbFetchTest).
  • Ambiguous return types still untyped (optional polish, low value): Db::{toSql,isDebug,quote,commit,transaction,driverName,fetch}, QueryObject::__get/__set (dynamic property bag — not a property-hook candidate).
  • Route::url() depends on the global BASEPATH constant defined only by public/index.php — should come via config/container (B5). Test env defines BASEPATH=''.
  • Dual Model lineage: Silver\Database\Model (static active- record, extends QueryObject) vs Silver\Core\Model (instance, protected string $primaryKey). Reconcile/clarify in B4.
  • ServiceProvider interface (before(mixed $kernel)/register(mixed $app)/after()) does not match how Kernel invokes providers (before($req,$res)/after($req,$res), register() never called). Fix in B5.
  • Dead Kernel::call() static (duplicates DI, no callers) — remove in B5.
  • Facade keeps its own static $objects cache outside Instances — same class can exist twice. Unify in B5.
  • Cosmetic: Query\Delete compiles DELETE FROM (double space) — valid SQL, left verbatim (behaviour-preserving); tidy opportunistically.

Phase C — Runtime performance [measure-first; DONE]

Profiled with the in-repo DebugTimer/RequestRecorder over 50 recorded requests (/, /wisp-demo, /demo) on the php -S dev server.

Measured baseline (median ms)

phase dev server warm process
Env::construct 6.32 0.77
view render 1.53 —
per middleware (×5) ~1.2–1.5 —
database connect 1.38 —
controller resolve 0.74 —
controller action 0.38 —
route resolve 0.014 —
services 0.008 —
boot header (autoload→mw) 21.65 —

Conclusion (data, not guesswork)

  • The apparent Env::construct hot spot is a no-opcache artifact: this runtime has no opcache at all, so php -S recompiles every file every request. Warm (single long-lived process, mimicking php-fpm+opcache) Env::construct is 0.77 ms, and the json_decode(json_encode()) config clone I suspected is 0.035 ms — hypothesis rejected by measurement.
  • No code path is algorithmically slow. Route match 0.014 ms, services 0.008 ms, controller action 0.38 ms. Speculative code micro-optimisation would add risk for zero proven gain — explicitly against measure-first.

Changes (zero behaviour risk)

  • composer.json → config.optimize-autoloader: true (+ sort-packages): every composer install now emits a classmap with PSR-4 fallback. Dev boot 21.65 → 20.62 ms; the real benefit is production scale (no per-class PSR-4 stat walk).

Deployment levers (the actual wins — documentation, not code)

  • opcache is the dominant production lever. With php-fpm + opcache the boot collapses toward the warm numbers (~3–5 ms total vs ~21 ms). No code change can match this; it is a deploy requirement.
  • Do NOT use classmap-authoritative with this framework. It would break correctness: Kernel::findCallable() resolves App controllers by file convention (include_once + new $class), and Dialect::classFor() / QueryType rely on class_exists() for optional dialect/query variants — an authoritative classmap returns false for anything not pre-listed (user controllers, dialect variants), breaking dynamic resolution. optimize-autoloader is the correct, safe choice (classmap + PSR-4 fallback).

All phases (A, B, C) complete. Remaining items live in the findings backlog above (dead DBCreator, optional Db facade return-typing).