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)04592MITPHPPHP >=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 today

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 57% 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

1220d 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

[composer/composer

Composer helps you declare, manage and install dependencies of PHP projects. It ensures you have the right stack everywhere.

29.5k196.2M3.1k](/packages/composer-composer)[aws/aws-sdk-php

AWS SDK for PHP - Use Amazon Web Services in your PHP project

6.3k543.5M2.6k](/packages/aws-aws-sdk-php)[symfony/config

Helps you find, load, combine, autofill and validate configuration values of any kind

4.3k479.6M8.4k](/packages/symfony-config)[friendsofphp/php-cs-fixer

A tool to automatically fix PHP code style

13.5k251.2M25.2k](/packages/friendsofphp-php-cs-fixer)[symfony/asset-mapper

Maps directories of assets & makes them available in a public directory with versioned filenames.

1678.8M238](/packages/symfony-asset-mapper)[pocketmine/pocketmine-mp

A server software for Minecraft: Bedrock Edition written in PHP

3.5k78.3k90](/packages/pocketmine-pocketmine-mp)

PHPackages © 2026

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