Hello Api Laravel Package

Technical Evaluation

Architecture fit. Apiato (published here under the porto-sap/hello-api name, pointing at apiato/apiato) is not a drop-in library — it is an opinionated Laravel application skeleton built on the Porto SAP architecture. Code is organized into Containers (one per domain: Actions, Tasks, Repositories, UI/API, Requests, Transformers, Tests) plus a Ship layer for shared infrastructure. It assumes greenfield service design and enforces boundaries that a typical Laravel monolith does not have. Fit is strong if we are building a new API-centric backend with multiple bounded contexts; it is poor if the intent is to bolt structured layering onto an existing app.

v13.2.0 does not change this evaluation: it is a non-breaking minor release containing a single feature PR ("modern responsive UI") from a first-time contributor. The signal worth registering is scope, not architecture — a UI-oriented change inside an API-first skeleton. We need to confirm whether this touches the docs/site or ships assets (views, CSS, frontend build tooling) into the skeleton itself.

Integration feasibility. Greenfield: high. The composer create-project flow, Docker setup, and pre-wired auth (OAuth2), transformers, and exception handling compress 4–8 weeks of platform scaffolding into days. Brownfield: low. Apiato replaces app/, bootstraps containers through its own service provider and kernel, and owns the exception handler, route loading, and test harness. Third-party packages that assume App\Models or standard PSR-4 autoloading will need bridging.

v13.2.0 is non-breaking on its face, but if the UI work introduces npm/Vite assets into the skeleton, the evaluation build must validate build-pipeline and Docker image impact before pinning.

Technical risk. The dominant risk is governance, not code. Two diligence red flags must be resolved before adoption:

• Name/repo mismatch and zero dependents against 3.1k stars. Apiato is consumed via create-project, not as a Composer dependency, which explains dependents=0 — but the published artifact name (porto-sap/hello-api) does not match the repo, so we must confirm what we are actually vendoring and pin a specific commit/tag. v13.1.0 → v13.2.0 gives us a usable diff to inspect, which partially de-risks this.
• Maintainer concentration. Effectively a single-maintainer project with community-only support. Release recency (2025-11-17) is positive but does not imply an LTS commitment. v13.2.0 adds one new contributor — an early positive signal on bus factor, but one PR is not evidence of sustained contributor depth and must not be treated as mitigation.

Secondary risks: tight coupling to Laravel major versions, reliance on Laravel Passport (OAuth2) and Fractal transformers — both areas where the wider ecosystem has moved on (Sanctum, API Resources). Expect to own these decisions rather than inherit them. New in this release: scope creep into presentation-layer concerns in a codebase whose value proposition is backend architecture discipline.

Key questions for the maintainer/pilot.

1. Which Laravel and PHP versions are supported, and what is the upgrade cadence policy per Laravel major?
2. Is apiato/core usable as a standalone dependency, or is the skeleton mandatory?
3. What is the security disclosure process and historical CVE turnaround?
4. Octane / Swoole compatibility and any stateful assumptions in Containers?
5. Test harness expectations (Codeception vs. PHPUnit) and typical suite runtime at scale?
6. Is there commercial support or a funded roadmap, and what is the bus factor mitigation?
7. Can we adopt the Action/Task/Repository pattern without the full skeleton — i.e., extract the architecture rather than the framework?
8. (New, v13.2.0) Does the "modern responsive UI" work ship into the skeleton (views/assets/frontend build), or is it documentation-site only? If it ships, what does it add to dependency surface, image size, and CI time — and does it presage a broader scope shift away from API-first?

Integration Approach

Stack fit. Laravel + PHP 8.2+, MySQL/Postgres, Redis, Docker-based local environment, OAuth2 auth. This aligns with our existing PHP footprint and CI tooling. The Container model maps cleanly to team ownership boundaries — one squad, one Container — which is the main strategic reason to consider it. If v13.2.0 brings frontend build tooling into the skeleton, add Node/npm to the CI matrix expectations; that is a small but real expansion of the stack surface.

Migration path. Do not attempt a lift-and-shift of an existing service. Two viable paths:

