Statamic Products Laravel Package

Product Decisions This Supports

• Build vs. buy for scoped file access. The package already provides the two pieces that are expensive to get right: a picker UI and a server-side boundary that refuses anything outside an allowed folder (including ../ traversal). That is a buy signal for any feature needing "show users only their folder" file selection.
• Build vs. buy for point-in-time credit balances. v1.12.0 adds added_at to every credit line plus Access::creditLinesAt($at) / AccessView::creditLines(includeEnded: …, at: $at), which answer "how many lines existed at the moment of this grant." That is the primitive behind grant replay, dispute handling, and back-dated reconciliation. Doing this ourselves means event-sourcing the ledger; the package now gives us the query shape for free.
• Feature feasibility for per-container / per-tenant file scoping. AccessContainers::allow(['container' => 'folder']) is the product-level primitive behind customer portals, per-client document folders, and role-limited media libraries. v1.11.1 confirmed the intent: the picker starts in the scoped folder for convenience, while enforcement lives on the server — a clean separation we can rely on when designing permission UX.
• Correctness of money-adjacent UX. A customer who bought a grant should not later be told a credit line is "missing" because it was added to their access after the fact. The at filter is exactly the guard against retroactively re-issuing or retroactively denying credits — a support-ticket and trust problem, not just a data problem.
• Roadmap sequencing. The 1.10.0 → 1.11.1 → 1.12.0 arc shows both areas (scoped containers, credit ledger) under active hardening. The ledger was previously "current state only"; it now has a temporal axis. If point-in-time entitlement reporting is on the near-term roadmap, this is stable enough to prototype against now.
• Risk posture for upgrades. v1.11.1 was a pure patch; v1.12.0 is additive with unchanged defaults (creditLines() without at behaves as before). No deprecations, no breakage. Taking it is low-risk, but the new added_at semantics are set-once and silent on conflict, so budget a short verification pass rather than a blind bump.
• Data-migration planning input. Lines from the takeover (which carry their own number) and lines saved before 1.12.0 have no added_at, meaning "has always been there." If we import historical balances, every earlier at query will include them. That is usually the right answer for a takeover, but it must be an explicit decision, not a discovery in a customer dispute.

When to Consider This Package

Adopt when:

• You are on Laravel/PHP and need a file picker whose visible scope is narrower than the underlying storage.
• Your access model is folder-as-boundary (tenant folder, client folder, project folder) rather than per-file ACLs.
• You want the security boundary enforced server-side and are content to treat the picker's starting location as a UX convenience only.
• You need to answer "what did this access hold at time T" for grants, purchases, or disputes, and current-state-only reads are insufficient.
• You are already using the package's containers and want to close out the nested-folder dead-end.

Look elsewhere when:

• You need per-file or per-record permissions, sharing links, or an approval workflow layered on top.
• You need a full DAM: versioning, renditions/thumbnails, metadata search, audit trails of who downloaded what.
• You need a double-entry ledger, corrections/back-dating of individual credit lines, or accounting-grade immutability and export. added_at is set once and restored if a form or import drops or changes it — good for integrity, but there is no documented correction path, so a wrong timestamp is effectively permanent.
• You need multi-cloud storage abstraction or non-Laravel services consuming the same access rules.
• You require a formal support/SLA commitment — this is a fast-moving 1.x line (1.10.0 → 1.11.1 → 1.12.0 in short order), so budget for upgrade verification each cycle.

Regardless of fit, pin the invariants we depend on in our own suite after each upgrade rather than trusting release prose:

• A scoped container still rejects paths outside its folder, including ../ (unchanged since 1.10.0, still worth owning).
• A credit line added after a grant time is not returned by creditLinesAt($grantTime) and is not reported as "missing" for the earlier purchase.
• A line with no added_at (pre-1.12.0 or takeover) is returned for every at query.
• An import or form that omits or alters added_at on an existing line yields the stored value, not the submitted one.
• Whether ended lines are included at a given at. The notes define the filter on added_at and state ended_at is unchanged, so the interaction is not spelled out — resolve it with a test before we build reporting on top of it.

How to Pitch It (Stakeholders)

To executives: We can ship scoped file access — customers and staff seeing only their own folders — without building the picker and the access enforcement ourselves. The security check sits on the server and rejects any attempt to reach outside the permitted folder, which is the part we would otherwise have to design, build, and defend in review. The same package now also lets us answer "what did this customer have at the moment of the grant," so disputes, replays, and back-dated reconciliation stop being a custom data project. The latest release adds that capability only: no interface changes, no migration required, existing behavior unchanged unless we opt in.

To engineering: v1.12.0 is a minor, additive release. Every credit line now carries added_at (ISO 8601), set by the model at numbering time. Semantics to know: lines from the takeover and lines saved before 1.12.0 have no added_at, interpreted as "has always existed"; once set it is fixed, so a form or import that drops or changes it silently gets the stored value back. New read APIs are Access::creditLinesAt($at) and AccessView::creditLines(includeEnded: …, at: $at); creditLines() without at behaves as before, and ended_at is untouched. No breaking changes, no deprecations, no config changes expected. Action: bump the dependency, add the four regression tests listed above (out-of-folder rejection, post-grant line exclusion, null-added_at inclusion, set-once round-trip), and confirm the at-versus-ended_at interaction before we build any reporting on it. Also decide explicitly whether historical balances are imported with or without added_at — that choice changes what every past-dated query returns.