From 6afd54fdcb1f0764745f89f6266bdb3acffffada Mon Sep 17 00:00:00 2001 From: David Schoenbauer Date: Fri, 2 Dec 2016 10:35:40 -0600 Subject: [PATCH 1/2] Added static constructor with() --- src/DotNotation/ArrayDotNotation.php | 13 ++++++++++++- tests/DotNotation/ArrayDotNotationTest.php | 13 +++++++++++++ 2 files changed, 25 insertions(+), 1 deletion(-) diff --git a/src/DotNotation/ArrayDotNotation.php b/src/DotNotation/ArrayDotNotation.php index 2fcc92c..6cce7b9 100644 --- a/src/DotNotation/ArrayDotNotation.php +++ b/src/DotNotation/ArrayDotNotation.php @@ -44,13 +44,24 @@ class ArrayDotNotation { * @var array */ private $_data = []; + + /** + * Sets the data to parse in a chain + * @param array $data optional Array of data that will be accessed via dot notation. + * @author John Smart + * @author David Schoenbauer + * @return \static + */ + public static function with(array $data = []){ + return new static($data); + } /** * An alias for setData * * @see ArrayDotNotation::setData() * @since 1.0.0 - * @param array $data Array of data that will be accessed via dot notation. + * @param array $data optional Array of data that will be accessed via dot notation. */ public function __construct(array $data = []) { $this->setData($data); diff --git a/tests/DotNotation/ArrayDotNotationTest.php b/tests/DotNotation/ArrayDotNotationTest.php index 2818593..e71c0a9 100644 --- a/tests/DotNotation/ArrayDotNotationTest.php +++ b/tests/DotNotation/ArrayDotNotationTest.php @@ -37,6 +37,19 @@ public function testDataConstructor() { $object = new ArrayDotNotation($data); $this->assertEquals($data, $object->getData()); } + + public function testWith(){ + $this->assertInstanceOf(ArrayDotNotation::class, ArrayDotNotation::with()); + } + + public function testWithData(){ + $data = ['test'=>'value']; + $this->assertEquals($data, ArrayDotNotation::with($data)->getData()); + } + + public function testWithNoData(){ + $this->assertEquals([], ArrayDotNotation::with()->getData()); + } public function testGet() { $this->assertEquals('someValueB', $this->_object->get('levelA.levelB')); From 39ae6eb56d2bcde99221e230ce9427a83ad856cb Mon Sep 17 00:00:00 2001 From: David Schoenbauer Date: Fri, 2 Dec 2016 10:38:29 -0600 Subject: [PATCH 2/2] updated documentation --- ...oenbauer.DotNotation.ArrayDotNotation.html | 68 +++- ...oenbauer.DotNotation.ArrayDotNotation.html | 331 +++++++++--------- 2 files changed, 227 insertions(+), 172 deletions(-) diff --git a/docs/class-DSchoenbauer.DotNotation.ArrayDotNotation.html b/docs/class-DSchoenbauer.DotNotation.ArrayDotNotation.html index 0b59099..eb37f0a 100644 --- a/docs/class-DSchoenbauer.DotNotation.ArrayDotNotation.html +++ b/docs/class-DSchoenbauer.DotNotation.ArrayDotNotation.html @@ -114,7 +114,7 @@

Class ArrayDotNotation

David Schoenbauer
Version: 1.0.1
- Located at DotNotation/ArrayDotNotation.php + Located at DotNotation/ArrayDotNotation.php
@@ -122,6 +122,50 @@

Class ArrayDotNotation

+ + + + + +
Methods summary
+ public static + + static + + +
+ # + with( array $data = [] ) + +
+

Sets the data to parse in a chain

+
+ + +
@@ -134,7 +178,7 @@

Class ArrayDotNotation

# - __construct( array $data = [] ) + __construct( array $data = [] )

An alias for setData

@@ -147,7 +191,7 @@

Class ArrayDotNotation

Parameters

$data
-
Array of data that will be accessed via dot notation.
+
optional Array of data that will be accessed via dot notation.
@@ -177,7 +221,7 @@

See

# - getData( ) + getData( )

returns the array

@@ -217,7 +261,7 @@

Since

# - setData( array $data ) + setData( array $data )

sets the array that the dot notation will be used on.

@@ -260,7 +304,7 @@

Since

# - get( string $dotNotation, mixed $defaultValue = null ) + get( string $dotNotation, mixed $defaultValue = null )

Retrieves a value from an array structure as defined by a dot notation string

@@ -307,7 +351,7 @@

Since

# - recursiveGet( array $data, array $keys, mixed $defaultValue ) + recursiveGet( array $data, array $keys, mixed $defaultValue )

Recursively works though an array level by level until the final key is found. Once key is found the keys value is returned.

@@ -354,7 +398,7 @@

Since

# - set( string $dotNotation, mixed $value ) + set( string $dotNotation, mixed $value )

sets a value into a complicated array data structure

@@ -409,7 +453,7 @@

Since

# - recursiveSet( array & $data, array $keys, mixed $value ) + recursiveSet( array & $data, array $keys, mixed $value )

Transverses the keys array until it reaches the appropriate key in the data array and sets that key to the value. @@ -458,7 +502,7 @@

Since

# - merge( string $dotNotation, array $value ) + merge( string $dotNotation, array $value )

Merges two arrays together over writing existing values with new values, while adding new array structure to the data

@@ -508,7 +552,7 @@

Since

# - remove( string $dotNotation ) + remove( string $dotNotation )

Removes data from the array

@@ -551,7 +595,7 @@

Since

# - recursiveRemove( array & $data, array $keys ) + recursiveRemove( array & $data, array $keys )

Transverses the keys array until it reaches the appropriate key in the diff --git a/docs/source-class-DSchoenbauer.DotNotation.ArrayDotNotation.html b/docs/source-class-DSchoenbauer.DotNotation.ArrayDotNotation.html index 5034efa..1fa745c 100644 --- a/docs/source-class-DSchoenbauer.DotNotation.ArrayDotNotation.html +++ b/docs/source-class-DSchoenbauer.DotNotation.ArrayDotNotation.html @@ -147,174 +147,185 @@

Exceptions

44: * @var array 45: */ 46: private $_data = []; - 47: + 47: 48: /** - 49: * An alias for setData - 50: * - 51: * @see ArrayDotNotation::setData() - 52: * @since 1.0.0 - 53: * @param array $data Array of data that will be accessed via dot notation. + 49: * Sets the data to parse in a chain + 50: * @param array $data optional Array of data that will be accessed via dot notation. + 51: * @author John Smart + 52: * @author David Schoenbauer + 53: * @return \static 54: */ - 55: public function __construct(array $data = []) { - 56: $this->setData($data); + 55: public static function with(array $data = []){ + 56: return new static($data); 57: } 58: 59: /** - 60: * returns the array + 60: * An alias for setData 61: * - 62: * returns the array that the dot notation has been used on. - 63: * - 64: * @since 1.0.0 - 65: * @return array Array of data that will be accessed via dot notation. - 66: */ - 67: public function getData() { - 68: return $this->_data; - 69: } - 70: - 71: /** - 72: * sets the array that the dot notation will be used on. - 73: * - 74: * @since 1.0.0 - 75: * @param array $data Array of data that will be accessed via dot notation. - 76: * @return $this + 62: * @see ArrayDotNotation::setData() + 63: * @since 1.0.0 + 64: * @param array $data optional Array of data that will be accessed via dot notation. + 65: */ + 66: public function __construct(array $data = []) { + 67: $this->setData($data); + 68: } + 69: + 70: /** + 71: * returns the array + 72: * + 73: * returns the array that the dot notation has been used on. + 74: * + 75: * @since 1.0.0 + 76: * @return array Array of data that will be accessed via dot notation. 77: */ - 78: public function setData(array $data) { - 79: $this->_data = $data; - 80: return $this; - 81: } - 82: - 83: /** - 84: * Retrieves a value from an array structure as defined by a dot notation string - 85: * - 86: * Returns a value from an array. - 87: * - 88: * @since 1.0.0 - 89: * @param string $dotNotation a string of keys concatenated together by a dot that represent different levels of an array - 90: * @param mixed $defaultValue value to return if the dot notation does not find a valid key - 91: * @return mixed value found via dot notation in the array of data - 92: */ - 93: public function get($dotNotation, $defaultValue = null) { - 94: return $this->recursiveGet($this->getData(), explode('.', $dotNotation), $defaultValue); - 95: } - 96: - 97: /** - 98: * Recursively works though an array level by level until the final key is found. Once key is found the keys value is returned. + 78: public function getData() { + 79: return $this->_data; + 80: } + 81: + 82: /** + 83: * sets the array that the dot notation will be used on. + 84: * + 85: * @since 1.0.0 + 86: * @param array $data Array of data that will be accessed via dot notation. + 87: * @return $this + 88: */ + 89: public function setData(array $data) { + 90: $this->_data = $data; + 91: return $this; + 92: } + 93: + 94: /** + 95: * Retrieves a value from an array structure as defined by a dot notation string + 96: * + 97: * Returns a value from an array. + 98: * 99: * @since 1.0.0 -100: * @param array $data array that has value to be retrieved -101: * @param array $keys array of keys for each level of the array -102: * @param mixed $defaultValue value to return when a key is not found -103: * @return mixed value that the keys find in the data array -104: */ -105: protected function recursiveGet($data, $keys, $defaultValue) { -106: $key = array_shift($keys); -107: if (is_array($data) && $key && count($keys) == 0) { //Last Key -108: return array_key_exists($key, $data) ? $data[$key] : $defaultValue; -109: } elseif (is_array($data) && array_key_exists($key, $data)) { -110: return $this->recursiveGet($data[$key], $keys, $defaultValue); -111: } -112: return $defaultValue; -113: } -114: -115: /** -116: * sets a value into a complicated array data structure -117: * -118: * Places a value into a tiered array. A dot notation of "one.two.three" -119: * would place the value at ['one' => ['two' => ['three' => 'valueHere' ]]] -120: * If the array does not exist it will be added. Indexed arrays can be used, -121: * and referenced by number. i.e. "one.0" would return the first item of the -122: * one array. -123: * -124: * @since 1.0.0 -125: * @param string $dotNotation dot notation representation of keys of where to set a value -126: * @param mixed $value any value to be stored with in a key structure of dot notation -127: * @return $this -128: * @throws PathNotArrayException if a value in the dot notation path is not an array -129: */ -130: public function set($dotNotation, $value) { -131: $this->recursiveSet($this->_data, explode('.', $dotNotation), $value); -132: return $this; -133: } -134: -135: /** -136: * Transverses the keys array until it reaches the appropriate key in the data array and sets that key to the value. -137: * If the keys don't exist they are created. -138: * -139: * @since 1.0.0 -140: * @param array $data data to be traversed -141: * @param array $keys the remaining keys of focus for the data array -142: * @param mixed $value the value to be placed at the final key -143: * @throws PathNotArrayException if a value in the dot notation path is not an array -144: */ -145: protected function recursiveSet(array &$data, array $keys, $value) { -146: $key = array_shift($keys); -147: if ($key && count($keys) == 0) { //Last Key -148: $data[$key] = $value; -149: } else { -150: if (!array_key_exists($key, $data)) { -151: $data[$key] = []; -152: } elseif (!is_array($data[$key])) { -153: throw new Exception\PathNotArrayException($key); -154: } -155: $this->recursiveSet($data[$key], $keys, $value); -156: } -157: } -158: -159: /** -160: * Merges two arrays together over writing existing values with new values, while adding new array structure to the data -161: * -162: * @since 1.1.0 -163: * @param string $dotNotation dot notation representation of keys of where to set a value -164: * @param array $value array to be merged with an existing array -165: * @return $this -166: * @throws UnexpectedValueException if a value in the dot notation path is not an array -167: * @throws TargetNotArrayException if the value in the dot notation target is not an array -168: */ -169: public function merge($dotNotation, array $value) { -170: $target = $this->get($dotNotation, []); -171: if (!is_array($target)) { -172: throw new Exception\TargetNotArrayException($dotNotation); -173: } -174: $this->set($dotNotation, array_merge_recursive($target, $value)); -175: return $this; -176: } -177: -178: /** -179: * Removes data from the array -180: * -181: * @since 1.1.0 -182: * @param string $dotNotation dot notation representation of keys of where to remove a value -183: * @return $this -184: */ -185: public function remove($dotNotation) { -186: $this->recursiveRemove($this->_data, explode('.', $dotNotation), $dotNotation); -187: return $this; -188: } -189: -190: /** -191: * Transverses the keys array until it reaches the appropriate key in the -192: * data array and then deletes the value from the key. -193: * -194: * @since 1.1.0 -195: * @param array $data data to be traversed -196: * @param array $keys the remaining keys of focus for the data array -197: * @throws UnexpectedValueException if a value in the dot notation path is -198: * not an array -199: */ -200: protected function recursiveRemove(array &$data, array $keys) { -201: $key = array_shift($keys); -202: if (!array_key_exists($key, $data)) { -203: throw new PathNotFoundException($key); -204: } elseif ($key && count($keys) == 0) { //Last Key -205: unset($data[$key]); -206: } elseif (!is_array($data[$key])) { -207: throw new PathNotArrayException($key); -208: } else { -209: $this->recursiveRemove($data[$key], $keys); -210: } -211: } -212: -213: } -214: +100: * @param string $dotNotation a string of keys concatenated together by a dot that represent different levels of an array +101: * @param mixed $defaultValue value to return if the dot notation does not find a valid key +102: * @return mixed value found via dot notation in the array of data +103: */ +104: public function get($dotNotation, $defaultValue = null) { +105: return $this->recursiveGet($this->getData(), explode('.', $dotNotation), $defaultValue); +106: } +107: +108: /** +109: * Recursively works though an array level by level until the final key is found. Once key is found the keys value is returned. +110: * @since 1.0.0 +111: * @param array $data array that has value to be retrieved +112: * @param array $keys array of keys for each level of the array +113: * @param mixed $defaultValue value to return when a key is not found +114: * @return mixed value that the keys find in the data array +115: */ +116: protected function recursiveGet($data, $keys, $defaultValue) { +117: $key = array_shift($keys); +118: if (is_array($data) && $key && count($keys) == 0) { //Last Key +119: return array_key_exists($key, $data) ? $data[$key] : $defaultValue; +120: } elseif (is_array($data) && array_key_exists($key, $data)) { +121: return $this->recursiveGet($data[$key], $keys, $defaultValue); +122: } +123: return $defaultValue; +124: } +125: +126: /** +127: * sets a value into a complicated array data structure +128: * +129: * Places a value into a tiered array. A dot notation of "one.two.three" +130: * would place the value at ['one' => ['two' => ['three' => 'valueHere' ]]] +131: * If the array does not exist it will be added. Indexed arrays can be used, +132: * and referenced by number. i.e. "one.0" would return the first item of the +133: * one array. +134: * +135: * @since 1.0.0 +136: * @param string $dotNotation dot notation representation of keys of where to set a value +137: * @param mixed $value any value to be stored with in a key structure of dot notation +138: * @return $this +139: * @throws PathNotArrayException if a value in the dot notation path is not an array +140: */ +141: public function set($dotNotation, $value) { +142: $this->recursiveSet($this->_data, explode('.', $dotNotation), $value); +143: return $this; +144: } +145: +146: /** +147: * Transverses the keys array until it reaches the appropriate key in the data array and sets that key to the value. +148: * If the keys don't exist they are created. +149: * +150: * @since 1.0.0 +151: * @param array $data data to be traversed +152: * @param array $keys the remaining keys of focus for the data array +153: * @param mixed $value the value to be placed at the final key +154: * @throws PathNotArrayException if a value in the dot notation path is not an array +155: */ +156: protected function recursiveSet(array &$data, array $keys, $value) { +157: $key = array_shift($keys); +158: if ($key && count($keys) == 0) { //Last Key +159: $data[$key] = $value; +160: } else { +161: if (!array_key_exists($key, $data)) { +162: $data[$key] = []; +163: } elseif (!is_array($data[$key])) { +164: throw new Exception\PathNotArrayException($key); +165: } +166: $this->recursiveSet($data[$key], $keys, $value); +167: } +168: } +169: +170: /** +171: * Merges two arrays together over writing existing values with new values, while adding new array structure to the data +172: * +173: * @since 1.1.0 +174: * @param string $dotNotation dot notation representation of keys of where to set a value +175: * @param array $value array to be merged with an existing array +176: * @return $this +177: * @throws UnexpectedValueException if a value in the dot notation path is not an array +178: * @throws TargetNotArrayException if the value in the dot notation target is not an array +179: */ +180: public function merge($dotNotation, array $value) { +181: $target = $this->get($dotNotation, []); +182: if (!is_array($target)) { +183: throw new Exception\TargetNotArrayException($dotNotation); +184: } +185: $this->set($dotNotation, array_merge_recursive($target, $value)); +186: return $this; +187: } +188: +189: /** +190: * Removes data from the array +191: * +192: * @since 1.1.0 +193: * @param string $dotNotation dot notation representation of keys of where to remove a value +194: * @return $this +195: */ +196: public function remove($dotNotation) { +197: $this->recursiveRemove($this->_data, explode('.', $dotNotation), $dotNotation); +198: return $this; +199: } +200: +201: /** +202: * Transverses the keys array until it reaches the appropriate key in the +203: * data array and then deletes the value from the key. +204: * +205: * @since 1.1.0 +206: * @param array $data data to be traversed +207: * @param array $keys the remaining keys of focus for the data array +208: * @throws UnexpectedValueException if a value in the dot notation path is +209: * not an array +210: */ +211: protected function recursiveRemove(array &$data, array $keys) { +212: $key = array_shift($keys); +213: if (!array_key_exists($key, $data)) { +214: throw new PathNotFoundException($key); +215: } elseif ($key && count($keys) == 0) { //Last Key +216: unset($data[$key]); +217: } elseif (!is_array($data[$key])) { +218: throw new PathNotArrayException($key); +219: } else { +220: $this->recursiveRemove($data[$key], $keys); +221: } +222: } +223: +224: } +225: