Add path, path_or, prop, prop_or, props functions

composer.json

@@ -82,10 +82,15 @@
             "src/Functional/PartialMethod.php",
             "src/Functional/PartialRight.php",
             "src/Functional/Partition.php",
+            "src/Functional/Path.php",
+            "src/Functional/PathOr.php",
             "src/Functional/Pick.php",
             "src/Functional/Pluck.php",
             "src/Functional/Poll.php",
             "src/Functional/Product.php",
+            "src/Functional/Prop.php",
+            "src/Functional/PropOr.php",
+            "src/Functional/Props.php",
             "src/Functional/Ratio.php",
             "src/Functional/ReduceLeft.php",
             "src/Functional/ReduceRight.php",

src/Functional/Functional.php

@@ -299,6 +299,16 @@ final class Functional
      */
     const partition = '\Functional\partition';
 
+    /**
+     * @see \Functional\path
+     */
+    const path = '\Functional\path';
+
+    /**
+     * @see \Functional\path_or
+     */
+    const path_or = '\Functional\path_or';
+
     /**
      * @see \Functional\pick
      */
@@ -319,6 +329,21 @@ final class Functional
      */
     const product = '\Functional\product';
 
+    /**
+     * @see \Functional\prop
+     */
+    const prop = '\Functional\prop';
+
+    /**
+     * @see \Functional\prop_or
+     */
+    const prop_or = '\Functional\prop_or';
+
+    /**
+     * @see \Functional\props
+     */
+    const props = '\Functional\props';
+
     /**
      * @see \Functional\ratio
      */

src/Functional/Path.php

@@ -0,0 +1,35 @@
+<?php
+/**
+ * Copyright (C) 2019 by Sergei Kolesnikov <[email protected]>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+namespace Functional;
+
+/**
+ * Retrieve the value at a given path.
+ *
+ * @param array $path The path to use
+ * @param array|object $item The object or array to retrieve the nested property from
+ * @return mixed The value at the given path or null if it not exists
+ */
+function path(array $path, $item)
+{
+    return path_or(null, $path, $item);
+}

src/Functional/PathOr.php

@@ -0,0 +1,42 @@
+<?php
+/**
+ * Copyright (C) 2019 by Sergei Kolesnikov <[email protected]>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+namespace Functional;
+
+/**
+ * Retrieve the value at a given path.
+ *
+ * @param mixed $default Default value if the value at specified path not found
+ * @param array $path The path to use
+ * @param array|object $item The object or array to retrieve the nested property from
+ * @return mixed The value at the given path or the default if it not exists
+ */
+function path_or($default, array $path, $item)
+{
+    return \array_reduce(
+        $path,
+        function ($item, $key) use ($default) {
+            return prop_or($default, $key, $item);
+        },
+        $item
+    );
+}

src/Functional/Prop.php

@@ -0,0 +1,35 @@
+<?php
+/**
+ * Copyright (C) 2019 by Sergei Kolesnikov <[email protected]>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+namespace Functional;
+
+/**
+ * Returns the indicated property of the item, if it exists, or null, if not.
+ *
+ * @param mixed $key The property name
+ * @param array|object $item The object or array to query
+ * @return mixed The value
+ */
+function prop($key, $item)
+{
+    return prop_or(null, $key, $item);
+}

src/Functional/PropOr.php

@@ -0,0 +1,45 @@
+<?php
+/**
+ * Copyright (C) 2019 by Sergei Kolesnikov <[email protected]>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+namespace Functional;
+
+/**
+ * Returns the indicated property of the item, if it exists, or the default value, if not.
+ *
+ * @param mixed $default Default value if the property not found
+ * @param mixed $key The property name
+ * @param array|object $item The object or array to query
+ * @return mixed The value
+ */
+function prop_or($default, $key, $item)
+{
+    switch (true) {
+        case \is_array($item) || $item instanceof \ArrayAccess:
+            return $item[$key] ?? $default;
+
+        case \is_object($item) && isset($item->$key):
+            return $item->$key ?? $default;
+
+        default:
+            return $default;
+    }
+}

src/Functional/Props.php

@@ -0,0 +1,41 @@
+<?php
+/**
+ * Copyright (C) 2019 by Sergei Kolesnikov <[email protected]>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+namespace Functional;
+
+/**
+ * Acts as multiple prop: array of keys in, array of values out. Preserves order.
+ *
+ * @param array $keys The property names to fetch
+ * @param array|object $item The object or array to query
+ * @return mixed The value
+ */
+function props(array $keys, $item)
+{
+    $result = [];
+
+    foreach ($keys as $key) {
+        $result[] = prop($key, $item);
+    }
+
+    return $result;
+}

tests/Functional/PathOrTest.php

@@ -0,0 +1,73 @@
+<?php
+/**
+ * Copyright (C) 2019 by Sergei Kolesnikov <[email protected]>
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in
+ * all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+ * THE SOFTWARE.
+ */
+namespace Functional\Tests;
+
+use function Functional\path_or;
+
+class PathOrTest extends AbstractTestCase
+{
+    const DEFAULT = 'amazing default value';
+
+    /**
+     * @dataProvider provider
+     *
+     * @param $expected
+     * @param $path
+     * @param $item
+     */
+    public function testPropOr($expected, $path, $item)
+    {
+        $this->assertEquals($expected, path_or(static::DEFAULT, $path, $item));
+    }
+
+    public function provider()
+    {
+        $object = new class {
+            private $a = 5;
+            public $b = 5;
+        };
+
+        $objectTestGetter = new class {
+            public function __get($propertyName)
+            {
+                throw new \RuntimeException($propertyName);
+            }
+        };
+
+        return [
+            ['42', ['a'], (object)['a' => '42', 'b' => '69']],
+            ['42', ['a'], ['a' => '42', 'b' => '69']],
+            ['69', ['42', 'a'], ['42' => ['a' => '69']]],
+            ['69', ['42', 0], ['42' => ['69']]],
+            [static::DEFAULT, ['a'], ['b' => '69']],
+            [static::DEFAULT, ['a'], $object],
+            [static::DEFAULT, ['b', 'x'], $object],
+            [static::DEFAULT, ['anyField'], $objectTestGetter],
+            [static::DEFAULT, ['anyField', 'deep'], $objectTestGetter],
+            ['a', [0], \SplFixedArray::fromArray(['a', 'b', 'c'])],
+            [static::DEFAULT, ['nonExisting'], new \ArrayObject(['a', 'b', 'c'])],
+            ['42', ['first', 'a'], new \ArrayObject(['first' => (object)['a' => '42', 'b' => '69'], 'b', 'c'])],
+            [static::DEFAULT, ['first', 'a', 'x'], new \ArrayObject(['first' => (object)['a' => '42', 'b' => '69'], 'b', 'c'])],
+        ];
+    }
+}