• Path A (recommended for a new product line): greenfield bounded service — e.g., a partner-facing or internal read/write API — built on the skeleton, with the rest of the platform untouched. Isolates blast radius and gives a clean reference implementation.
• Path B (recommended if the goal is architectural uplift): pattern extraction. Reimplement Action/Task/Repository/Transformer conventions as a thin internal Composer package on top of stock Laravel. Lower ceiling, far lower lock-in.

Both paths survive v13.2.0 unchanged; it is an additive minor release.

Compatibility. Pin Laravel and PHP versions explicitly in the ADR, and pin Apiato to v13.2.0 or later rather than a branch, now that there is a clean tagged delta. Verify no conflicts with our auth provider, observability SDKs, and static analysis pipeline (PHPStan/Larastan need Container-aware config). Confirm migration and seeder paths, since Apiato relocates them per Container. Review the PR #786 diff for new transitive dependencies before locking the pin.

Sequencing.

1. Diligence spike (1 week): resolve artifact identity, pin version (≥ v13.2.0), confirm support matrix, review PR #786 diff for shipped UI assets and new dependencies.
2. Evaluation build (2–3 weeks): one Container, two endpoints, full test + CI + deploy path.
3. Pattern/ADRs (1 week): decide Path A vs. B; document Container boundaries and naming conventions; record position on UI/presentation assets in the skeleton.
4. Team enablement (2 weeks, overlapping): pair-programming, reference Container as template.
5. First production service (1 quarter): single bounded context, feature-flagged, with a documented exit plan.

Operational Impact

Maintenance. Assume we fork and own. Upgrades will be re-diffing the skeleton against our fork rather than a composer update, so budget ~5–10% of one engineer per quarter for upstream tracking. This is the single largest hidden cost. v13.2.0 is a favourable sample of what that tracking looks like — a one-line changelog with an inspectable single-PR diff — but a UI-oriented diff is also the kind we may choose not to merge into an API-only fork, which is exactly the divergence cost to plan for.

Support. Community channels only — no SLA, no guaranteed triage. Mitigate with an internal champion (ideally two, to address bus factor) and a documented escalation path to Path B if upstream stalls. The first-time contributor in v13.2.0 is encouraging but is not a support commitment and should not be cited as such to stakeholders.

Scaling. Containers are stateless by design and scale horizontally without ceremony. The real scaling constraint is developer throughput: a single endpoint touches roughly 8–12 files (Request, Controller, Action, Task, Repository, Transformer, Test, routes). This is deliberate and pays off at 30+ endpoints across 5+ teams, but it slows the first 10 endpoints measurably. Set expectations with stakeholders accordingly.

Failure modes to monitor.

• Upgrade drift — falling two Laravel majors behind makes the fork unmergeable.
• Boundary erosion — cross-Container direct calls and shared Repositories quietly recreate a monolith.
• Over-abstraction — Tasks wrapping single-line queries; enforce a "no Task without reuse or orchestration" rule.
• Dependency decay — Passport and Fractal are inherited choices; plan replacements.
• Test suite slowdown — Container tests trend toward integration; enforce unit-level budgets in CI.
• Scope drift (new, watches v13.2.0) — presentation-layer or non-API concerns entering the skeleton; hold the line that our fork stays API-only unless a business case is approved.

Ramp-up. 2–4 weeks to fluency for a mid/senior Laravel engineer; documentation is substantial but has known drift versus the current skeleton, so treat the reference Container in-repo as the source of truth. Junior engineers take longer — the pattern rewards discipline over speed. If UI assets are now part of the skeleton, add a short note on frontend conventions to the onboarding path.

TPM recommendation. Unchanged. v13.2.0 is a low-risk, non-breaking minor release that does not alter the architecture assessment, the integration paths, or the score (33.8) and opportunity (3.84). It supplies two small positives — a clean tagged delta and a first outside contributor — and one new diligence item: confirm the UI work does not pull presentation-layer scope and frontend build tooling into an API-first skeleton. Pursue only as a greenfield, bounded pilot with an explicit Path B fallback. The value proposition is the architecture, not the dependency — negotiate accordingly.