README

此包为原始类型提供 全功能集合，并提供了用于构建自己的强类型集合的泛型类。每个集合都有链式方法来执行遍历、过滤和投影操作。

示例

IntCollection::fromArray([0, 1, 2, 3, 4, 5, 6, 7, 8, 9])
    ->where(fn($n) => $n > 4)
    ->append(10)
    ->select(static fn($n) => $n * 10)
    ->forEach(static fn(int $n) => var_dump($n));

// Outputs:
//   int(50)
//   int(60)
//   int(70)
//   int(80)
//   int(90)
//   int(100)

章节

可用集合
- 原始类型集合
- 类集合
基本用法
- 构造函数
- 修改集合

安装

此包需要 PHP 7.4+

将其作为Composer依赖项添加

$ composer require mediagone/types-collections

1. 可用集合

原始类型集合

Mediagone\Types\Collections\Types 命名空间为PHP的所有原始类型提供强类型集合

ArrayCollection: 只能包含PHP array值的强类型集合。
BoolCollection: 只能包含PHP boolean值的强类型集合。
CallableCollection: 只能包含PHP callable值的强类型集合。
FloatCollection: 只能包含PHP float值的强类型集合。
IntCollection: 只能包含PHP integer值的强类型集合。
MixedCollection: 只能包含PHP mixed值的强类型集合。
ObjectCollection: 只能包含PHP object值的强类型集合。
ResourceCollection: 只能包含PHP resource值的强类型集合。
StringCollection: 只能包含PHP string值的强类型集合。

类集合

该库还提供了一个抽象类，可以轻松构建强类型类集合。

首先创建一个继承自 Mediagone\Types\Collections\Types\ClassCollection 的类并实现 classFqcn 方法

use App\Foo;
use Mediagone\Types\Collections\ClassCollection;

class FooCollection extends ClassCollection
{
    protected static function classFqcn() : string
    {
        return Foo::class;
    }
}

如果你使用的是静态分析工具，你必须使用以下简单注解指定泛型基集合的类型

/*
 * @extends ClassCollection<Foo>
 */
