1<?php 2 3namespace Illuminate\Support; 4 5use Countable; 6use Illuminate\Contracts\Support\Arrayable; 7use Illuminate\Contracts\Support\Jsonable; 8use IteratorAggregate; 9use JsonSerializable; 10 11interface Enumerable extends Arrayable, Countable, IteratorAggregate, Jsonable, JsonSerializable 12{ 13 /** 14 * Create a new collection instance if the value isn't one already. 15 * 16 * @param mixed $items 17 * @return static 18 */ 19 public static function make($items = []); 20 21 /** 22 * Create a new instance by invoking the callback a given amount of times. 23 * 24 * @param int $number 25 * @param callable|null $callback 26 * @return static 27 */ 28 public static function times($number, callable $callback = null); 29 30 /** 31 * Create a collection with the given range. 32 * 33 * @param int $from 34 * @param int $to 35 * @return static 36 */ 37 public static function range($from, $to); 38 39 /** 40 * Wrap the given value in a collection if applicable. 41 * 42 * @param mixed $value 43 * @return static 44 */ 45 public static function wrap($value); 46 47 /** 48 * Get the underlying items from the given collection if applicable. 49 * 50 * @param array|static $value 51 * @return array 52 */ 53 public static function unwrap($value); 54 55 /** 56 * Create a new instance with no items. 57 * 58 * @return static 59 */ 60 public static function empty(); 61 62 /** 63 * Get all items in the enumerable. 64 * 65 * @return array 66 */ 67 public function all(); 68 69 /** 70 * Alias for the "avg" method. 71 * 72 * @param callable|string|null $callback 73 * @return mixed 74 */ 75 public function average($callback = null); 76 77 /** 78 * Get the median of a given key. 79 * 80 * @param string|array|null $key 81 * @return mixed 82 */ 83 public function median($key = null); 84 85 /** 86 * Get the mode of a given key. 87 * 88 * @param string|array|null $key 89 * @return array|null 90 */ 91 public function mode($key = null); 92 93 /** 94 * Collapse the items into a single enumerable. 95 * 96 * @return static 97 */ 98 public function collapse(); 99 100 /** 101 * Alias for the "contains" method. 102 * 103 * @param mixed $key 104 * @param mixed $operator 105 * @param mixed $value 106 * @return bool 107 */ 108 public function some($key, $operator = null, $value = null); 109 110 /** 111 * Determine if an item exists, using strict comparison. 112 * 113 * @param mixed $key 114 * @param mixed $value 115 * @return bool 116 */ 117 public function containsStrict($key, $value = null); 118 119 /** 120 * Get the average value of a given key. 121 * 122 * @param callable|string|null $callback 123 * @return mixed 124 */ 125 public function avg($callback = null); 126 127 /** 128 * Determine if an item exists in the enumerable. 129 * 130 * @param mixed $key 131 * @param mixed $operator 132 * @param mixed $value 133 * @return bool 134 */ 135 public function contains($key, $operator = null, $value = null); 136 137 /** 138 * Cross join with the given lists, returning all possible permutations. 139 * 140 * @param mixed ...$lists 141 * @return static 142 */ 143 public function crossJoin(...$lists); 144 145 /** 146 * Dump the collection and end the script. 147 * 148 * @param mixed ...$args 149 * @return void 150 */ 151 public function dd(...$args); 152 153 /** 154 * Dump the collection. 155 * 156 * @return $this 157 */ 158 public function dump(); 159 160 /** 161 * Get the items that are not present in the given items. 162 * 163 * @param mixed $items 164 * @return static 165 */ 166 public function diff($items); 167 168 /** 169 * Get the items that are not present in the given items, using the callback. 170 * 171 * @param mixed $items 172 * @param callable $callback 173 * @return static 174 */ 175 public function diffUsing($items, callable $callback); 176 177 /** 178 * Get the items whose keys and values are not present in the given items. 179 * 180 * @param mixed $items 181 * @return static 182 */ 183 public function diffAssoc($items); 184 185 /** 186 * Get the items whose keys and values are not present in the given items, using the callback. 187 * 188 * @param mixed $items 189 * @param callable $callback 190 * @return static 191 */ 192 public function diffAssocUsing($items, callable $callback); 193 194 /** 195 * Get the items whose keys are not present in the given items. 196 * 197 * @param mixed $items 198 * @return static 199 */ 200 public function diffKeys($items); 201 202 /** 203 * Get the items whose keys are not present in the given items, using the callback. 204 * 205 * @param mixed $items 206 * @param callable $callback 207 * @return static 208 */ 209 public function diffKeysUsing($items, callable $callback); 210 211 /** 212 * Retrieve duplicate items. 213 * 214 * @param callable|string|null $callback 215 * @param bool $strict 216 * @return static 217 */ 218 public function duplicates($callback = null, $strict = false); 219 220 /** 221 * Retrieve duplicate items using strict comparison. 222 * 223 * @param callable|string|null $callback 224 * @return static 225 */ 226 public function duplicatesStrict($callback = null); 227 228 /** 229 * Execute a callback over each item. 230 * 231 * @param callable $callback 232 * @return $this 233 */ 234 public function each(callable $callback); 235 236 /** 237 * Execute a callback over each nested chunk of items. 238 * 239 * @param callable $callback 240 * @return static 241 */ 242 public function eachSpread(callable $callback); 243 244 /** 245 * Determine if all items pass the given truth test. 246 * 247 * @param string|callable $key 248 * @param mixed $operator 249 * @param mixed $value 250 * @return bool 251 */ 252 public function every($key, $operator = null, $value = null); 253 254 /** 255 * Get all items except for those with the specified keys. 256 * 257 * @param mixed $keys 258 * @return static 259 */ 260 public function except($keys); 261 262 /** 263 * Run a filter over each of the items. 264 * 265 * @param callable|null $callback 266 * @return static 267 */ 268 public function filter(callable $callback = null); 269 270 /** 271 * Apply the callback if the value is truthy. 272 * 273 * @param bool $value 274 * @param callable $callback 275 * @param callable|null $default 276 * @return static|mixed 277 */ 278 public function when($value, callable $callback, callable $default = null); 279 280 /** 281 * Apply the callback if the collection is empty. 282 * 283 * @param callable $callback 284 * @param callable|null $default 285 * @return static|mixed 286 */ 287 public function whenEmpty(callable $callback, callable $default = null); 288 289 /** 290 * Apply the callback if the collection is not empty. 291 * 292 * @param callable $callback 293 * @param callable|null $default 294 * @return static|mixed 295 */ 296 public function whenNotEmpty(callable $callback, callable $default = null); 297 298 /** 299 * Apply the callback if the value is falsy. 300 * 301 * @param bool $value 302 * @param callable $callback 303 * @param callable|null $default 304 * @return static|mixed 305 */ 306 public function unless($value, callable $callback, callable $default = null); 307 308 /** 309 * Apply the callback unless the collection is empty. 310 * 311 * @param callable $callback 312 * @param callable|null $default 313 * @return static|mixed 314 */ 315 public function unlessEmpty(callable $callback, callable $default = null); 316 317 /** 318 * Apply the callback unless the collection is not empty. 319 * 320 * @param callable $callback 321 * @param callable|null $default 322 * @return static|mixed 323 */ 324 public function unlessNotEmpty(callable $callback, callable $default = null); 325 326 /** 327 * Filter items by the given key value pair. 328 * 329 * @param string $key 330 * @param mixed $operator 331 * @param mixed $value 332 * @return static 333 */ 334 public function where($key, $operator = null, $value = null); 335 336 /** 337 * Filter items where the value for the given key is null. 338 * 339 * @param string|null $key 340 * @return static 341 */ 342 public function whereNull($key = null); 343 344 /** 345 * Filter items where the value for the given key is not null. 346 * 347 * @param string|null $key 348 * @return static 349 */ 350 public function whereNotNull($key = null); 351 352 /** 353 * Filter items by the given key value pair using strict comparison. 354 * 355 * @param string $key 356 * @param mixed $value 357 * @return static 358 */ 359 public function whereStrict($key, $value); 360 361 /** 362 * Filter items by the given key value pair. 363 * 364 * @param string $key 365 * @param mixed $values 366 * @param bool $strict 367 * @return static 368 */ 369 public function whereIn($key, $values, $strict = false); 370 371 /** 372 * Filter items by the given key value pair using strict comparison. 373 * 374 * @param string $key 375 * @param mixed $values 376 * @return static 377 */ 378 public function whereInStrict($key, $values); 379 380 /** 381 * Filter items such that the value of the given key is between the given values. 382 * 383 * @param string $key 384 * @param array $values 385 * @return static 386 */ 387 public function whereBetween($key, $values); 388 389 /** 390 * Filter items such that the value of the given key is not between the given values. 391 * 392 * @param string $key 393 * @param array $values 394 * @return static 395 */ 396 public function whereNotBetween($key, $values); 397 398 /** 399 * Filter items by the given key value pair. 400 * 401 * @param string $key 402 * @param mixed $values 403 * @param bool $strict 404 * @return static 405 */ 406 public function whereNotIn($key, $values, $strict = false); 407 408 /** 409 * Filter items by the given key value pair using strict comparison. 410 * 411 * @param string $key 412 * @param mixed $values 413 * @return static 414 */ 415 public function whereNotInStrict($key, $values); 416 417 /** 418 * Filter the items, removing any items that don't match the given type(s). 419 * 420 * @param string|string[] $type 421 * @return static 422 */ 423 public function whereInstanceOf($type); 424 425 /** 426 * Get the first item from the enumerable passing the given truth test. 427 * 428 * @param callable|null $callback 429 * @param mixed $default 430 * @return mixed 431 */ 432 public function first(callable $callback = null, $default = null); 433 434 /** 435 * Get the first item by the given key value pair. 436 * 437 * @param string $key 438 * @param mixed $operator 439 * @param mixed $value 440 * @return mixed 441 */ 442 public function firstWhere($key, $operator = null, $value = null); 443 444 /** 445 * Get a flattened array of the items in the collection. 446 * 447 * @param int $depth 448 * @return static 449 */ 450 public function flatten($depth = INF); 451 452 /** 453 * Flip the values with their keys. 454 * 455 * @return static 456 */ 457 public function flip(); 458 459 /** 460 * Get an item from the collection by key. 461 * 462 * @param mixed $key 463 * @param mixed $default 464 * @return mixed 465 */ 466 public function get($key, $default = null); 467 468 /** 469 * Group an associative array by a field or using a callback. 470 * 471 * @param array|callable|string $groupBy 472 * @param bool $preserveKeys 473 * @return static 474 */ 475 public function groupBy($groupBy, $preserveKeys = false); 476 477 /** 478 * Key an associative array by a field or using a callback. 479 * 480 * @param callable|string $keyBy 481 * @return static 482 */ 483 public function keyBy($keyBy); 484 485 /** 486 * Determine if an item exists in the collection by key. 487 * 488 * @param mixed $key 489 * @return bool 490 */ 491 public function has($key); 492 493 /** 494 * Concatenate values of a given key as a string. 495 * 496 * @param string $value 497 * @param string|null $glue 498 * @return string 499 */ 500 public function implode($value, $glue = null); 501 502 /** 503 * Intersect the collection with the given items. 504 * 505 * @param mixed $items 506 * @return static 507 */ 508 public function intersect($items); 509 510 /** 511 * Intersect the collection with the given items by key. 512 * 513 * @param mixed $items 514 * @return static 515 */ 516 public function intersectByKeys($items); 517 518 /** 519 * Determine if the collection is empty or not. 520 * 521 * @return bool 522 */ 523 public function isEmpty(); 524 525 /** 526 * Determine if the collection is not empty. 527 * 528 * @return bool 529 */ 530 public function isNotEmpty(); 531 532 /** 533 * Join all items from the collection using a string. The final items can use a separate glue string. 534 * 535 * @param string $glue 536 * @param string $finalGlue 537 * @return string 538 */ 539 public function join($glue, $finalGlue = ''); 540 541 /** 542 * Get the keys of the collection items. 543 * 544 * @return static 545 */ 546 public function keys(); 547 548 /** 549 * Get the last item from the collection. 550 * 551 * @param callable|null $callback 552 * @param mixed $default 553 * @return mixed 554 */ 555 public function last(callable $callback = null, $default = null); 556 557 /** 558 * Run a map over each of the items. 559 * 560 * @param callable $callback 561 * @return static 562 */ 563 public function map(callable $callback); 564 565 /** 566 * Run a map over each nested chunk of items. 567 * 568 * @param callable $callback 569 * @return static 570 */ 571 public function mapSpread(callable $callback); 572 573 /** 574 * Run a dictionary map over the items. 575 * 576 * The callback should return an associative array with a single key/value pair. 577 * 578 * @param callable $callback 579 * @return static 580 */ 581 public function mapToDictionary(callable $callback); 582 583 /** 584 * Run a grouping map over the items. 585 * 586 * The callback should return an associative array with a single key/value pair. 587 * 588 * @param callable $callback 589 * @return static 590 */ 591 public function mapToGroups(callable $callback); 592 593 /** 594 * Run an associative map over each of the items. 595 * 596 * The callback should return an associative array with a single key/value pair. 597 * 598 * @param callable $callback 599 * @return static 600 */ 601 public function mapWithKeys(callable $callback); 602 603 /** 604 * Map a collection and flatten the result by a single level. 605 * 606 * @param callable $callback 607 * @return static 608 */ 609 public function flatMap(callable $callback); 610 611 /** 612 * Map the values into a new class. 613 * 614 * @param string $class 615 * @return static 616 */ 617 public function mapInto($class); 618 619 /** 620 * Merge the collection with the given items. 621 * 622 * @param mixed $items 623 * @return static 624 */ 625 public function merge($items); 626 627 /** 628 * Recursively merge the collection with the given items. 629 * 630 * @param mixed $items 631 * @return static 632 */ 633 public function mergeRecursive($items); 634 635 /** 636 * Create a collection by using this collection for keys and another for its values. 637 * 638 * @param mixed $values 639 * @return static 640 */ 641 public function combine($values); 642 643 /** 644 * Union the collection with the given items. 645 * 646 * @param mixed $items 647 * @return static 648 */ 649 public function union($items); 650 651 /** 652 * Get the min value of a given key. 653 * 654 * @param callable|string|null $callback 655 * @return mixed 656 */ 657 public function min($callback = null); 658 659 /** 660 * Get the max value of a given key. 661 * 662 * @param callable|string|null $callback 663 * @return mixed 664 */ 665 public function max($callback = null); 666 667 /** 668 * Create a new collection consisting of every n-th element. 669 * 670 * @param int $step 671 * @param int $offset 672 * @return static 673 */ 674 public function nth($step, $offset = 0); 675 676 /** 677 * Get the items with the specified keys. 678 * 679 * @param mixed $keys 680 * @return static 681 */ 682 public function only($keys); 683 684 /** 685 * "Paginate" the collection by slicing it into a smaller collection. 686 * 687 * @param int $page 688 * @param int $perPage 689 * @return static 690 */ 691 public function forPage($page, $perPage); 692 693 /** 694 * Partition the collection into two arrays using the given callback or key. 695 * 696 * @param callable|string $key 697 * @param mixed $operator 698 * @param mixed $value 699 * @return static 700 */ 701 public function partition($key, $operator = null, $value = null); 702 703 /** 704 * Push all of the given items onto the collection. 705 * 706 * @param iterable $source 707 * @return static 708 */ 709 public function concat($source); 710 711 /** 712 * Get one or a specified number of items randomly from the collection. 713 * 714 * @param int|null $number 715 * @return static|mixed 716 * 717 * @throws \InvalidArgumentException 718 */ 719 public function random($number = null); 720 721 /** 722 * Reduce the collection to a single value. 723 * 724 * @param callable $callback 725 * @param mixed $initial 726 * @return mixed 727 */ 728 public function reduce(callable $callback, $initial = null); 729 730 /** 731 * Replace the collection items with the given items. 732 * 733 * @param mixed $items 734 * @return static 735 */ 736 public function replace($items); 737 738 /** 739 * Recursively replace the collection items with the given items. 740 * 741 * @param mixed $items 742 * @return static 743 */ 744 public function replaceRecursive($items); 745 746 /** 747 * Reverse items order. 748 * 749 * @return static 750 */ 751 public function reverse(); 752 753 /** 754 * Search the collection for a given value and return the corresponding key if successful. 755 * 756 * @param mixed $value 757 * @param bool $strict 758 * @return mixed 759 */ 760 public function search($value, $strict = false); 761 762 /** 763 * Shuffle the items in the collection. 764 * 765 * @param int|null $seed 766 * @return static 767 */ 768 public function shuffle($seed = null); 769 770 /** 771 * Skip the first {$count} items. 772 * 773 * @param int $count 774 * @return static 775 */ 776 public function skip($count); 777 778 /** 779 * Skip items in the collection until the given condition is met. 780 * 781 * @param mixed $value 782 * @return static 783 */ 784 public function skipUntil($value); 785 786 /** 787 * Skip items in the collection while the given condition is met. 788 * 789 * @param mixed $value 790 * @return static 791 */ 792 public function skipWhile($value); 793 794 /** 795 * Get a slice of items from the enumerable. 796 * 797 * @param int $offset 798 * @param int|null $length 799 * @return static 800 */ 801 public function slice($offset, $length = null); 802 803 /** 804 * Split a collection into a certain number of groups. 805 * 806 * @param int $numberOfGroups 807 * @return static 808 */ 809 public function split($numberOfGroups); 810 811 /** 812 * Chunk the collection into chunks of the given size. 813 * 814 * @param int $size 815 * @return static 816 */ 817 public function chunk($size); 818 819 /** 820 * Chunk the collection into chunks with a callback. 821 * 822 * @param callable $callback 823 * @return static 824 */ 825 public function chunkWhile(callable $callback); 826 827 /** 828 * Sort through each item with a callback. 829 * 830 * @param callable|null|int $callback 831 * @return static 832 */ 833 public function sort($callback = null); 834 835 /** 836 * Sort items in descending order. 837 * 838 * @param int $options 839 * @return static 840 */ 841 public function sortDesc($options = SORT_REGULAR); 842 843 /** 844 * Sort the collection using the given callback. 845 * 846 * @param callable|string $callback 847 * @param int $options 848 * @param bool $descending 849 * @return static 850 */ 851 public function sortBy($callback, $options = SORT_REGULAR, $descending = false); 852 853 /** 854 * Sort the collection in descending order using the given callback. 855 * 856 * @param callable|string $callback 857 * @param int $options 858 * @return static 859 */ 860 public function sortByDesc($callback, $options = SORT_REGULAR); 861 862 /** 863 * Sort the collection keys. 864 * 865 * @param int $options 866 * @param bool $descending 867 * @return static 868 */ 869 public function sortKeys($options = SORT_REGULAR, $descending = false); 870 871 /** 872 * Sort the collection keys in descending order. 873 * 874 * @param int $options 875 * @return static 876 */ 877 public function sortKeysDesc($options = SORT_REGULAR); 878 879 /** 880 * Get the sum of the given values. 881 * 882 * @param callable|string|null $callback 883 * @return mixed 884 */ 885 public function sum($callback = null); 886 887 /** 888 * Take the first or last {$limit} items. 889 * 890 * @param int $limit 891 * @return static 892 */ 893 public function take($limit); 894 895 /** 896 * Take items in the collection until the given condition is met. 897 * 898 * @param mixed $value 899 * @return static 900 */ 901 public function takeUntil($value); 902 903 /** 904 * Take items in the collection while the given condition is met. 905 * 906 * @param mixed $value 907 * @return static 908 */ 909 public function takeWhile($value); 910 911 /** 912 * Pass the collection to the given callback and then return it. 913 * 914 * @param callable $callback 915 * @return $this 916 */ 917 public function tap(callable $callback); 918 919 /** 920 * Pass the enumerable to the given callback and return the result. 921 * 922 * @param callable $callback 923 * @return mixed 924 */ 925 public function pipe(callable $callback); 926 927 /** 928 * Get the values of a given key. 929 * 930 * @param string|array $value 931 * @param string|null $key 932 * @return static 933 */ 934 public function pluck($value, $key = null); 935 936 /** 937 * Create a collection of all elements that do not pass a given truth test. 938 * 939 * @param callable|mixed $callback 940 * @return static 941 */ 942 public function reject($callback = true); 943 944 /** 945 * Return only unique items from the collection array. 946 * 947 * @param string|callable|null $key 948 * @param bool $strict 949 * @return static 950 */ 951 public function unique($key = null, $strict = false); 952 953 /** 954 * Return only unique items from the collection array using strict comparison. 955 * 956 * @param string|callable|null $key 957 * @return static 958 */ 959 public function uniqueStrict($key = null); 960 961 /** 962 * Reset the keys on the underlying array. 963 * 964 * @return static 965 */ 966 public function values(); 967 968 /** 969 * Pad collection to the specified length with a value. 970 * 971 * @param int $size 972 * @param mixed $value 973 * @return static 974 */ 975 public function pad($size, $value); 976 977 /** 978 * Count the number of items in the collection using a given truth test. 979 * 980 * @param callable|null $callback 981 * @return static 982 */ 983 public function countBy($callback = null); 984 985 /** 986 * Zip the collection together with one or more arrays. 987 * 988 * e.g. new Collection([1, 2, 3])->zip([4, 5, 6]); 989 * => [[1, 4], [2, 5], [3, 6]] 990 * 991 * @param mixed ...$items 992 * @return static 993 */ 994 public function zip($items); 995 996 /** 997 * Collect the values into a collection. 998 * 999 * @return \Illuminate\Support\Collection 1000 */ 1001 public function collect(); 1002 1003 /** 1004 * Convert the collection to its string representation. 1005 * 1006 * @return string 1007 */ 1008 public function __toString(); 1009 1010 /** 1011 * Add a method to the list of proxied methods. 1012 * 1013 * @param string $method 1014 * @return void 1015 */ 1016 public static function proxy($method); 1017 1018 /** 1019 * Dynamically access collection proxies. 1020 * 1021 * @param string $key 1022 * @return mixed 1023 * 1024 * @throws \Exception 1025 */ 1026 public function __get($key); 1027} 1028