Update return and input type hints

Remove deprecated methods
Add additional set tests

CHANGELOG.md

@@ -1,6 +1,19 @@
 Change Log
 ==========
 
+2021-01-20
+----------
+
+ * Add union return types and better type hints
+ * Update docs
+
+2021-01-18
+----------
+
+ * Update for PHP8
+ * Update docs
+ * Remove deprecated v4.X methods
+
 2020-10-05 - 4.0.1
 ------------------
 

CHANGELOG_V5.md

@@ -0,0 +1,30 @@
+
+## Important Changes in 5.X series
+
+### Re-namespaced
+
+`Somnambulist\Collection` is now `Somnambulist\Components\Collection`. This is a change being
+made to all the `somnambulist/*` packages.
+
+### PHP 8 Compatibility
+
+The 5.X series properly supports PHP 8 and makes use of PHP 8 features such as the static return
+type, union types and the mixed return type.
+
+PHP 8 is now required to use this library.
+
+### Removal of all 4.X deprecated features
+
+All features previously marked as deprecated in the 4.X series have been removed. This includes:
+
+ * `sortUsing()`
+ * `sortUsingWithKeys()`
+ * `sortByValue()`
+ * `sortByValueReversed()`
+ * `sortByKey()`
+ * `sortByKeyReversed()`
+
+### Miscellaneous Changes
+
+ * Keys are typed to `int|string` across the board instead of inferred mixed/string
+ * `GetWithDotNotation::get()` no longer supports `null` for all values; use `all()` instead

README.md

@@ -43,6 +43,7 @@ suggest a better name!
 
  * [V3 Deprecations, API changes](CHANGELOG_V3.md)
  * [V4 Deprecations, API changes](CHANGELOG_V4.md)
+ * [V5 Deprecations, API changes](CHANGELOG_V5.md)
 
 ## Requirements
 
@@ -98,18 +99,18 @@ $collection->map()->filter()...
 Freeze changes to a collection:
 
 ```php
-$locked = $collection->freeze()
+$locked = $collection->freeze();
 
 // raises exception
-$locked->shift()
+$locked->shift();
 ```
 Use a custom Immutable collection class:
 ```php
 MutableCollection::setFreezeableClass();
-$locked = $collection->freeze()
+$locked = $collection->freeze();
 
 // raises exception
-$locked->shift()
+$locked->shift();
 ```
 
 ### Dot Access

composer.json

