PHPackages                             xdg/base-directory - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. xdg/base-directory

ActiveLibrary[Utility & Helpers](/categories/utility)

xdg/base-directory
==================

Implementation of the XDG Base Directory Specification

1.2(3y ago)04582MITPHPPHP >=8.1

Since Oct 3Pushed 2y ago1 watchersCompare

[ Source](https://github.com/php-xdg/base-directory)[ Packagist](https://packagist.org/packages/xdg/base-directory)[ RSS](/packages/xdg-base-directory/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (2)Versions (7)Used By (2)

xdg/base-directory
==================

[](#xdgbase-directory)

[![codecov](https://camo.githubusercontent.com/28cf9ced22974b55b9442d774fc7d7b455c2301d402bd99d49c9fb026adc918a/68747470733a2f2f636f6465636f762e696f2f67682f7068702d7864672f626173652d6469726563746f72792f6272616e63682f6d61696e2f67726170682f62616467652e7376673f746f6b656e3d394a3531543441365338)](https://codecov.io/gh/php-xdg/base-directory)

PHP implementation of the [XDG Base Directory Specification](https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html), with sensible default fallbacks for non-linux platforms.

Installation
------------

[](#installation)

```
composer require xdg/base-directory
```

Usage
-----

[](#usage)

```
use Xdg\BaseDirectory\XdgBaseDirectory;

// we start by instantiating a platform:
$platform = XdgBaseDirectory::fromEnvironment();
// get the XDG_CONFIG_HOME directory
$configHome = $platform->getConfigHome();
// find the most user-specific existing configuration file:
$configPath = $platform->findConfigPath('my-app/config.json', \file_exists(...));
```

See the [PlatformInterface](src/PlatformInterface.php) for all available platform methods.

Fallback values for Windows and macOS platforms
-----------------------------------------------

[](#fallback-values-for-windows-and-macos-platforms)

While on most Unix platforms, the XDG environment variables are usually defined, this is typically not the case on Windows and macOS.

This library choses to deviate from the spec and provide sensible defaults on those platforms.

### Windows

[](#windows)

On windows, when an XDG environment variable is not set, we first try to find a matching [Known Folder](https://learn.microsoft.com/en-us/windows/win32/shell/known-folders):

XDG envKnown Folder(s)HOMEProfileXDG\_CONFIG\_HOMELocalAppDataXDG\_DATA\_HOMELocalAppDataXDG\_STATE\_HOMELocalAppDataXDG\_CACHE\_HOMELocalAppData/cacheXDG\_RUNTIME\_DIRLocalAppDataXDG\_CONFIG\_DIRSProgramData, RoamingAppDataXDG\_DATA\_DIRSRoamingAppData, ProgramDataIf the known folder is not defined, we then try to fall back to a windows-specific environment variable, then fall back to a static default:

KnownFolderWindows envdefaultProfileUSERPROFILE, HOMEDRIVE + HOMEPATH🚨 Error 🚨LocalAppDataLOCALAPPDATA$HOME/AppData/LocalRoamingAppDataAPPDATA$HOME/AppData/RoamingProgramDataProgramData%SystemDrive%/ProgramData, C:/ProgramData### MacOS

[](#macos)

XDG envFallbackXDG\_CONFIG\_HOME$HOME/Library/Application SupportXDG\_DATA\_HOME$HOME/Library/Application SupportXDG\_STATE\_HOME$HOME/Library/Application SupportXDG\_CACHE\_HOME$HOME/Library/cachesXDG\_RUNTIME\_DIR$HOME/Library/Application SupportXDG\_CONFIG\_DIRS$HOME/Library/Preferences, /Library/Application Support, /Library/PreferencesXDG\_DATA\_DIRS/Library/Application Support

###  Health Score

29

—

LowBetter than 59% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity13

Limited adoption so far

Community11

Small or concentrated contributor base

Maturity60

Established project with proven stability

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~29 days

Recently: every ~37 days

Total

6

Last Release

1174d ago

Major Versions

0.3 → 1.02023-02-03

### Community

Maintainers

![](https://www.gravatar.com/avatar/db8c537fa479fd389b9ef832345ebf665f767e3ff7c7c345bc0ba4c52b46a22f?d=identicon)[ju1ius](/maintainers/ju1ius)

---

Top Contributors

[![ju1ius](https://avatars.githubusercontent.com/u/218404?v=4)](https://github.com/ju1ius "ju1ius (29 commits)")

---

Tags

base-directoryfreedesktopxdg

### Embed Badge

![Health badge](/badges/xdg-base-directory/health.svg)

```
[![Health](https://phpackages.com/badges/xdg-base-directory/health.svg)](https://phpackages.com/packages/xdg-base-directory)
```

###  Alternatives

[phpro/soap-client

A general purpose SoapClient library

8885.6M46](/packages/phpro-soap-client)[symplify/monorepo-builder

Not only Composer tools to build a Monorepo.

5205.3M82](/packages/symplify-monorepo-builder)[pocketmine/pocketmine-mp

A server software for Minecraft: Bedrock Edition written in PHP

3.5k74.6k86](/packages/pocketmine-pocketmine-mp)[friendsoftypo3/content-blocks

TYPO3 CMS Content Blocks - Content Types API | Define reusable components via YAML

96374.6k23](/packages/friendsoftypo3-content-blocks)[solspace/craft-freeform

The most flexible and user-friendly form building plugin!

52664.9k12](/packages/solspace-craft-freeform)[shyim/danger-php

Port of danger to PHP

8544.9k](/packages/shyim-danger-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)