Common Utils Laravel Package

Product Decisions This Supports

• Framework migration / dual-target roadmaps. If we have any credible path where a service built on Webman needs to run on Laravel (or vice versa) — acquisition, hosting change, team consolidation, or a customer who mandates Laravel — this package directly reduces the "rewrite the HTTP/config/log layer" line item from a multi-sprint effort to an adapter swap. It converts a binary decision (rewrite vs. stay) into a reversible one.
• Build vs. buy on internal abstraction layers. The package is essentially a reference architecture for the abstraction we'd otherwise build ourselves: Request/Response/Session/Route/Config/Runtime, plus BaseMiddleware and a Json encoder that handles NaN/INF/non-UTF-8. Even if we don't adopt it, it de-risks our own scoping estimate and gives us a checklist of the edge cases (path resolution in CLI, env read-only semantics, test isolation) that internal designs routinely miss.
• Library / SDK strategy. If any part of our product ships as a plugin or composer package consumed by other teams, targeting one framework API surface means we cut the support matrix roughly in half. This is the single strongest product justification: write the middleware once, ship to Webman and Laravel customers.
• Test-cost and CI decisions. Testing\Factory::registerTestRuntime() with TestRequest/TestRoute/TestConfig fakes means business logic can be unit-tested without booting a framework. That is a measurable reduction in test runtime and flakiness, and it's an argument for pushing business logic behind the abstraction rather than into controllers.
• Operational consistency. Unified base_path() / runtime_path() / logger() / config() helpers eliminate a class of "works in HTTP, breaks in CLI/cron" bugs — relevant if we run queue workers, scheduled jobs, or artisan-style scripts against the same codebase.
• Explicit non-decision: this does not justify standardizing on Webman. The abstraction is about portability, not about picking a winner.

When to Consider This Package

Consider it when:

• We have a concrete, dated requirement to run the same code on more than one PHP runtime — not a hypothetical.
• Our product's value is in business logic, and the framework layer is genuinely commodity glue we'd rather not own.
• We are building an internal shared package consumed by several services, at least one of which is not on the incumbent framework.
• Our test suite is slow/awkward because tests reach into framework internals, and we want a fake-based seam.
• We're comfortable treating the source as vendored/forked code we may need to patch.

Look elsewhere (or treat as read-only reference) when:

• The maturity signals are disqualifying for a production dependency. This is the honest read: 0 stars, 0 dependents, first/only release dated 2025-11-24, and the description is literally "[READ ONLY] Subtree split from webman-tech/components-monorepo." That means no issue tracker on this repo, no external user base, no community validation, and no signal that the split is independently maintained. Adopting it as a dependency means we are the only consumer — we inherit all maintenance.
• We can only tolerate one framework for the foreseeable future. The abstraction is pure overhead if the second runtime never materializes; every Request::getCurrent() indirection is a small ongoing tax on readability and debugging.
• We need API stability guarantees, security response, or a support contract. Nothing here suggests those exist.
• We need deep or framework-specific capabilities — streaming, file uploads, queue integration, ORM — that the abstraction likely doesn't cover, forcing escape hatches that defeat the purpose.
• The team has no appetite for owning a fork. If the answer to "who patches this when upstream is abandoned?" is nobody, don't adopt.

Net recommendation: adopt the pattern, not the dependency. Vendor or fork it under our namespace, pin it, and treat it as internal code — or reimplement the small surface we actually need. Track the upstream monorepo (webman-tech/components-monorepo) rather than this split, since that's where activity would appear.

How to Pitch It (Stakeholders)

To executives — one paragraph: This is a portability layer that lets the same PHP application code run on two different frameworks without a rewrite. The strategic value is optionality: it keeps a future framework migration, acquisition integration, or multi-customer deployment from becoming a multi-sprint project, and it lets us ship a single plugin to a wider customer base instead of maintaining parallel versions. The tradeoff is that the specific package is unproven — zero external users, a read-only snapshot from a monorepo, no support path. So the recommendation is not "buy this product." It's "adopt this architecture, at a cost of roughly one to two weeks of engineering, on the one or two components where portability is a real near-term requirement." That buys the option cheaply and commits us to nothing.

To engineering — the pitch:

• One seam — Runtime plus Request/Response/Config/Route — replaces direct framework calls, so business logic stops importing \Webman\Http\Request or request().
• Middleware written once against BaseMiddleware runs on both Webman and Laravel, and mutations via withHeaders()/withCustomData() write through to the real request, so there's no shadow-object confusion.
• Json::encode() is a strict improvement over json_encode() for anything user-facing — it survives NaN/INF and non-UTF-8 instead of silently returning false.
• CLI and cron get first-class support: RuntimeCustomRegister::register([...]) makes base_path()/runtime_path()/logger() work outside a request context, which is exactly where framework helper functions fall over.
• Test fakes remove the framework from the unit-test loop; the discipline required is clear() in beforeEach to avoid cross-test pollution.
• The ask: we fork it into vendor/ under our namespace, pin the version, own a thin test suite around the surface we actually use, and don't pretend upstream owes us anything. If a maintained alternative appears, swapping back is cheap because the interface is the contract.