lodash-php · sfinktah · Sep 10, 2023 · Nov 2, 2023 · pierredup · Nov 2, 2023
diff --git a/composer.json b/composer.json
@@ -1,5 +1,5 @@
 {
-    "name": "lodash-php/lodash-php",
+    "name": "sfinktah/lodash-php",
     "description": "A port of Lodash to PHP",
     "keywords": [
         "lodash",
@@ -24,13 +24,12 @@
     },
     "require": {
         "php": ">=7.1",
-        "sebastian/comparator": "^1.2 | ^2.0 | ^2.1 | ^3.0 | ^4.0",
-        "symfony/property-access": "^2.7 | ^3.0 | ^4.0 | ^5.0"
+        "sebastian/comparator": "*",
+        "symfony/property-access": "*"
     },
     "require-dev": {
-        "phpdocumentor/reflection-docblock": "^4.2",
-        "bamarni/composer-bin-plugin": "^1.2",
-        "phpstan/phpdoc-parser": "^0.3.0"
+        "bamarni/composer-bin-plugin": "*",
+        "phpunit/phpunit": "^10"
     },
     "scripts": {
         "post-install-cmd": ["@composer bin all install --ansi"],

diff --git a/src/Array/firstOr.php b/src/Array/firstOr.php
@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the SolidWorx Lodash-PHP project.
+ *
+ * @author     Pierre du Plessis <open-source@solidworx.co>
+ * @copyright  Copyright (c) 2017
+ */
+
+namespace _;
+
+/**
+ * Gets the first element of `array` or `default` if the array is empty
+ *
+ * @alias    firstOr
+ * @param mixed $array The array to query.
+ * @param mixed|callable $default Value or Callable if array is empty *
+ *
+ * @return mixed Returns the first element of `array` or `default` if empty.
+ *
+ * @category Array
+ *
+ * @example
+ * <code>
+ * head([1, 2, 3])
+ * // => 1
+ *
+ * head([])
+ * // => null
+ * </code>
+ */
+function headOr(mixed $array, mixed $default)
+{
+    if ((is_array($array) || $array instanceof \ArrayObject) && count($array)) {
+        return reset($array);
+    }
+    else if (is_string($array) && strlen($array)) {
+        return substr($array, 0, 1);
+    }
+    return is_callable($default) ? $default($array) : $default;
+}
+
+/* alias to head() */
+function firstOr(mixed $array, mixed $default)
+{
+    return headOr($array, $default);
+}
+
diff --git a/src/Array/head.php b/src/Array/head.php
@@ -17,7 +17,7 @@
  * @alias    first
  * @category Array
  *
- * @param array $array The array to query.
+ * @param mixed $array The array to query.
  *
  * @return mixed Returns the first element of `array`.
  *
@@ -30,15 +30,43 @@
  * // => null
  * </code>
  */
-function head(array $array)
+function head(mixed $array)
 {
-    reset($array);
-
-    return current($array) ?: null;
+    if ((is_array($array) || $array instanceof \ArrayObject) && count($array)) {
+        return reset($array);
+    }
+    else if (is_string($array) && strlen($array)) {
+        return substr($array, 0, 1);
+    }
+    return null;
 }
 
 /* alias to head() */
-function first(array $array)
+function first(mixed $array)
 {
     return head($array);
 }
+
+$COMMENT = <<<JSON
+# lodash (4.17.15) (JavaScript)
+```js
+function head(array) {
+  return (array && array.length) ? array[0] : undefined;
+}
+```
+> a = [ [], [1], [1, 2], "123", "1", null, false, "" ];
+> b = _.map(a, function(v) { return _.first(v); });
+> JSON.stringify({a:a, b:b});
+{"a":[[],[1],[1,2],"123","1",null,false,""],"b":[null,1,1,"1","1",null,null,null]}
+
+
+# Underscore.js (1.13.6) (JavaScript)
+{"a":[[],[1],[1,2],"123","1",null,false,""],"b":[null,1,1,"1","1",null,null,null]}
+```js
+export default function first(array, n, guard) {
+  if (array == null || array.length < 1) return n == null || guard ? void 0 : [];
+  if (n == null || guard) return array[0];
+  return initial(array, array.length - n);
+}
+```
+JSON;
diff --git a/src/Lang/castArray.php b/src/Lang/castArray.php
@@ -0,0 +1,55 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the SolidWorx Lodash-PHP project.
+ *
+ * @author     Pierre du Plessis <open-source@solidworx.co>
+ * @copyright  Copyright (c) 2017
+ */
+
+namespace _;
+
+/**
+ * Casts `value` as an array if it's not one.
+ *
+ * @param mixed $value The value to cast
+ *
+ * @returns {Array} Returns the cast array.
+ * @param  array $array The array to concatenate.
+ *
+ * @return array Returns the cast array.
+ *
+ * @example
+ *
+ * _.castArray(1);
+ * // => [1]
+ *
+ * _.castArray({ 'a': 1 });
+ * // => [{ 'a': 1 }]
+ *
+ * _.castArray('abc');
+ * // => ['abc']
+ *
+ * _.castArray(null);
+ * // => [null]
+ *
+ * _.castArray(undefined);
+ * // => [undefined]
+ *
+ * _.castArray();
+ * // => []
+ *
+ * var array = [1, 2, 3];
+ * console.log(_.castArray(array) === array);
+ * // => true
+ */
+function castArray($value): array
+{
+    $check = function ($value): array {
+        return \is_array($value) ? $value : [$value];
+    };
+
+    return $check($value);
+}
diff --git a/src/Lang/isArrayLike.php b/src/Lang/isArrayLike.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the SolidWorx Lodash-PHP project.
+ *
+ * @author     Pierre du Plessis <open-source@solidworx.co>
+ * @copyright  Copyright (c) 2017
+ */
+
+namespace _;
+
+use SebastianBergmann\Comparator\ComparisonFailure;
+use SebastianBergmann\Comparator\Factory;
+
+/**
+ * Check if the value is an Array and that the keys are entirely numeric (integer)
+ *
+ * @category Lang
+ *
+ * @param mixed $value The value to check.
+ *
+ * @return  bool Returns `true` if the value is an array, else `false`.
+ *
+ * @example
+ * <code>
+ *
+ * $object = [ 'a' => 1]
+ * $array = [ 'a' ]
+ *
+ * isArrayLike($array)
+ * // => true
+ *
+ * isArrayLike($object)
+ * // => false
+ *
+ * </code>
+ */
+function isArrayLike(mixed $value): bool {
+    return is_array($value) && every(array_keys($value), function ($key) {
+            return is_int($key);
+        });
+}
diff --git a/src/Lang/isObjectLike.php b/src/Lang/isObjectLike.php
@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the SolidWorx Lodash-PHP project.
+ *
+ * @author     Pierre du Plessis <open-source@solidworx.co>
+ * @copyright  Copyright (c) 2017
+ */
+
+namespace _;
+
+use SebastianBergmann\Comparator\ComparisonFailure;
+use SebastianBergmann\Comparator\Factory;
+
+/**
+ * Check if the value is an Array and that not all keys are entirely numeric (integer)
+ *
+ * @category Lang
+ *
+ * @param mixed $value The value to check.
+ *
+ * @return  bool Returns `true` if the value is an object-like array, else `false`.
+ *
+ * @example
+ * <code>
+ *
+ * $object = [ 'a' => 1]
+ * $array = [ 'a' ]
+ *
+ * isObjectLike($array)
+ * // => false
+ *
+ * isObjectLike($object)
+ * // => true
+ *
+ * </code>
+ */
+function isObjectLike(mixed $value): bool {
+    return $value instanceof \stdClass || is_array($value) && !every(array_keys($value), function ($key) {
+            return is_int($key);
+        });
+}
diff --git a/src/Object/assign.php b/src/Object/assign.php
@@ -0,0 +1,54 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the SolidWorx Lodash-PHP project.
+ *
+ * @author     Pierre du Plessis <open-source@solidworx.co>
+ * @copyright  Copyright (c) 2018
+ */
+
+namespace _;
+
+use function _\internal\basePick;
+use function _\internal\flatRest;
+
+/**
+ * Assigns own enumerable string keyed properties of source objects to the
+ * destination object. Source objects are applied from left to right.
+ * Subsequent sources overwrite property assignments of previous sources.
+ *
+ * **Note:** This method mutates `object` and is loosely based on
+ * [`Object.assign`](https://mdn.io/Object/assign).
+ *
+ * @param object $object The destination object.
+ * @param object ...$sources The source objects.
+ * @return object Returns the new object.
+ * @category Object
+ * @since 0.10.0
+ * @example
+ *
+ * function Foo() {
+ *   this.a = 1;
+ * }
+ *
+ * function Bar() {
+ *   this.c = 3;
+ * }
+ *
+ * Foo.prototype.b = 2;
+ * Bar.prototype.d = 4;
+ *
+ * _.assign({ 'a': 0 }, new Foo, new Bar);
+ * // => { 'a': 1, 'c': 3 }
+ */
+function assign(object $object, object ...$sources): \stdClass
+{
+    foreach ($sources as $source) {
+        foreach ($source as $key => $value) {
+            $object->$key = $value;
+        }
+    }
+    return $object;
+}
diff --git a/src/Object/omit.php b/src/Object/omit.php
@@ -0,0 +1,45 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the SolidWorx Lodash-PHP project.
+ *
+ * @author     Pierre du Plessis <open-source@solidworx.co>
+ * @copyright  Copyright (c) 2018
+ */
+
+namespace _;
+
+use function _\internal\basePick;
+use function _\internal\flatRest;
+
+/**
+ * The opposite of `_.pick`; this method creates an object composed of the
+ * own and inherited enumerable property paths of `object` that are not omitted.
+ *
+ * **Note:** This method is considerably slower than `_.pick`.
+ *
+ * @static
+ * @since 0.1.0
+ * @memberOf _
+ * @category Object
+ * @param array $object The source object.
+ * @returns array Returns the new object.
+ * @example
+ *
+ * var object = { 'a': 1, 'b': '2', 'c': 3 };
+ *
+ * _.omit(object, ['a', 'c']);
+ * // => { 'b': '2' }
+ */
+function omit(array $object, array $paths): array
+{
+    $result = [];
+    foreach ($object as $key => $value) {
+        if (!in_array($key, $paths)) {
+            $result[$key] = $value;
+        }
+    }
+    return $result;
+}