README

Retrieve strongly typed values from deeply nested arrays.

This library will not set any values or manipulate data structures in any way. It is purely a way to retrieve information.

Usage

Give me a typed value or throw an exception

use GSteel\Dot;
use GSteel\MissingKey;
use GSteel\InvalidValue;
use stdClass;

$data = [
    'data' => [
        'float' => 1.23,
        'integer' => 42,
        'bool' => true,
        'string' => 'Goats',
        'callable' => static fn (): string => 'Hey!',
        'instance' => new stdClass(),
        'mixed' => null,
        'array' => ['a' => 'b'],
    ],
];

$value = Dot::float('data.float', $data); // 1.23
$value = Dot::integer('data.integer', $data); // 42
$value = Dot::bool('data.bool', $data); // true
$value = Dot::string('data.string', $data); // Goats
$value = Dot::callable('data.callable', $data); // function
$value = Dot::instanceOf('data.instance', $data, stdClass::class); // object<stdClass>
$value = Dot::valueAt('data.mixed'); // mixed
$value = Dot::array('data.array'); // ['a' => 'b']

$value = Dot::string('nope.not-there', $data); // Exception: MissingKey
$value = Dot::string('data.float', $data); // Exception: InvalidValue

Retrieve a typed value or null

All the methods have consistent names, so floatOrNull, boolOrNull etc.

use GSteel\Dot;

$data = ['a' => ['b' => ['c' => 'foo']]];

$value = Dot::stringOrNull('a.b.c', $data); // "foo"
$value = Dot::stringOrNull('a.b.nope', $data); // null
$value = Dot::integerOrNull('a.b.c', $data); // null

Retrieve a typed existing value or fallback to a given default

use GSteel\Dot;

$data = ['a' => ['b' => ['c' => 'foo']]];

$value = Dot::stringDefault('a.b.c', $data, 'bar'); // "foo"
$value = Dot::stringDefault('a.b.nope', $data, 'bar'); // "bar"
$value = Dot::integerDefault('a.b.c', $data, 42); // 42

Dots in the array keys?

use GSteel\Dot;

$data = [
    'data' => [
        'dot.here' => 'value',
        'slash/dot.' => 'value',
        'array/' => [
            'd.o.t.s' => [
                'p|pes' => 'value',
            ],      
        ],
    ],
];

$value = Dot::string('data/dot.here', $data, '/'); // "value"
$value = Dot::string('data|slash/dot.', $data, '|'); // "value"
$value = Dot::string('data*array/*d.o.t.s*p|pes', $data, '*'); // "value"

Why?

As a mostly happy psalm user, it is really boring telling Psalm the configuration array you just retrieved from your DI container has a possibly null string value somewhere. For example:

use GSteel\Dot;

$config = $container->get('config');

$connectionParams = $config['doctrine']['connection']['params'] ?? [];
// 👆 Psalm has no idea what that is.

// Alternatively…

$params = [
    'host' => Dot::stringDefault('doctrine.connection.params.host', $config, 'localhost'),
    'port' => Dot::integerDefault('doctrine.connection.params.port', $config, 1234),
];

Hasn't this been done before?

Yes. Here's a few:

• dflydev/dflydev-dot-access-data
• adbario/php-dot-notation
• https://packagist.org/?query=array%20dot