@@ -15,12 +15,12 @@
         }
     ],
     "require": {
-        "php": ">=7.4",
+        "php": ">=8.0",
         "ext-json": "*"
     },
     "require-dev": {
-        "phpunit/phpunit": "~9.3",
-        "symfony/var-dumper": "~5",
+        "phpunit/phpunit": "~9.5",
+        "symfony/var-dumper": "~5.2",
         "victorjonsson/markdowndocs": "^1.3"
     },
     "autoload": {

docs/aggregates.md

@@ -11,12 +11,12 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>average(</strong><em>null/string/callable</em> <strong>$key=null</strong>)</strong> : <em>float/int</em><br /><em>Returns the average of all values from the collection using the key</em> |
-| public | <strong>max(</strong><em>null/string/callable</em> <strong>$key=null</strong>)</strong> : <em>float/int</em><br /><em>Returns the highest value from the collection of values Key can be a string key or callable. Based on Laravel: Illuminate\Support\Collection.max</em> |
-| public | <strong>median(</strong><em>null/string/callable</em> <strong>$key=null</strong>)</strong> : <em>float/int</em><br /><em>Returns the median value of the min/max from the key</em> |
-| public | <strong>min(</strong><em>null/string/callable</em> <strong>$key=null</strong>)</strong> : <em>float/int</em><br /><em>Returns the lowest value from the collection of values Key can be a string key or callable. Based on Laravel: Illuminate\Support\Collection.min</em> |
-| public | <strong>modal(</strong><em>null/string/callable</em> <strong>$key=null</strong>)</strong> : <em>mixed</em><br /><em>Returns the modal (most frequent) value from the collection based on the key In the case of a single modal, returns that value (int/float). In the case of several modals, returns an array of each value If every value is a modal, returns false. If you have many modals, consider grouping by occurrence instead.</em> |
-| public | <strong>sum(</strong><em>null/string/callable</em> <strong>$key=null</strong>)</strong> : <em>float/int</em><br /><em>Sum items in the collection, optionally matching the key / callable Based on Laravel: Illuminate\Support\Collection.sum</em> |
+| public | <strong>average(</strong><em>\null</em> <strong>$key=null</strong>)</strong> : <em>float/int</em><br /><em>Returns the average of all values from the collection using the key</em> |
+| public | <strong>max(</strong><em>\null</em> <strong>$key=null</strong>)</strong> : <em>mixed int/float or an array of the key => value that is the max value</em><br /><em>Returns the highest value from the collection of values Key can be a string key or callable. Based on Laravel: Illuminate\Support\Collection.max</em> |
+| public | <strong>median(</strong><em>\null</em> <strong>$key=null</strong>)</strong> : <em>float/int</em><br /><em>Returns the median value of the min/max from the key</em> |
+| public | <strong>min(</strong><em>\null</em> <strong>$key=null</strong>)</strong> : <em>mixed int/float or an array of the key => value that is the min value</em><br /><em>Returns the lowest value from the collection of values Key can be a string key or callable. Based on Laravel: Illuminate\Support\Collection.min</em> |
+| public | <strong>modal(</strong><em>\null</em> <strong>$key=null</strong>)</strong> : <em>mixed int/float or an array of the key => value that are the modal values</em><br /><em>Returns the modal (most frequent) value from the collection based on the key In the case of a single modal, returns that value (int/float). In the case of several modals, returns an array of each value If every value is a modal, returns false. If you have many modals, consider grouping by occurrence instead.</em> |
+| public | <strong>sum(</strong><em>\null</em> <strong>$key=null</strong>)</strong> : <em>float/int</em><br /><em>Sum items in the collection, optionally matching the key / callable Based on Laravel: Illuminate\Support\Collection.sum</em> |
 
 <hr />
 
@@ -26,5 +26,5 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>countBy(</strong><em>\callable</em> <strong>$callback=null</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\Aggregate\static</em><br /><em>Count the number of items in the collection using a given test</em> |
+| public | <strong>countBy(</strong><em>\callable</em> <strong>$callback=null</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Count the number of items in the collection using a given test</em> |
 

docs/assertable.md

@@ -10,5 +10,5 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>assert(</strong><em>\callable</em> <strong>$callback</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\Assertion\static</em><br /><em>Run the test for all items in the collection; failures raise an exception</em> |
+| public | <strong>assert(</strong><em>\callable</em> <strong>$callback</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Run the test for all items in the collection; failures raise an exception</em> |
 

docs/comparable.md

@@ -12,10 +12,10 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>diff(</strong><em>mixed</em> <strong>$items</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\Compare\static</em><br /><em>Get the items in the collection that are not present in the given items.</em> |
-| public | <strong>diffAssoc(</strong><em>mixed</em> <strong>$items</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\Compare\static</em><br /><em>Get the items in the collection whose keys and values are not present in the given items.</em> |
-| public | <strong>diffAssocUsing(</strong><em>mixed</em> <strong>$items</strong>, <em>\callable</em> <strong>$callback</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\Compare\static</em><br /><em>Get the items in the collection whose keys and values are not present in the given items.</em> |
-| public | <strong>diffUsing(</strong><em>mixed</em> <strong>$items</strong>, <em>\callable</em> <strong>$callback</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\Compare\static</em><br /><em>Get the items in the collection that are not present in the given items.</em> |
+| public | <strong>diff(</strong><em>\mixed</em> <strong>$items</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Get the items in the collection that are not present in the given items.</em> |
+| public | <strong>diffAssoc(</strong><em>\mixed</em> <strong>$items</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Get the items in the collection whose keys and values are not present in the given items.</em> |
+| public | <strong>diffAssocUsing(</strong><em>\mixed</em> <strong>$items</strong>, <em>\callable</em> <strong>$callback</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Get the items in the collection whose keys and values are not present in the given items.</em> |
+| public | <strong>diffUsing(</strong><em>\mixed</em> <strong>$items</strong>, <em>\callable</em> <strong>$callback</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Get the items in the collection that are not present in the given items.</em> |
 
 <hr />
 
@@ -25,8 +25,8 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>intersect(</strong><em>mixed</em> <strong>$items</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\Compare\static</em><br /><em>Intersect the collection with the given items.</em> |
-| public | <strong>intersectByKeys(</strong><em>mixed</em> <strong>$items</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\Compare\static</em><br /><em>Intersect the collection with the given items by key.</em> |
+| public | <strong>intersect(</strong><em>\mixed</em> <strong>$items</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Intersect the collection with the given items.</em> |
+| public | <strong>intersectByKeys(</strong><em>\mixed</em> <strong>$items</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Intersect the collection with the given items by key.</em> |
 
 <hr />
 
@@ -36,6 +36,6 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>diffKeys(</strong><em>mixed</em> <strong>$items</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\Compare\static</em><br /><em>Get the items in the collection whose keys are not present in the given items.</em> |
-| public | <strong>diffKeysUsing(</strong><em>mixed</em> <strong>$items</strong>, <em>\callable</em> <strong>$callback</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\Compare\static</em><br /><em>Get the items in the collection whose keys are not present in the given items.</em> |
+| public | <strong>diffKeys(</strong><em>\mixed</em> <strong>$items</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Get the items in the collection whose keys are not present in the given items.</em> |
+| public | <strong>diffKeysUsing(</strong><em>\mixed</em> <strong>$items</strong>, <em>\callable</em> <strong>$callback</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Get the items in the collection whose keys are not present in the given items.</em> |
 

docs/exportable.md

@@ -16,7 +16,7 @@
 | Visibility | Function |
 |:-----------|:---------|
 | public | <strong>serialize()</strong> : <em>string</em> |
-| public | <strong>unserialize(</strong><em>string</em> <strong>$serialized</strong>)</strong> : <em>void</em> |
+| public | <strong>unserialize(</strong><em>\string</em> <strong>$serialized</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em> |
 
 <hr />
 
@@ -26,7 +26,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>implode(</strong><em>string</em> <strong>$glue=`','`</strong>, <em>null/string/\Somnambulist\Components\Collection\Behaviours\Export\Closure</em> <strong>$value=null</strong>, <em>null/string</em> <strong>$withKeys=null</strong>)</strong> : <em>string</em><br /><em>Implodes all the values into a single string, objects should support __toString If a specific value is specified it will be pulled from any sub-arrays or objects; alternatively it can be a closure to fetch specific properties from any objects in the collection. If $withKeys is set to a string, it will prefix the string value with the key and the $withKeys string.</em> |
+| public | <strong>implode(</strong><em>\string</em> <strong>$glue=`','`</strong>, <em>\null</em> <strong>$value=null</strong>, <em>\string</em> <strong>$withKeys=null</strong>)</strong> : <em>string</em><br /><em>Implodes all the values into a single string, objects should support __toString If a specific value is specified it will be pulled from any sub-arrays or objects; alternatively it can be a closure to fetch specific properties from any objects in the collection. If $withKeys is set to a string, it will prefix the string value with the key and the $withKeys string.</em> |
 | public | <strong>toString()</strong> : <em>string</em><br /><em>Converts the collection to a JSON string</em> |
 
 <hr />
@@ -57,7 +57,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>JsonSerialize()</strong> : <em>array</em><br /><em>Returns the collection in a form suitable for encoding to JSON</em> |
+| public | <strong>jsonSerialize()</strong> : <em>array</em><br /><em>Returns the collection in a form suitable for encoding to JSON</em> |
 
 <hr />
 
@@ -67,5 +67,5 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>toQueryString(</strong><em>string</em> <strong>$separator=`'&'`</strong>, <em>int</em> <strong>$encoding=2</strong>)</strong> : <em>string</em><br /><em>Returns a HTTP query string of the values Note: should only be used with elements that can be cast to scalars.</em> |
+| public | <strong>toQueryString(</strong><em>\string</em> <strong>$separator=`'&'`</strong>, <em>\int</em> <strong>$encoding=2</strong>)</strong> : <em>string</em><br /><em>Returns a HTTP query string of the values Note: should only be used with elements that can be cast to scalars.</em> |
 

docs/mappable.md

@@ -15,7 +15,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>reduce(</strong><em>\callable</em> <strong>$callback</strong>, <em>mixed</em> <strong>$initial=null</strong>)</strong> : <em>mixed</em><br /><em>Reduces the Collection to a single value, returning it, or $initial if no value</em> |
+| public | <strong>reduce(</strong><em>\callable</em> <strong>$callback</strong>, <em>\mixed</em> <strong>$initial=null</strong>)</strong> : <em>mixed</em><br /><em>Reduces the Collection to a single value, returning it, or $initial if no value</em> |
 
 <hr />
 
@@ -25,7 +25,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>collapse()</strong> : <em>\Somnambulist\Components\Collection\Behaviours\MapReduce\static</em><br /><em>Collapse the collection of items into a single array</em> |
+| public | <strong>collapse()</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Collapse the collection of items into a single array</em> |
 
 <hr />
 
@@ -35,7 +35,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>map(</strong><em>callable/string</em> <strong>$callable</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\MapReduce\static</em><br /><em>Apply the callback to all elements in the collection Note: the callable should accept 2 arguments, the value and the key. For single argument callables only the value will be passed in. The argument count of the callable will attempt to be found. This works on methods, functions and static callable (Class::method).</em> |
+| public | <strong>map(</strong><em>callable/string/\string</em> <strong>$callable</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Apply the callback to all elements in the collection Note: the callable should accept 2 arguments, the value and the key. For single argument callables only the value will be passed in. The argument count of the callable will attempt to be found. This works on methods, functions and static callable (Class::method).</em> |
 
 <hr />
 
@@ -45,7 +45,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>mapInto(</strong><em>\string</em> <strong>$class</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\MapReduce\static</em><br /><em>Map the values into a new class.</em> |
+| public | <strong>mapInto(</strong><em>\string</em> <strong>$class</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Map the values into a new class.</em> |
 
 <hr />
 
@@ -55,7 +55,7 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>flatMap(</strong><em>\callable</em> <strong>$callable</strong>)</strong> : <em>\Somnambulist\Components\Collection\Behaviours\MapReduce\static</em><br /><em>Map a collection and flatten the result by a single level</em> |
+| public | <strong>flatMap(</strong><em>\callable</em> <strong>$callable</strong>)</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Map a collection and flatten the result by a single level</em> |
 
 <hr />
 
@@ -65,6 +65,6 @@
 
 | Visibility | Function |
 |:-----------|:---------|
-| public | <strong>flatten()</strong> : <em>\Somnambulist\Components\Collection\Behaviours\MapReduce\static</em><br /><em>Returns a new Collection with all sub-sets / arrays merged into one Collection If similar keys exist, they will be overwritten. This method is intended to convert a multi-dimensional array into a key => value array. This method is called recursively through the Collection.</em> |
-| public | <strong>flattenWithDotKeys()</strong> : <em>\Somnambulist\Components\Collection\Behaviours\MapReduce\static</em><br /><em>Returns a new Collection with all sub-sets / arrays merged into one Collection Key names are flattened into dot notation, though overwrites may still occur.</em> |
+| public | <strong>flatten()</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Returns a new Collection with all sub-sets / arrays merged into one Collection If similar keys exist, they will be overwritten. This method is intended to convert a multi-dimensional array into a key => value array. This method is called recursively through the Collection.</em> |
+| public | <strong>flattenWithDotKeys()</strong> : <em>\Somnambulist\Components\Collection\Collection/static</em><br /><em>Returns a new Collection with all sub-sets / arrays merged into one Collection Key names are flattened into dot notation, though overwrites may still occur.</em> |