README

DotKey

Dot notation access for objects and arrays.

Inspired by the node.js Dotty library.

Installation

composer require jasny/dotkey 

Usage

use Jasny\DotKey\DotKey; $subject = [ "a" => [ "b" => [ "x" => "y" ] ] ]; DotKey::on($subject)->exists("a.b.x"); // true DotKey::on($subject)->exists("a.b.z"); // false DotKey::on($subject)->exists("a.b.x.o"); // false DotKey::on($subject)->get("a.b.x"); // "y" DotKey::on($subject)->get("a.b"); // ["x" => "y"] DotKey::on($subject)->get("a.b.z"); // null DotKey::on($subject)->get("a.b.x.o"); // Throws ResolveException because a.b.x is a string DotKey::on($subject)->set("a.b.q", "foo"); // $subject = ["a" => ["b" => ["x" => "y", "q" => "foo"]]] DotKey::on($subject)->set("a.d", ['p' => 1]); // $subject = ["a" => ["b" => ["x" => "y"]], "d" => ["p" => 1]] DotKey::on($subject)->set("a.c.x", "bar"); // Throws ResolveException because a.c doesn't exist DotKey::on($subject)->set("a.b.x.o", "qux"); // Throws ResolveException because a.b.x is a string DotKey::on($subject)->put("a.b.q", "foo"); // $subject = ["a" => ["b" => ["x" => "y", "q" => "foo"]]] DotKey::on($subject)->put("a.c.x", "bar"); // $subject = ["a" => ["b" => ["x" => "y"]], "c" => ["x" => "bar"]] DotKey::on($subject)->remove("a.b.x"); // $subject = ["a" => ["b" => []]] DotKey::on($subject)->remove("a.c.z"); // $subject isn't modified DotKey::on($subject)->remove("a.b.x.o"); // Throws ResolveException because a.b.x is a string DotKey::on($subject)->remove("a.b"); // $subject = ["a" => []] DotKey::on($subject)->update("a.b", fn($value) => array_map('strtoupper', $value)); // $subject = ["a" => ["b" => ["x" => "Y"]]]

The subject may be an array or object. If an object implements ArrayAccess it will be treated as array.

use Jasny\DotKey\DotKey; $obj = (object)["a" => (object)["b" => (object)["x" => "y"]]]; DotKey::on($obj)->exists("a.b.x"); DotKey::on($obj)->set("a.b.q", "foo");

exists() will return false when trying access a private or static property. All other methods will throw a ResolveException.

Copy

By default, the target is modified in place. With the onCopy() factory method, a copy will be made instead.

use Jasny\DotKey\DotKey; $source = ["a" => ["b" => ["x" => "y"]]]; DotKey::onCopy($source, $copy)->set("a.b.q", "foo"); // $copy = ["a" => ["b" => ["x" => "y", "q" => "foo"]]]

With onCopy(), objects will be cloned if they're modified.

use Jasny\DotKey\DotKey; $source = (object)["f" => (object)["x" => "y"], "g" => (object)["x" => "z"]]]]; DotKey::onCopy($source, $copy)->set("f.q", "foo"); $copy === $source; // false, source is cloned $copy->f === $source->f; // false, `f` is cloned and modified $copy->g === $source->g; // true, `g` is not cloned

Delimiter

The default delimiter is a dot, but any string can be used as delimiter. Leading and trailing delimiters are stripped.

use Jasny\DotKey\DotKey; DotKey::on($subject)->exists('/a/b/x', '/'); DotKey::on($subject)->get("/a/b/x", '/'); DotKey::on($subject)->set("/a/b/q", "foo", '/'); DotKey::on($subject)->put("/a/b/q", "foo", '/'); DotKey::on($subject)->remove("/a/b/q", '/'); DotKey::on($subject)->exists('a::b::c', '::');

Set vs Put

• set('a.b.c', 1) requires 'a.b' to exist and be an object or array. If that's not the case, a ResolveException is thrown.
• put('a.b.c', 1) will always result in $result["a"]["b"]["c"] === 1. If 'a.b' doesn't exist, it will be created. If it already exists and isn't an array or object, it will be overwritten.

The structure put() creates is either an associative array or an \stdClass object, depending on the type of the subject. Passing true as fourth argument forces this to an array, while passing false forces it to create an object.

use Jasny\DotKey\DotKey; $subject = ["a" => null]; $obj = (object)["a" => null]; DotKey::on($subject)->put("a.b.o", 1, '.'); // ["a" => ["b" => ["o" => 1]]] DotKey::on($subject)->put("a.b.o", 1, '.', true); // ["a" => ["b" => ["o" => 1]]] DotKey::on($subject)->put("a.b.o", 1, '.', false); // ["a" => (object)["b" => (object)["o" => 1]]] DotKey::on($obj)->put("a.b.o", 1, '.'); // (object)["a" => (object)["b" => (object)["o" => 1]]] DotKey::on($obj)->put("a.b.o", 1, '.', true); // (object)["a" => ["b" => ["o" => 1]]] DotKey::on($obj)->put("a.b.o", 1, '.', false); // (object)["a" => (object)["b" => (object)["o" => 1]]]