Folio Laravel Package

Product Decisions This Supports

• Build vs. buy on routing scaffolding: Folio is a first-party Laravel package (MIT, no license cost, no vendor risk beyond the Laravel core team). The "buy" decision is essentially free; the real cost is the team convention shift from explicit route files to file-and-folder-based routing. Frame adoption as a convention decision, not a procurement one.
• Feature scoping for page-heavy surfaces: Decide per surface area rather than app-wide. Folio is strongest where the URL structure is obvious and page count grows steadily — marketing pages, documentation, blog/help-center, changelog, settings screens, simple CRUD admin pages. Mounting it at a subpath (/docs, /admin) lets you ship those areas without disturbing the existing routes/web.php graph.
• Roadmap sizing for content velocity: Because a new page is a Blade file plus a filename convention, PMs can forecast "time-to-new-page" in hours rather than sprints. That materially changes what you can promise a marketing or docs stakeholder for landing-page and campaign turnaround.
• Convention-driven dynamic pages: Filename tokens give model route binding for free, so a spec like "product detail page at /products/{product}" maps directly to a file path. This reduces the design-to-implementation translation layer and makes scope estimates more predictable for detail/index views.
• Cross-cutting requirements without bespoke plumbing: Middleware via attributes, terminable middleware, multiple mount paths, per-domain mounting, and mount selection (v1.2.0) mean auth gating, localization, and multi-tenant or multi-brand hosting can be expressed once at the mount level instead of per route.
• Observability and auditability of the URL surface: folio:list (with route names and URIs) is a governance artifact — useful for SEO inventories, sitemap generation, redirect planning, and pre-release QA of what actually exists. The ViewMatched event supports page-level analytics, A/B assignment, or instrumentation without touching controllers.
• Performance and deployment posture: route:cache compatibility and the current pipeline-through-container support mean this does not force a deviation from your standard Laravel deploy and caching playbook — a key reason it can clear an architecture review that a third-party router package likely would not.
• Risk-reduction decisions: The changelog shows active, current compatibility maintenance — Laravel 12/13, PHP 8.4/8.5, Symfony 8, plus fixes for genuinely nasty edge cases (route caching breaking, silently dropped routes with overlapping domains, slug collisions with index). Treat ongoing framework-version compatibility as low-risk, but treat edge-case correctness in your specific URL shapes as something to verify rather than assume.

When to Consider This Package

Consider it when:

• The surface area is page-oriented and URL-obvious — a docs site, marketing site, blog, help center, or an internal admin panel with many structurally similar pages.
• The team is already fluent in Laravel conventions and comfortable with convention-over-configuration. Folio's benefits evaporate if engineers routinely get lost because "the route isn't in a file."
• You expect steady page-count growth and want the marginal cost of a new page to be near zero.
• You want auth, localization, or tenant middleware applied uniformly at a mount rather than repeated across route groups.
• You need multiple independent surfaces in one app (e.g. /docs and /admin with different middleware, or per-domain marketing sites) with clean separation.
• You're standardizing on current Laravel and your deploy pipeline already runs route:cache.
• You want the URL inventory to be discoverable and auditable (folio:list) rather than reconstructed by grepping route files.

Look elsewhere when:

• The URL structure is not a mirror of the content hierarchy — deeply irregular routes, heavy use of route prefixes that don't map to folders, or URLs that are SEO-frozen while the underlying file organization must change. Renaming a folder is a URL change and therefore a redirect/SEO migration.
• The routing graph encodes business logic or policy — complex route groups, per-route rate limits, signed URLs, or API endpoints. Keep APIs and non-page routes in explicit route files; Folio is a page router, not a general routing replacement.
• The team is large and distributed with weak convention discipline, or the app has many contributors touching the same directory tree. Explicit route files provide a reviewable, single-file diff that file-based routing does not.
• You need strong IDE/static discoverability as a hard requirement — jump-to-route-definition tooling and refactor safety are better served by explicit routes.
• The package is unproven at your scale: 608 stars and no listed dependents mean the reference base is thin. That's mitigated by first-party ownership but not eliminated; validate with a scoped pilot rather than a repo-wide migration.
• The pages are so few that the convention adds cognitive overhead without saving keystrokes.

How to Pitch It (Stakeholders)

To executives: Folio is a free, officially maintained Laravel package that lets us define pages by creating files in a folder rather than writing routing code. The business case is throughput and consistency: new marketing, docs, and admin pages ship faster, and page-level requirements like login gating or localization get applied once instead of page by page. It's MIT-licensed, maintained against the current Laravel and PHP releases, and works with our existing deploy and cache pipeline, so there's no new vendor, no license line item, and no infrastructure change. We recommend a scoped pilot on one surface — for example documentation or the internal admin — with success measured by time-to-new-page and a clean route/SEO audit, before deciding on broader use.

To engineering: Folio replaces boilerplate route registration with convention: Blade pages in a mounted directory become routes, filename tokens map to model route binding, and middleware attaches via attributes. It supports multiple mount paths, domains, mount selection, named routes, route:cache, and a folio:list command for auditing the resulting URL surface — so it fits our existing build and deploy model rather than fighting it. We'll keep explicit route files for APIs and anything with irregular URL requirements, and mount Folio only where the URL mirrors the content hierarchy. Known sharp edges to respect: URL structure becomes coupled to directory structure, so folder renames are SEO events; some historical edge cases (route caching, overlapping mounts across domains, index slug collisions) have been fixed but warrant a compatibility check against our specific URL shapes. Ask: a two-week pilot on one mount, a convention doc for naming and redirects, and a folio:list diff in CI so the URL surface is reviewed like any other contract.