├── .github └── workflows │ └── release.yml ├── .gitignore ├── AbstractCollection.php ├── AbstractList.php ├── ArrayList.php ├── Collection.php ├── CollectionUtils.php ├── LICENSE ├── Map.php ├── Queue.php ├── README.md ├── Set.php ├── Stack.php └── composer.json /.github/workflows/release.yml: -------------------------------------------------------------------------------- 1 | # Create a release when a version tag is pushed 2 | name: Create Release 3 | on: 4 | push: 5 | tags: 6 | - 'v*' 7 | jobs: 8 | build: 9 | name: Create Release 10 | runs-on: ubuntu-latest 11 | steps: 12 | - name: Checkout code 13 | uses: actions/checkout@v1 14 | - name: Create Release 15 | id: create_release 16 | uses: actions/create-release@v1 17 | env: 18 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 19 | with: 20 | tag_name: ${{ github.ref }} 21 | release_name: Release ${{ github.ref }} 22 | body: For changes in this release please see https://github.com/phootwork/phootwork/releases/tag/${{ github.ref }} 23 | draft: false 24 | prerelease: false -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | composer.phar 2 | composer.lock 3 | vendor/ 4 | -------------------------------------------------------------------------------- /AbstractCollection.php: -------------------------------------------------------------------------------- 1 | array = []; 25 | } 26 | 27 | /** 28 | * @internal 29 | */ 30 | public function rewind(): void { 31 | reset($this->array); 32 | } 33 | 34 | /** 35 | * @internal 36 | */ 37 | public function current(): mixed { 38 | return current($this->array); 39 | } 40 | 41 | /** 42 | * @internal 43 | */ 44 | public function key(): int|string|null { 45 | return key($this->array); 46 | } 47 | 48 | /** 49 | * @internal 50 | */ 51 | public function next(): void { 52 | next($this->array); 53 | } 54 | 55 | /** 56 | * @internal 57 | */ 58 | public function valid(): bool { 59 | return key($this->array) !== null; 60 | } 61 | } 62 | -------------------------------------------------------------------------------- /AbstractList.php: -------------------------------------------------------------------------------- 1 | sort($cmp)->reverse(); 42 | } 43 | } 44 | -------------------------------------------------------------------------------- /ArrayList.php: -------------------------------------------------------------------------------- 1 | add($element); 45 | } 46 | } 47 | 48 | /** 49 | * Removes an element from the list by its index. 50 | * 51 | * @param int $index 52 | * 53 | * @return ArrayList 54 | */ 55 | public function removeByIndex(int $index): self { 56 | if (isset($this->array[$index])) { 57 | unset($this->array[$index]); 58 | 59 | if (!array_is_list($this->array)) { 60 | $this->array = array_values($this->array); 61 | } 62 | } 63 | 64 | return $this; 65 | } 66 | 67 | /** 68 | * Returns the element at the given index (or null if the index isn't present) 69 | * 70 | * @param int $index 71 | * 72 | * @return mixed 73 | */ 74 | public function get(int $index): mixed { 75 | return $this->traitGet($index); 76 | } 77 | 78 | /** 79 | * Returns the index of the given element or null if the element can't be found 80 | * 81 | * @param mixed $element 82 | * 83 | * @return int|null the index for the given element 84 | */ 85 | public function indexOf(mixed $element): ?int { 86 | $index = $this->traitIndexOf($element); 87 | 88 | return $index === null ? $index : (int) $index; 89 | } 90 | 91 | /** 92 | * Searches the array with a given callback and returns the index for the last element if found. 93 | * 94 | * The callback function takes one or two parameters: 95 | * 96 | * function ($element [, $query]) {} 97 | * 98 | * The callback must return a boolean 99 | * When it's passed, $query must be the first argument: 100 | * 101 | * - find($query, callback) 102 | * - find(callback) 103 | * 104 | * @param array $arguments 105 | * 106 | * @return int|null the index or null if it hasn't been found 107 | */ 108 | public function findLastIndex(mixed ...$arguments): ?int { 109 | $lastIndex = $this->traitFindLastIndex(...$arguments); 110 | 111 | return $lastIndex === null ? $lastIndex : (int) $lastIndex; 112 | } 113 | 114 | /** 115 | * Searches the array with a given callback and returns the index for the first element if found. 116 | * 117 | * The callback function takes one or two parameters: 118 | * 119 | * function ($element [, $query]) {} 120 | * 121 | * The callback must return a boolean 122 | * When it's passed, $query must be the first argument: 123 | * 124 | * - find($query, callback) 125 | * - find(callback) 126 | * 127 | * @param array $arguments 128 | * 129 | * @return int|null the index or null if it hasn't been found 130 | */ 131 | public function findIndex(mixed ...$arguments): ?int { 132 | $index = $this->traitFindIndex(...$arguments); 133 | 134 | return $index === null ? $index : (int) $index; 135 | } 136 | } 137 | -------------------------------------------------------------------------------- /Collection.php: -------------------------------------------------------------------------------- 1 | $v) { 84 | $map->set($k, self::toCollection($v)); 85 | } 86 | 87 | return $map; 88 | } 89 | 90 | /** 91 | * Recursively transforms data into a list (on the first level, deeper levels 92 | * transformed to an appropriate collection) (experimental API) 93 | * 94 | * @param array|Iterator $collection 95 | * 96 | * @return ArrayList 97 | */ 98 | public static function toList(Iterator|array $collection): ArrayList { 99 | $list = new ArrayList(); 100 | /** @var mixed $v */ 101 | foreach ($collection as $v) { 102 | $list->add(self::toCollection($v)); 103 | } 104 | 105 | return $list; 106 | } 107 | 108 | /** 109 | * Recursively exports a collection to an array 110 | * 111 | * @param mixed $collection 112 | * 113 | * @return array 114 | * 115 | * @psalm-suppress MixedAssignment 116 | */ 117 | public static function toArrayRecursive(mixed $collection): array { 118 | $arr = $collection; 119 | if (is_object($collection) && method_exists($collection, 'toArray')) { 120 | $arr = $collection->toArray(); 121 | } 122 | 123 | /** @var array $arr */ 124 | return array_map( 125 | function (mixed $v): mixed { 126 | if (is_object($v) && method_exists($v, 'toArray')) { 127 | return static::toArrayRecursive($v); 128 | } 129 | 130 | return $v; 131 | }, 132 | $arr 133 | ); 134 | } 135 | } 136 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2015 - 2021 Thomas Gossmann 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | 23 | -------------------------------------------------------------------------------- /Map.php: -------------------------------------------------------------------------------- 1 | setAll($collection); 33 | } 34 | 35 | /** 36 | * Sets an element with the given key on that map 37 | * 38 | * @param string|int|Text $key 39 | * @param mixed $element 40 | * 41 | * @return Map $this 42 | */ 43 | public function set(string|int|Text $key, mixed $element): self { 44 | $key = is_int($key) ? $key : (string) $key; 45 | $this->array[$key] = $element; 46 | 47 | return $this; 48 | } 49 | 50 | /** 51 | * Returns the element for the given key 52 | * 53 | * @param string|int|Text $key 54 | * 55 | * @return mixed 56 | */ 57 | public function get(string|int|Text $key): mixed { 58 | $key = is_int($key) ? $key : (string) $key; 59 | 60 | return $this->array[$key] ?? null; 61 | } 62 | 63 | /** 64 | * Returns the key for the given value or null if not found 65 | * 66 | * @param mixed $value the value 67 | * 68 | * @return string|null 69 | */ 70 | public function getKey(mixed $value): ?string { 71 | /** 72 | * @var string $k 73 | * @var mixed $v 74 | */ 75 | foreach ($this->array as $k => $v) { 76 | if ($v === $value) { 77 | return $k; 78 | } 79 | } 80 | 81 | return null; 82 | } 83 | 84 | /** 85 | * Sets many elements on that map 86 | * 87 | * @param array|Iterator $collection 88 | * 89 | * @return Map $this 90 | */ 91 | public function setAll(array|Iterator $collection): self { 92 | /** 93 | * @var string $key 94 | * @var mixed $element 95 | */ 96 | foreach ($collection as $key => $element) { 97 | $this->set($key, $element); 98 | } 99 | 100 | return $this; 101 | } 102 | 103 | /** 104 | * Removes and returns an element from the map by the given key. Returns null if the key 105 | * does not exist. 106 | * 107 | * @param string|Text $key 108 | * 109 | * @return $this 110 | */ 111 | public function remove(string|Text $key): self { 112 | if (isset($this->array[(string) $key])) { 113 | unset($this->array[(string) $key]); 114 | } 115 | 116 | return $this; 117 | } 118 | 119 | /** 120 | * Returns all keys as Set 121 | * 122 | * @return Set the map's keys 123 | */ 124 | public function keys(): Set { 125 | return new Set(array_keys($this->array)); 126 | } 127 | 128 | /** 129 | * Returns all values as ArrayList 130 | * 131 | * @return ArrayList the map's values 132 | */ 133 | public function values(): ArrayList { 134 | return new ArrayList(array_values($this->array)); 135 | } 136 | 137 | /** 138 | * Returns whether the key exist. 139 | * 140 | * @param string|Text $key 141 | * 142 | * @return bool 143 | */ 144 | public function has(string|Text $key): bool { 145 | return isset($this->array[(string) $key]); 146 | } 147 | 148 | /** 149 | * Sorts the map 150 | * 151 | * @param Comparator|callable|null $cmp 152 | * 153 | * @return $this 154 | */ 155 | public function sort(Comparator|callable|null $cmp = null): AbstractArray { 156 | return $this->sortAssoc($cmp); 157 | } 158 | 159 | /** 160 | * Iterates the map and calls the callback function with the current key and value as parameters 161 | * 162 | * @param callable $callback 163 | */ 164 | public function each(callable $callback): void { 165 | /** 166 | * @var string $key 167 | * @var mixed $value 168 | */ 169 | foreach ($this->array as $key => $value) { 170 | $callback($key, $value); 171 | } 172 | } 173 | 174 | /** 175 | * Searches the collection with a given callback and returns the key for the first element if found. 176 | * 177 | * The callback function takes one or two parameters: 178 | * 179 | * function ($element [, $query]) {} 180 | * 181 | * The callback must return a boolean 182 | * When it's passed, $query must be the first argument: 183 | * 184 | * - find($query, callback) 185 | * - find(callback) 186 | * 187 | * @param array $arguments 188 | * 189 | * @return mixed|null the key or null if it hasn't been found 190 | */ 191 | public function findKey(mixed ...$arguments) { 192 | /** @var mixed $index */ 193 | $index = count($arguments) === 1 ? $this->find($arguments[0]) : $this->find($arguments[0], $arguments[1]); 194 | 195 | return $this->getKey($index); 196 | } 197 | 198 | /** 199 | * Searches the collection with a given callback and returns the key for the last element if found. 200 | * 201 | * The callback function takes one or two parameters: 202 | * 203 | * function ($element [, $query]) {} 204 | * 205 | * The callback must return a boolean 206 | * When it's passed, $query must be the first argument: 207 | * 208 | * - find($query, callback) 209 | * - find(callback) 210 | * 211 | * @param array $arguments 212 | * 213 | * @return mixed|null the key or null if it hasn't been found 214 | */ 215 | public function findLastKey(mixed ...$arguments) { 216 | /** @var mixed $index */ 217 | $index = count($arguments) === 1 ? $this->findLast($arguments[0]) : $this->findLast($arguments[0], $arguments[1]); 218 | 219 | return $this->getKey($index); 220 | } 221 | 222 | /** 223 | * @param mixed $offset 224 | * @param mixed $value 225 | * 226 | * @internal 227 | */ 228 | public function offsetSet(mixed $offset, mixed $value): void { 229 | /** @var string|null $offset */ 230 | if ($offset !== null) { 231 | $this->array[$offset] = $value; 232 | } 233 | } 234 | 235 | /** 236 | * @param mixed $offset 237 | * 238 | * @return bool 239 | * 240 | * @internal 241 | */ 242 | public function offsetExists(mixed $offset): bool { 243 | /** @var string $offset */ 244 | return isset($this->array[$offset]); 245 | } 246 | 247 | /** 248 | * @param mixed $offset 249 | * 250 | * @internal 251 | */ 252 | public function offsetUnset(mixed $offset): void { 253 | /** @var string $offset */ 254 | unset($this->array[$offset]); 255 | } 256 | 257 | /** 258 | * @param mixed $offset 259 | * 260 | * @return mixed 261 | * 262 | * @internal 263 | */ 264 | public function offsetGet(mixed $offset): mixed { 265 | /** @var string $offset */ 266 | return isset($this->array[$offset]) ? $this->array[$offset] : null; 267 | } 268 | } 269 | -------------------------------------------------------------------------------- /Queue.php: -------------------------------------------------------------------------------- 1 | enqueue(...$collection); 29 | } 30 | 31 | /** 32 | * Enqueues an element 33 | * 34 | * @param mixed ...$elements 35 | * 36 | * @return $this 37 | */ 38 | public function enqueue(mixed ...$elements): self { 39 | array_unshift($this->array, ...$elements); 40 | 41 | return $this; 42 | } 43 | 44 | /** 45 | * Returns the element at the head or null if the queue is empty but doesn't remove that element 46 | * 47 | * @return mixed 48 | */ 49 | public function peek(): mixed { 50 | if ($this->size() > 0) { 51 | return $this->array[0]; 52 | } 53 | 54 | return null; 55 | } 56 | 57 | /** 58 | * Removes and returns the element at the head or null if the is empty 59 | * 60 | * @return mixed 61 | */ 62 | public function poll(): mixed { 63 | return array_shift($this->array); 64 | } 65 | } 66 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # PHP Collections library 2 | 3 | ![Tests](https://github.com/phootwork/phootwork/workflows/Tests/badge.svg) 4 | [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/phootwork/phootwork/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/phootwork/phootwork/?branch=master) 5 | [![Code Coverage](https://scrutinizer-ci.com/g/phootwork/phootwork/badges/coverage.png?b=master)](https://scrutinizer-ci.com/g/phootwork/phootwork/?branch=master) 6 | [![License](https://img.shields.io/github/license/phootwork/collection.svg?style=flat-square)](https://packagist.org/packages/phootwork/collection) 7 | [![Latest Stable Version](https://img.shields.io/packagist/v/phootwork/collection.svg?style=flat-square)](https://packagist.org/packages/phootwork/collection) 8 | [![Total Downloads](https://img.shields.io/packagist/dt/phootwork/collection.svg?style=flat-square&colorB=007ec6)](https://packagist.org/packages/phootwork/collection) 9 | 10 | PHP Collections library which contains ArrayList, Set, Map, Queue & Stack. 11 | 12 | ## Goals 13 | 14 | - Provide collections for php 15 | - Inspired by java `java.util.Collection` 16 | - Functional sugar (map, filter, reduce, ...) 17 | 18 | ## Installation 19 | 20 | Installation via composer: 21 | 22 | ``` 23 | composer require phootwork/collection 24 | ``` 25 | 26 | ## Documentation 27 | 28 | [https://phootwork.github.io/collection](https://phootwork.github.io/collection) 29 | 30 | ## Running tests 31 | 32 | This package is a part of the Phootwork library. In order to run the test suite, you have to download the full library. 33 | 34 | ``` 35 | git clone https://github.com/phootwork/phootwork 36 | ``` 37 | Then install the dependencies via composer: 38 | 39 | ``` 40 | composer install 41 | ``` 42 | Now, run the *collection* test suite: 43 | 44 | ``` 45 | vendor/bin/phpunit --testsuite collection 46 | ``` 47 | If you want to run the whole library tests, simply run: 48 | 49 | ``` 50 | vendor/bin/phpunit 51 | ``` 52 | 53 | ## Contact 54 | 55 | Report issues at the github [Issue Tracker](https://github.com/phootwork/phootwork/issues). 56 | 57 | ## Changelog 58 | 59 | Refer to [Releases](https://github.com/phootwork/phootwork/releases) 60 | -------------------------------------------------------------------------------- /Set.php: -------------------------------------------------------------------------------- 1 | add(...$collection); 27 | } 28 | 29 | /** 30 | * Adds an element to that set 31 | * 32 | * @param mixed ...$elements 33 | * 34 | * @return $this 35 | */ 36 | public function add(mixed ...$elements): self { 37 | /** @var mixed $element */ 38 | foreach ($elements as $element) { 39 | if (!in_array($element, $this->array, true)) { 40 | $this->array[$this->size()] = $element; 41 | } 42 | } 43 | 44 | return $this; 45 | } 46 | } 47 | -------------------------------------------------------------------------------- /Stack.php: -------------------------------------------------------------------------------- 1 | push(...$collection); 32 | } 33 | 34 | /** 35 | * Pushes an element onto the stack 36 | * 37 | * @param mixed ...$elements 38 | * 39 | * @return $this 40 | */ 41 | public function push(mixed ...$elements): self { 42 | array_push($this->array, ...$elements); 43 | 44 | return $this; 45 | } 46 | 47 | /** 48 | * Returns the element at the head or null if the stack is empty but doesn't remove that element 49 | * 50 | * @return mixed 51 | */ 52 | public function peek(): mixed { 53 | if ($this->size() > 0) { 54 | return $this->array[$this->size() - 1]; 55 | } 56 | 57 | return null; 58 | } 59 | } 60 | -------------------------------------------------------------------------------- /composer.json: -------------------------------------------------------------------------------- 1 | { 2 | "name" : "phootwork/collection", 3 | "type" : "library", 4 | "description" : "The phootwork library fills gaps in the php language and provides better solutions than the existing ones php offers.", 5 | "authors" : [{ 6 | "name" : "Thomas Gossmann", 7 | "homepage" : "http://gos.si" 8 | } 9 | ], 10 | "license" : "MIT", 11 | "keywords" : [ 12 | "Text object", 13 | "Array object", 14 | "collection", 15 | "collections", 16 | "list", 17 | "set", 18 | "map", 19 | "queue", 20 | "stack", 21 | "xml", 22 | "json" 23 | ], 24 | "support" : { 25 | "issues" : "https://github.com/phootwork/phootwork/issues" 26 | }, 27 | "autoload" : { 28 | "psr-4" : { 29 | "phootwork\\collection\\" : "" 30 | } 31 | }, 32 | "require" : { 33 | "php" : ">=8.0", 34 | "phootwork/lang" : "^3.0" 35 | }, 36 | "homepage" : "https://phootwork.github.io/collection/" 37 | } 38 | --------------------------------------------------------------------------------