Php Xdg Base Dir Laravel Package

Getting Started

Start by installing via Composer: composer require dnoegel/php-xdg-base-dir. After installation, the core usage is straightforward — instantiate the Xdg class and call its methods to resolve standard directories. For example:

use dnoegel\Xdg\Xdg;

$xdg = new Xdg();
$configDir = $xdg->getConfigHome(); // e.g., ~/.config or $XDG_CONFIG_HOME
$dataDir   = $xdg->getDataHome();   // e.g., ~/.local/share or $XDG_DATA_HOME
$cacheDir  = $xdg->getCacheHome();  // e.g., ~/.cache or $XDG_CACHE_HOME

The first practical use case is ensuring CLI tools and scripts store configuration and cache files in standard locations — avoiding cluttering the user’s home directory or hardcoding paths like /tmp/myapp/.

Implementation Patterns

• Centralized Directory Resolution: Create a singleton or service provider (e.g., in Laravel) that exposes XDG paths to the app. Example Laravel service provider binding:

  $this->app->singleton('xdg', fn () => new Xdg());
  

  Then inject or resolve Xdg wherever you need to write/read config or cache.

• Config File Discovery: Use getConfigDirs() to iterate over all potential config directories (including /etc/xdg) for system-level and user-level overrides. Useful for apps that support layered configs (e.g., default config in /etc/xdg/myapp, user override in ~/.config/myapp).

• Cache and Temp Files: Use getCacheHome() for cache storage (e.g., compiled templates, downloaded assets), and getRuntimeDir() (if available) for ephemeral runtime files like lock files or sockets — though note this method may require custom implementation since it's not in the core API.

• Path Prefixing: Use makePath() or getHome() + custom subpaths (e.g., $xdg->getHome() . '/myapp/') to create app-specific subdirectories within XDG roots.

Gotchas and Tips

• No XDG_RUNTIME_DIR by default: While the spec includes XDG_RUNTIME_DIR, this package only implements config/data/cache home directories out-of-the-box. If you need runtime paths, implement the fallback manually or extend Xdg — check $HOME first, then fallback to /tmp.

• No Windows Support: This package is for Unix-like environments only. On Windows, it returns false or falls back to $_SERVER['HOME'] or $_SERVER['USERPROFILE'], but this behavior isn’t guaranteed. For cross-platform apps, wrap calls in platform checks (PHP_OS_FAMILY === 'Unix').

• Environment Variable Misconceptions: The package respects XDG_* env vars, but does not export them. Don’t assume the process environment itself is modified — only the directory resolution is.

• Silent Fallbacks Can Mask Misconfigurations: If HOME is unset (e.g., in some containerized environments), the fallback to /tmp or /var/tmp may not be obvious. Add logging or validation in dev/prod to verify expected paths exist.

• Immutable and Stateless: Xdg has no state and never writes to disk — it only resolves paths. Treat it purely as a reader, not a file manager.

• No Updates Since 2019: Though minimal and stable, verify compatibility with modern PHP versions (tested up to 8.0 in CI docs). Not risky for this simple library, but good to note for security scans.