Laravel Report Url Laravel Package

Product Decisions This Supports

• Delivering large generated artifacts to users. The core use case is anything a product generates that is too large or too sensitive to email: scheduled report exports, CSV/XLSX dumps, invoices, PDF statements, data-export requests. ReportUrl::store() / storeFile() keeps the file on a private disk and returns a time-limited signed URL instead of an attachment.
• Build vs. buy on "secure download links." This is a thin, opinionated layer over Laravel's signed URLs plus filesystem storage. The build cost of the happy path is low, but the surrounding 20% — expiry semantics (410 responses), owner checks, download telemetry, pruning of expired links and their files — is exactly the part teams forget to ship. Buying (adopting) it is justified by that tail, not the URL generation.
• Feature work it unblocks or de-risks. Self-serve "email me my report" flows, shareable-but-revocable links for customer-facing documents, scheduled-report delivery pipelines, and any workflow currently blocked by SMTP attachment size limits.
• Compliance and retention roadmap. Configurable ttl (7-day default, per-call override) plus report-url:prune with --dry-run gives a concrete data-retention story: files do not live forever, links die on schedule, and the cleanup job is inspectable before it runs. That is a policy artifact you can show in a security review, not just a cron job.
• Observability and abuse questions. ReportUrlDownloaded plus a download counter and last_downloaded_at mean you can answer "did the customer actually get the report?" and "was this link hammered?" without instrumenting anything yourself — a real support-cost reducer.
• Scope/roadmap sequencing of owner-restricted links. restrict_to_owner is a config flag, not a permission system. Deciding whether you need per-recipient sharing, revocation UI, or multi-tenant access control is a roadmap decision this release forces you to make explicitly rather than by accident.
• Vendor/integration surface. The laravel-saved-filter 1.9+ binding (HostsReportFiles) is a ready-made answer to "scheduled reports too big to attach" for teams already on that stack — a same-day win, and a signal the package is being maintained against real downstream needs.

When to Consider This Package

Consider it when all of the following roughly hold:

• The product is Laravel/PHP and generated files already live (or can live) on a private disk — local, S3, or equivalent Laravel filesystem driver.
• Files are per-user or per-request artifacts, not public marketing assets. The signed-URL model fits ephemeral, individually-issued downloads; it is a poor fit for permanent CDN-delivered assets.
• You need bounded access windows — either for compliance/retention reasons or because the artifact contains customer data you don't want lingering at a guessable URL.
• You want download visibility (who/when/how many) without building an audit table.
• You are already sending, or plan to send, scheduled reports by email and are hitting attachment limits — in which case the laravel-saved-filter integration is close to a drop-in.
• Your team would otherwise reimplement expiry + pruning + signed routes, and has better things to do.

Look elsewhere, or build deliberately, when:

• You need a full sharing/permission model. restrict_to_owner is binary. Per-recipient links, team/org-level access, revocation dashboards, or delegated sharing are out of scope — do not adopt this and then discover you need an ACL layer underneath it.
• Files are not Laravel-disk artifacts, e.g. streamed from another service, generated on the fly, or stored in a system where you cannot safely delegate deletion to report-url:prune.
• You need content inspection before delivery — malware scanning, DLP, redaction. Nothing here does that; add it upstream or pick a document-pipeline product.
• The requirement is truly just "give me a temporary URL." If Storage::temporaryUrl() covers it and you have no retention, telemetry, or cleanup needs, the package is extra surface area for little gain.
• You cannot run a scheduled prune job, or run it on many servers without care — the release notes specify daily scheduling on one server, so onOneServer()/single-node assumptions need to match your infrastructure.
• Production stability is a hard gate and you need a track record. This is a 1.0.0 first release. Semver says the API is now declared stable, but there is no field history yet; pin the version, and treat the config keys and event payload as the contract you are depending on.

Two adoption cautions worth stating plainly to engineering: the 410-on-expiry behaviour and the owner-check are the security-relevant bits, so they need test coverage in your app, not just trust in the package. And the coupling to laravel-saved-filter is a version-bounded integration (1.9+) — verify it against whatever you actually run before promising the "reports by link" feature to anyone.

How to Pitch It (Stakeholders)

For executives — one paragraph. We can now deliver large or sensitive generated files — scheduled reports, exports, statements — as secure, expiring download links instead of email attachments. That removes a hard blocker on report delivery, gives us a defensible retention story (links and files expire on a configurable schedule and are cleaned up automatically), and gives us an audit trail of who downloaded what and when. It is a small, single-purpose library rather than a platform commitment, so the cost of trying it is low; the main caveat is that it is a first release, so we pin the version and keep our usage narrow.

For engineering — the practical summary. It wraps Laravel signed URLs over a private disk: store() / storeFile() return a URL plus expires_at, with a 7-day default TTL and per-call override. Downloads go through a named route (report-url.download) that is signed, has configurable middleware, returns 410 after expiry, optionally enforces restrict_to_owner, and fires ReportUrlDownloaded while incrementing a counter and last_downloaded_at. report-url:prune --dry-run deletes expired rows and their files; schedule it daily on a single server. If you already use laravel-saved-filter 1.9+, HostsReportFiles is bound for you and oversized scheduled reports arrive as links.

For the business, framed as risk. The failure mode we are avoiding is customer data sitting at durable, guessable URLs indefinitely. Expiry-by-default plus scheduled pruning plus a dry-run mode means retention is a configuration decision we can review, not an accident. The residual risks are ordinary and manageable: it is a 1.0.0 with no long track record (pin it, keep the integration thin), owner restriction is coarse so we should not market it as sharing/permissioning, and the prune job needs a single-runner guarantee in our infrastructure. None of these are blockers for the report-delivery use case; all of them should be written down before we expand scope.