Basepath Laravel Package

Product Decisions This Supports

• Deployment topology. Whether we can ship the same artifact to a dedicated vhost, a subdirectory (/app), or a path-prefixed reverse proxy without code changes or per-environment config. This package makes "base path" a runtime-detected value instead of a hardcoded constant, which directly enables "build once, deploy anywhere."
• Build vs. buy for URL correctness. Correct link/redirect generation behind proxies is a recurring source of P1-ish bugs ("redirects to /login instead of /app/login"). The decision is whether to spend engineering time on a bespoke detector or take a ~small MIT dependency. At this scope, buying (or vendoring) is almost always the right call.
• Roadmap scoping. Adopting it now unblocks path-prefix deployments and proxy-terminated TLS scenarios without pulling in a heavier framework component. It also caps the roadmap item at "configure the detector + add tests" rather than "rework routing."
• Use cases it serves: Slim 4 apps hosted under a subpath, apps behind an ingress/ALB that rewrites the path prefix, staging environments mounted under /staging/<service>, and multi-tenant-style path partitioning where each tenant is served from a distinct prefix.
• Risk decision — dependency posture. Low stars and zero dependents is a real signal. The PM decision is not "adopt or not" but "adopt with which guardrails": pin the version, vendor the source if the security posture requires it, and cover it with our own integration test so an upstream stall doesn't become our outage.

When to Consider This Package

Adopt when all of these hold:

• The service is Slim 4 (or a PSR-7 app with a comparable setBasePath hook). This is the package's core assumption; fighting it elsewhere is wasted effort.
• The app must run under a path prefix in at least one environment, and that prefix is not known at build time.
• The prefix is signalled through standard server variables or proxy headers (SCRIPT_NAME, PHP_SELF, X-Forwarded-Prefix-style), not through a proprietary mechanism.
• You want correct urlFor()/redirect output and are willing to add your own tests around the detection logic.

Look elsewhere when:

• The stack is Laravel or Symfony — both already resolve base URL/trusted proxies in the framework (Request::root(), UrlGenerator, Request::getBasePath()), and adding this would create two competing sources of truth.
• You need full trusted-proxy handling (which headers to trust, from which CIDRs, X-Forwarded-For chains). That is a security-sensitive concern; use a dedicated middleware or symfony/http-foundation-style trust configuration. This package detects a path, it does not establish trust.
• You need asset/CDN URL rewriting or canonical-host enforcement — adjacent problems, different tools.
• Your organization requires actively maintained, multi-maintainer dependencies with ecosystem validation. With ~48 stars and zero dependents, this fails most procurement/OSS-review checklists; plan to vendor it (MIT permits this) and treat it as internal code.
• You are on a non-Slim micro-framework and the detection logic would need material modification — at that point the build-vs-buy math flips; a ~100-line internal helper is cheaper than a fork.

How to Pitch It (Stakeholders)

To executives: This is a small, free (MIT), single-purpose utility that removes a class of deployment bugs — broken links and misdirected redirects when our app is served from a subdirectory or behind a load balancer. It costs nothing, touches one concern, and lets the same build run in more environments, which reduces release friction and environment-specific config drift. It is easily replaced: if the upstream project stalls, we vendor the source and own it at negligible cost.

To engineering: It detects the application base path from server variables and proxy headers and hands it to Slim's base path setting, so urlFor() and redirects generate correct absolute paths. Scope it as: add the dependency (pinned), wire the detector in the app bootstrap, and write our own integration tests for the three cases we actually run — root, subpath, proxy-prefixed. Do not treat it as proxy-trust configuration; pair it with an explicit trusted-proxy policy. Note the maintenance profile (small maintainer base, no downstream dependents) and prefer vendoring if our supply-chain policy requires it. Estimated effort: under a day, mostly tests.