class FooCollection extends ClassCollection
{

然后...就这些！你的自定义集合现在只接受Foo实例。

2. 基本用法

构造函数

空集合

您可以使用 new 静态工厂方法创建一个空集合

$collection = StringCollection::new();

从数组创建

您还可以使用 fromArray 初始化任何集合，并可以使用 toArray 方法将项目作为PHP数组检索，例如

$collection = StringCollection::fromArray(['item1', 'item2', '3']);
var_dump($collection->toArray());
// Outputs:
//   array(3) {
//     [0] => string(5) "item1"
//     [1] => string(5) "item2"
//     [2] => string(1) "3"
//   }

如果将无效项添加到集合中，则强类型集合会抛出错误

// Throws a TypeError exception because this collection accepts only integer instances
$collection = IntCollection::fromArray([1, 2, 'invalid item']);

从重复值创建

您还可以使用 fromRepeatedValue 使用初始重复值创建集合

$collection = StringCollection::fromRepeatedValue('something', 3);
var_dump($collection->toArray());
// Outputs:
//   array(3) {
//     [0] => string(9) "something"
//     [1] => string(9) "something"
//     [2] => string(9) "something"
//   }

其他构造函数

某些集合实现了与底层类型相关的特定静态工厂方法（请参阅每个类以发现特定可用的工厂），例如在 IntCollection 类中

$collection = IntCollection::fromRange(2, 5);
var_dump($collection->toArray());
// Outputs:
//   array(5) {
//     [0] => int(2)
//     [1] => int(3)
//     [2] => int(4)
//     [3] => int(5)
//   }

修改集合

您可以使用 append 或 prepend 方法在集合初始化后添加新元素

$collection = StringCollection::fromArray(['item1', 'item2']);

// Add a value at the end of the collection
$collection->append('item3');

// Add a value at the start of the collection
$collection->prepend('item0');

var_dump($collection->toArray());
// Outputs:
//   array(4) {
//     [0] => string(5) "item0"
//     [1] => string(5) "item1"
//     [2] => string(5) "item2"
//     [3] => string(5) "item3"
//   }

注意：项目索引始终从0开始，即使在插入、删除或重新排序项目之后。

但是，基本集合类提供了许多更有用的方法

转换方法
- toArray: 返回集合的项目作为数组。
- toCollection: 将集合转换为新的集合类型，所有项都必须在目标集合中有效。
元素方法
- contains: 确定集合是否包含指定的项。
- append: 将项添加到集合的末尾。
- prepend: 将项添加到集合的开始。
- concat: 将一个集合合并到当前集合的项中。
- remove: 从集合中删除项。
- first: 返回集合的第一个项。
- firstOrNull: 返回集合的第一个项（满足可选条件）或null如果未找到此类项。
- firstOrDefault: 返回集合的第一个项（满足可选条件）或未找到此类项时的默认值。
- last: 返回集合的最后一个项。
- lastOrNull: 返回集合的最后一个项（满足可选条件）或未找到此类项时的null。
- lastOrDefault: 返回集合的最后一个项（满足可选条件）或未找到此类项时的默认值。
- single: 返回集合的唯一项或如果存在多个项则抛出异常。
- singleOrDefault: 返回集合的唯一项或如果存在多个项则抛出异常。
- random: 返回集合的唯一项或如果存在多个项则抛出异常。
分区方法
- skip: 跳过集合中指定数量的项，然后返回剩余的项。
- skipLast: 返回一个新的集合，该集合包含从源集合中省略了最后count个项的源项。
- skipWhile: 当指定的条件为真时跳过集合中的项，然后返回剩余的项。
- take: 返回从集合开始的一定数量的连续项。
- takeLast: 返回一个新的集合，该集合包含源的最后count个项。
- takeWhile: 当指定的条件为真时返回集合中的项。
- distinct: 从集合中删除重复项。
- distinctBy: 根据指定的键选择函数从集合中删除重复项。
- where: 根据谓词过滤集合项。
- except: 计算集合的差集。
- exceptBy: 根据指定的键选择函数计算两个序列的集合差。
- intersect: 计算两个集合的集合交集。
- intersectBy: 根据指定的键选择函数计算两个序列的集合差。
排序方法
- shuffle: 随机化集合中项的顺序。
- reverse: 反转集合中项的顺序。
- sort: 根据键对集合的项进行升序排序。
- sortDescending: 根据键对集合的项进行降序排序。
- sortBy: 根据键对集合的项进行升序排序。
- sortByDescending: 根据键对集合的项进行降序排序。
聚合方法
- count: 返回集合中的项数。
- min: 返回集合的最小值。
- max: 返回集合的最大值。
- average: 计算集合值的平均值。
- sum: 计算数值集合的总和。
- aggregate: 对序列应用累加器函数。
投影方法
- chunk: 将集合的项分割为指定大小的块。
- select：将集合的每个元素转换成新的形式，并返回包含转换后元素的新数组。
- selectMany：将集合的每个元素转换成集合，并将结果集合合并成一个集合。
- groupBy：根据指定的键选择函数对集合的元素进行分组。
- join：根据匹配的键关联两个集合的元素。
量词方法
- all：确定集合中的所有元素是否满足某个条件。
- any：确定集合中是否包含任何元素。
遍历方法
- forEach：将回调函数应用到集合的每个元素上。

注意：所有集合都实现了 JsonSerialize 和 ArrayIterator 接口。集合还实现了 ArrayAccess 接口，以便可以通过标准数组语法 $collection[$i] 访问元素，但是 只能访问 元素，不能设置或取消设置。

许可证

类型集合 使用 MIT 许可证。请参阅 LICENSE 文件。

mediagone / types-collections

维护者

详细信息