Dot Notation Parser

DotNotationParser turns dot-delimited paths into an ordered list of keys. Use it when configuration, request parameters, or nested data need a compact path syntax. For example, account.profile.name becomes [ 'account', 'profile', 'name' ].

Keys may contain dots when wrapped in double quotes. Escape a literal double quote with a backslash. The parser reports invalid paths with the character offset that caused the error, so callers can return useful feedback.

Requirements

• php: >=8.2

Installing

Install the latest version with:

composer require 'quorum/dot-notation'

Example

<?php

use Quorum\DotNotation\DotNotationParser;

require __DIR__ . '/../vendor/autoload.php';

$parser = new DotNotationParser;

$tests = [
	'foo',
	'foo.bar',
	'spaces are allowed'                  => 'foo bar.baz',
	'dots are accepted in quotes'         => '"foo.bar".baz',
	'quotes are escaped with backslashes' => '"foo\"bar\"".baz',
];

foreach( $tests as $descr => $test ) {
	echo sprintf("Parsing '%s'%s\n",
		$test,
		is_numeric($descr) ? '' : ' - ' . $descr);

	$parts = $parser->parse($test);

	echo sprintf("[ %s ]\n", implode(", ", array_map(
		function ( $a ) { return var_export($a, true); },
		$parts)));
	echo "\n";
}

Parsing 'foo'
[ 'foo' ]

Parsing 'foo.bar'
[ 'foo', 'bar' ]

Parsing 'foo bar.baz' - spaces are allowed
[ 'foo bar', 'baz' ]

Parsing '"foo.bar".baz' - dots are accepted in quotes
[ 'foo.bar', 'baz' ]

Parsing '"foo\"bar\"".baz' - quotes are escaped with backslashes
[ 'foo"bar"', 'baz' ]

Documentation

Class: Quorum\DotNotation\DotNotationParser

Class DotPathParser

Parse strings like foo."bar.baz".quux into [ 'foo', 'bar.baz', 'quux' ]

Method: DotNotationParser->parse

function parse(string $path): array

Parse a given dot notation path into it's parts

The path is expected to be a string of dot separated keys, where keys can be
quoted with double quotes. Backslashes are used to escape double quotes inside
quoted keys.

Examples

• 'foo.bar.baz' => [ 'foo', 'bar', 'baz' ]
• 'foo."bar.baz"' => [ 'foo', 'bar.baz' ]
• 'foo."bar.baz".quux' => [ 'foo', 'bar.baz', 'quux' ]
• 'foo."bar\"baz".quux' => [ 'foo', 'bar"baz', 'quux' ]

Throws: \Quorum\DotNotation\Exceptions\ParseException

Return Value

• list