Framework Laravel Package

Technical Evaluation

Architecture fit

• codeigniter4/framework is a full-stack MVC framework, not a composable library. It is a peer/alternative to Laravel, not an add-on — the "Laravel/PHP package" framing needs correcting before any scoping: there is no Illuminate service-provider integration, no Laravel package discovery, no shared container.
• Consequence for a TPM: the realistic leverage models are (a) greenfield bounded service or API built on CI4, (b) CI3 → CI4 modernization of an existing app, (c) a deliberately small-footprint sidecar service deployed next to a Laravel monolith. Pulling CI4 into an existing Laravel codebase is not a supported integration and should be rejected at intake.
• Strengths that map to product decisions: MIT license (no commercial negotiation), a documented public-API compatibility contract, and a defined deprecation lifecycle — all reduce vendor and upgrade risk relative to less disciplined OSS frameworks.

Integration feasibility

• Technically installable via Composer, but the framework assumes ownership of the application skeleton (app/, public/index.php, writable/, spark). It will collide with a host application's bootstrap, global helper functions, and autoload conventions. Integration therefore happens at the deployment boundary (separate container/vhost, shared database schema, HTTP/JSON or queue contracts), not the code boundary.
• Two genuine integration wins exist and should be evaluated explicitly:
  • FrankenPHP Worker Mode — boot-once, serve-many execution model (the CI4 analogue of Octane). Meaningful throughput/latency upside for high-RPS endpoints, but it converts the deployment into a long-running process with a new class of correctness risk.
  • php spark CLI + Commands — useful for scheduled jobs and operational tooling without adding a separate worker stack.

Technical risk

• PHP 8.2 floor, enforced by policy. Framework code must run on 8.2 even where newer runtimes are installed. This caps our ability to standardize the fleet on a newer runtime without forking or accepting untested paths.
• Compatibility surface is broad and explicitly enumerated: signatures, properties, constants, defaults, exceptions, side effects, configuration, and generated project files are all compatibility-sensitive. That is good governance but it also means upgrade diffs can be behaviorally subtle.
• Worker Mode state leakage is the top technical risk. Process-lifetime vs. request-specific state must be classified and reset per request; the entry-point template (system/Commands/Worker/Views/frankenphp-worker.php.tpl) is the source of truth and must be republished with php spark worker:install --force on qualifying releases. Skipping that step produces silent divergence between our deployment and the framework's expected bootstrap ordering.
• Type-system friction: declare(strict_types=1) is applied unevenly and the Rector exclusions are treated as intentional compatibility constraints. Expect occasional strict-vs-coercive comparison surprises at boundaries.
• Static analysis baselines and "focused validation only" policy mean the framework's own CI is the authoritative gate. We inherit whatever the baseline suppresses; we cannot audit that cheaply.
• Data-quality flags on the inputs: Dependents: 0 is almost certainly a measurement artifact (Packagist/GitHub graph not captured) and should not be read as low adoption; the 2026-10-09 last-release date is in the future and should be validated against Packagist before being cited in any plan. Score 68.57 with opportunity 45.81 suggests solid maturity, modest headroom — consistent with a stable-but-not-fast-moving framework.

Key questions

1. Is this replacing part of the Laravel estate or co-existing? (Co-existence only, realistically.)
2. Who owns the framework upgrade treadmill, and what is the funded cadence per minor line?
3. Do we need Worker Mode, or is PHP-FPM sufficient? (This single answer changes the risk profile materially.)
4. What is our runtime baseline commitment — are we willing to hold PHP 8.2 for the life of the service?
5. Which minor line do we pin, and what is our policy for narrow, documented breaks on 4.*?
6. What is the support/EOL commitment for security fixes on the line we pick, given there is no commercial LTS from the project itself?

Integration Approach

Stack fit

• Adopt as a standalone deployable, not an embedded dependency. One service, one CI4 app, one container. Communicate with the Laravel estate over HTTP (OpenAPI-documented), a shared database schema owned by exactly one service, or a message bus.
• Share infrastructure, not code: same CI runner, same observability agent, same secrets manager, same base image (pinned to a PHP 8.2-compatible tag).
• Do not attempt to share models, auth, or session stores across the Laravel/CI4 boundary. Auth should be delegated to a single identity provider.

Migration path

• CI3 → CI4 is the strongest business case: it is the framework's own supported forward path, and it retires an unmaintained codebase. Budget it as a rewrite, not an upgrade — namespaced app/, config-as-PHP-classes, removal of $this->load, changed DB and validation APIs.
• Laravel → CI4 should be declined unless there is a hard constraint (footprint, licensing posture, team skills, legacy CI3 estate). Functionally it is a capability reduction (no Eloquent-equivalent ORM ergonomics, smaller package market, thinner first-party tooling).
• New build on CI4 is the cleanest path and where the package's leverage is highest.

