PHPackages                             best/dot-notation - 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. best/dot-notation

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

best/dot-notation
=================

Compact, MongoDB-like dot notation for manipulating and creating arrays.

v5.0(2y ago)711.6k↓70.3%2MITPHPPHP >=7.1

Since Nov 20Pushed 2y agoCompare

[ Source](https://github.com/dmeybohm/dot-notation)[ Packagist](https://packagist.org/packages/best/dot-notation)[ Docs](http://github.com/dmeybohm/dot-notation)[ RSS](/packages/best-dot-notation/feed)WikiDiscussions master Synced 2d ago

READMEChangelog (10)Dependencies (2)Versions (18)Used By (0)

Dot Notation
============

[](#dot-notation)

This supports a dotted syntax similar to [MongoDB's dot notation](http://docs.mongodb.org/manual/core/document/#dot-notation) for creating and manipulating deeply nested arrays compactly in PHP. This notation is also used by other projects, such as Elasticsearch and CakePHP.

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

[](#installation)

```
composer require best/dot-notation

```

Overview
--------

[](#overview)

This package has a single class with static methods, `\Best\DotNotation`.

There are two main groups of methods: those that operate recursively across an entire array, and those that get/set values from such arrays.

### Recursive methods

[](#recursive-methods)

For the recursive methods, you can use `expand` and `compact` methods to convert the dots from the expanded form and the compact form, and these operations are inverses of each other:

```
use Best\DotNotation;

$array = DotNotation::compact(array(
  'my' => array(
      'dotted' ==> array(
          'key' => 'value'
      )
  )
));
// returns the dotted array:
array('my.dotted.key' => 'value');

// convert back to the other form:
$original = DotNotation::expand(['my.dotted.key' => 'value']);
```

### Get/set values

[](#getset-values)

For the other methods, pass an array as their first argument, and most then a "key path" as their second argument, that determines which keys on the array to operate on.

The key path can include dots to indicate subkeys of arrays to access.

For example, to access the key `'child'` of the array key `'parent'` on the variable `$container`, you would do:

```
$container = array('parent' => array('child' => '2'));
$childElement = \Best\DotNotation::get($container, 'parent.child');
// $childElement === '2' here
```

You can also use numbers as keys. For example, to access the second array element in the key `'parent'` of the variable `$container`, you would do this: (Note these are zero-indexed just like normal PHP arrays, so to get the second element, you specify .1 as the key):

```
$container = array('parent' => array('child0', 'child1'));
$secondElement = \Best\DotNotation::get($container, 'parent.1');
// $secondElement === 'child1' here.
```

You can also use bare integers:

```
$container = array('parent0', 'parent1', 'parent2');
$thirdElement = \Best\DotNotation::get($container, 2);
// $thirdElement === 'parent2' here.
```

Furthermore you can combine integer and string keys arbitrarily as well:

```
$container = array('parent0', array('child' => array('grandChild' => 'greatGrandChild'))));
$greatGrandChild = \Best\DotNotation::get($container, '1.child.grandChild')
// $greatGrandChild === 'greatGrandChild' here.
```

### Escaping dot to include it in keys

[](#escaping-dot-to-include-it-in-keys)

If you want to include a literal dot inside a key name, you can escape it with a backslash.

```
$container = array('my.dotted.key' => 'value');
$value = \Best\DotNotation::get($container, 'my\.dotted\.key'));
// equals: 'value'
```

Backslash is not treated as a special character in any other case, though. So you can use them in keys as long as it doesn't preceed a dot. Neither backslashes nor dots in values are transformed in any way, either.

Methods
-------

[](#methods)

Most of these methods require a valid key path. A valid key path is either an integer or non-empty string. Passing an invalid key path will result in a `\Best\DotNotation\BadKeyPath` exception.

### Get Methods

[](#get-methods)

#### `get(array $array, string|int $keyPath): mixed`

[](#getarray-array-stringint-keypath-mixed)

Get the value stored at the key path.

If any of the keys do not exist in the key path, this will throw a `\Best\DotNotation\KeyNotFound` exception.

#### `getOrNull(array $array, string|int $keyPath): mixed`

[](#getornullarray-array-stringint-keypath-mixed)

Get the value stored at the key path.

If any of the keys do not exist in the key path, this will return null.

#### `getOrDefault(array $array, string|int $keyPath, mixed $defaultValue): mixed`

[](#getordefaultarray-array-stringint-keypath-mixed-defaultvalue-mixed)

Get the value stored at the key path.

If any of the keys do not exist in the key path, this will return the default value from the third argument.

#### `has(array $array, string|int $keyPath): bool`

[](#hasarray-array-stringint-keypath-bool)

Whether the array has a value at the key path.

Note that even if this value is `null`, this will still return `true`.

```
use Best\DotNotation;

$container = ['movies' => [
    [
        'title' => 'Batman V. Superman - Dawn of Justice',
        'director' => 'Zack Snyder'
        'lead actor 1' => 'Henry Cavill'
        'lead actor 2' => 'Ben Affleck'
        'supporting actor 1' => 'Gal Gadot'
        'supporting actor 2' => 'Jesse Eisenberg'
    ],
    [
        'title' => 'La La Land',
        'director' => 'Damian Chazelle'
    ],
    [
        'title' => 'Justice League',
    ],
];

$zackSnyder = DotNotation::get($container, 'movies.0.director');
// $zackSnyder === 'Zack Snyder'

$null = DotNotation::getOrNull($container, 'movies.1.lead actor');
// $null === null

$jossWhedon = DotNotation::getOrDefault($container, 'movies.2.director', 'Joss Whedon');
// $jossWhedon === 'Joss Whedon'

$hasDirector = DotNotation::has($container, 'movies.2.director');
// $hasDirector === false
```

### Set Methods

[](#set-methods)

#### `set(): array`

[](#set-array)

Set the value

#### `setAndOverride(array $array, string|int $keyPath): array`

[](#setandoverridearray-array-stringint-keypath-array)

Set the path, and ignore any invalid intermediate keys, setting them to empty arrays along the way.

The new array with the key set is returned.

### Remove Methods

[](#remove-methods)

#### `remove()`

[](#remove)

Remove the value from the key path if it exists. A `\Best\DotNotation\KeyNotFound` exception is thrown if any of the keys in the key path do not exist.

#### `removeIfExists(array $array, string|int $keyPath)`

[](#removeifexistsarray-array-stringint-keypath)

Remove the value from the key path if it exists. No exception is thrown if the key path does not exist.

The new array with the key removed is returned.

### Recursive Methods

[](#recursive-methods-1)

#### `expand(array $dottedArray): array`

[](#expandarray-dottedarray-array)

Recursively expand the dots inside the keys into new arrays. Returns the newly expanded array.

If any inconsistent keys are detected (some keys are defined as scalars in some keys and are implicitly arrays in other keys), a `\Best\DotNotation\InconsistentKeyTypes`exception will be thrown.

#### `compact(array $array): array`

[](#compactarray-array-array)

Compact the array into a dotted array, with keys, suitable for passing to `expand()`.

For example:

```
use Best\DotNotation;

$array = DotNotation::compact(array(
  'my' => array(
      'dotted' ==> array(
          'key' => 'value'
      )
  )
));
// returns the dotted array:
array('my.dotted.key' => 'value');
```

#### `compactWithIntegerKeys(array $array): array`

[](#compactwithintegerkeysarray-array-array)

Compact the array as in `compact()`, but also compact integer keys, so that the array will be as flat as possible.

For example,

```
$array = \Best\DotNotation::compact(array(
  'my' => array(
      'dotted' ==> array(
          'key' => 'value'
      )
  )
));
// returns the dotted array:
array('my.dotted.key' => 'value');
```

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity32

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity67

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 ~312 days

Recently: every ~448 days

Total

10

Last Release

1072d ago

Major Versions

v2.0.0 → v3.02018-02-11

v3.0 → v4.02018-02-11

v1.0.1 → v2.0.22018-09-01

v2.0.2 → v4.0.12018-09-01

v3.0.1 → v5.02023-07-28

### Community

Maintainers

![](https://www.gravatar.com/avatar/4f638012772d62414fb8e4fc79f75ff62e626783bddc974da668750a8086bded?d=identicon)[best](/maintainers/best)

---

Top Contributors

[![dmeybohm](https://avatars.githubusercontent.com/u/99535?v=4)](https://github.com/dmeybohm "dmeybohm (145 commits)")

---

Tags

configurationarrayconfigzendmongo

###  Code Quality

TestsPHPUnit

Type Coverage Yes

### Embed Badge

![Health badge](/badges/best-dot-notation/health.svg)

```
[![Health](https://phpackages.com/badges/best-dot-notation/health.svg)](https://phpackages.com/packages/best-dot-notation)
```

###  Alternatives

[league/config

Define configuration arrays with strict schemas and access values with dot notation

565335.0M36](/packages/league-config)[symfony/options-resolver

Provides an improved replacement for the array\_replace PHP function

3.2k525.7M2.0k](/packages/symfony-options-resolver)[grasmash/expander

Expands internal property references in PHP arrays.

14064.3M10](/packages/grasmash-expander)[dflydev/dot-access-configuration

Given a deep data structure representing a configuration, access configuration by dot notation.

13414.5M4](/packages/dflydev-dot-access-configuration)[jbzoo/data

An extended version of the ArrayObject object for working with system settings or just for working with data arrays

851.6M23](/packages/jbzoo-data)[illuminatech/array-factory

Allows DI aware object creation from array definition

2266.2k6](/packages/illuminatech-array-factory)

PHPackages © 2026

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