gsteel / dot
A Utility for retrieving typed values from nested arrays
Installs: 114 800
Dependents: 7
Suggesters: 0
Security: 0
Stars: 3
Watchers: 1
Forks: 0
Open Issues: 2
Requires
- php: ~8.1 || ~8.2.0 || ~8.3
Requires (Dev)
- doctrine/coding-standard: ^12.0.0
- phpunit/phpunit: ^10.3.4
- psalm/plugin-phpunit: ^0.18.4
- squizlabs/php_codesniffer: ^3.7.2
- vimeo/psalm: ^5.15.0
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: