Laravel Xdg Laravel Package

Product Decisions This Supports

• Build vs. buy for XDG-compliant path resolution. Any time a Laravel app needs to decide where to write user-scoped artifacts (config, cache, data, state, runtime), this package replaces hand-rolled env() checks and hardcoded ~/.config/... paths with a maintained implementation of the freedesktop XDG Base Directory spec.
• Packaging & distribution strategy. Relevant if the product is a CLI, local daemon, or desktop-adjacent Laravel app that users install on their own machines rather than something we operate as a hosted service. It directly affects where our files land and how "native" we look on Linux desktops.
• Roadmap / framework currency. v1.5.0 adds Laravel 12 support (PR #9). That is a maintenance signal, not a feature signal: it tells us the dependency can follow our framework upgrade cadence, so it doesn't become a blocker when we plan the Laravel 12 migration.
• Use cases it unlocks. Artisan-based developer tooling, self-hosted agents, desktop wrappers around a Laravel core, and any product with per-user profiles that must respect XDG_CONFIG_HOME, XDG_CACHE_HOME, XDG_DATA_HOME, XDG_STATE_HOME and their spec-defined fallbacks.
• Decisions it does not inform. For a conventional server-rendered app in a container, user-home directory conventions are irrelevant — the app writes to its own storage tree. Do not let this package expand the scope of a hosted product.

When to Consider This Package

Adopt when:

• The product writes files into the end user's home directory and must behave correctly on Linux/WSL desktops.
• You need to honor XDG environment variables plus the spec's fallback defaults, and you don't want to own that logic (and its edge cases) yourselves.
• You already have users or admins who will file bugs when config lands in the "wrong" place — XDG compliance is a visible quality signal.
• You want a small, thin dependency with low lock-in: the surface area is narrow enough that replacing it later is cheap.

Look elsewhere when:

• The app is deployed as a hosted service or container image — use Laravel's own storage_path()/config_path() conventions and skip this entirely.
• You need first-class Windows support. XDG is a freedesktop convention; Windows expects %APPDATA%/%LOCALAPPDATA%. Verify the package's behavior there before committing, and if cross-platform parity is a hard requirement, plan for an abstraction layer of your own on top.
• You need general filesystem abstraction (cloud disks, S3, Flysystem semantics). This is a path-resolution concern, not a storage driver.
• Bus-factor check: small package, effectively single-maintainer. v1.5.0 confirms it is currently maintained, but for a load-bearing code path, confirm you're comfortable pinning a version and being able to fork or vendor it.

Upgrade risk for this release: v1.5.0 is additive/compatibility only — Laravel 12 support, no API changes, no deprecations, no breaking changes. v1.4.0 → v1.5.0 is a low-risk bump; treat it as maintenance hygiene rather than a planned work item.

How to Pitch It (Stakeholders)

For executives: This is a small, low-risk dependency that makes our product behave like a well-behaved native Linux application — config, cache, and data files go exactly where users and system administrators expect them to. That reduces a whole class of support complaints about stray or misplaced files, and it costs us almost nothing to adopt. The v1.5.0 release confirms the package is actively maintained and already supports Laravel 12, so it won't hold up our framework upgrade.

For engineering: It's a thin wrapper around XDG Base Directory resolution — it replaces bespoke environment-variable and path-joining code with a maintained, spec-correct implementation, with negligible runtime overhead and a narrow API surface, so lock-in is minimal. v1.5.0 only adds Laravel 12 support; there are no breaking changes or deprecations, so the bump from v1.4.0 is safe to take whenever we next touch dependencies. Recommendation: adopt only if we are genuinely writing user-scoped files from a locally-installed app; otherwise leave it out of the dependency tree.