Compatibility

• Pin to a specific minor line and treat the project's stated policy as our contract: patch lines (develop) admit no intentional breaks; minor lines (4.*) admit narrow, justified, documented breaks with tests, changelog, and upgrading-guide entries.
• Deprecated APIs are removable no earlier than the second subsequent minor. Encode that as an internal SLA: deprecation notices in our build logs must be resolved within two minor cycles, or we will be forced into an unscheduled upgrade.
• Treat the upgrading guide as a required read for every minor bump, not a break-glass document.

Sequencing

1. Spike (1–2 weeks): one bounded service, PHP-FPM only, standard Composer scaffolding. Confirm build, deploy, observability, and CI integration with our existing pipeline.
2. Upgrade runbook: write and rehearse a minor upgrade (pin → bump → run focused test suite → review upgrading guide → release). This is the deliverable that determines long-term cost.
3. Worker Mode decision: benchmark against PHP-FPM. Adopt only if the throughput/latency gain justifies the state-hygiene ownership cost. If adopted, add template republication to the runbook as a mandatory step.
4. Team enablement: ramp plan and coding-standard alignment (strict types, PHPStan usage without baseline edits, focused-test discipline) before the second service.
5. Scale-out: only after steps 1–4 have produced evidence; do not standardize the organization on CI4 on the strength of the spike alone.

Operational Impact

Maintenance

• Steady-state cost is a per-minor upgrade cycle: dependency bump, upgrading-guide review, focused test run, changelog entry. Low but non-zero, and it recurs whether or not we ship features. Fund it as a recurring line item, not a project.
• The project's own guidance is to run only the narrowest relevant tests locally and defer full CI to GitHub Actions. We cannot lean on the upstream suite as our regression net — our own test coverage is the safety net, which is a real investment item.
• Configuration-as-PHP-classes and generated project files are compatibility-sensitive, meaning merged config files and locally edited bootstrap files are upgrade-fragile. Keep customizations in our own classes, never in generated files.

Support

• MIT, community-driven; support arrives via documentation, forums/Discord, and issue tracker. There is no first-party commercial LTS — if the business requires a vendor SLA, that must be purchased from a third party or absorbed internally.
• Bus factor and release cadence are governed by a documented review policy, which is a positive signal for a 5.9k-star project, but TPM should confirm the security-fix policy for the specific minor line we pin and record it as an accepted risk.

Scaling

• Horizontal scaling via PHP-FPM is the well-understood default: stateless containers, shared session/cache backend, no new operational model.
• Worker Mode improves per-request efficiency (boot once, serve many) but changes the scaling unit to a long-lived process. That means: careful worker-count sizing against CPU/memory, graceful restarts on deploy, and no assumption that per-request teardown cleans up state for you.
• Database access uses the framework's own Query Builder/Model layer; connection pooling and reconnection ordering under Worker Mode must be explicitly validated.

Failure modes

• Worker Mode state leakage — request-specific data (superglobals, sessions, services, toolbar/event state, static caches) surviving into the next request. Highest-severity, hardest to reproduce, and only visible under load or in production.
• Stale worker entry point — a release changes frankenphp-worker.php.tpl, we don't republish with worker:install --force, bootstrap ordering diverges from the framework's tested path.
• PHP version drift — a base image or CI runner silently moves past 8.2 while framework code is only guaranteed on 8.2.
• Deprecation debt — deferred removals forcing an emergency minor upgrade, potentially colliding with a feature freeze.
• Boundary type coercion — inconsistent strict-types coverage producing subtle comparison/validation bugs at API edges.
• Ecosystem gaps — fewer maintained third-party packages than the Laravel ecosystem; a needed integration may become in-house code we own forever.
• Silent baseline masking — upstream static-analysis suppressions hiding defects we then inherit.

Ramp-up

• Any competent PHP developer is productive in CI4 within roughly one to three weeks; the MVC shape, routing, and migrations are familiar. The friction points are the differences: config-as-classes, the Services/factories pattern instead of a full DI container, Query Builder rather than Eloquent, and the framework's testing and coding-standard conventions.
• Two training items are non-optional and should be scheduled, not assumed: (1) the upgrade runbook, so upgrades are routine rather than heroic; (2) Worker Mode state discipline if that mode is adopted, because it is a correctness discipline, not a performance toggle.
• Plan for at least one engineer to hold designated ownership of the framework relationship — release tracking, upgrading-guide review, and the pin/bump decision. Without a named owner, the upgrade treadmill stops and the risk silently compounds.