集合 collection

Testing Is Documentation

tests/Collection/CollectionTest.php集合 collection - 图1

集合 collection 提供了一些实用方法，数据库查询的数据列表也会转换为集合数据类型。

Uses

  1. <?php
  3. use JsonSerializable;
  4. use Leevel\Collection\Collection;
  5. use Leevel\Support\IArray;
  6. use Leevel\Support\IJson;
  7. use stdClass;

基本使用

集合实现了 \IteratorAggregate 可以像普通数组一样遍历，也实现了 \ArrayAccess 接口，可以当做普通数组一样使用。

  1. public function testBaseUse(): void
  2. {
  3.     $data = [
  4.         'hello', 'world', 'foo', 'bar',
  5.     ];
  7.     $collection = new Collection($data);
  9.     foreach ($collection as $key => $val) {
  10.         switch ($key) {
  11.             case 0:
  12.                 $this->assertSame($val, 'hello');
  14.                 break;
  15.             case 1:
  16.                 $this->assertSame($val, 'world');
  18.                 break;
  19.             case 2:
  20.                 $this->assertSame($val, 'foo');
  22.                 break;
  23.             case 3:
  24.                 $this->assertSame($val, 'bar');
  26.                 break;
  27.         }
  28.     }
  30.     $this->assertSame($collection[0], 'hello');
  31.     $this->assertSame($collection[1], 'world');
  32.     $this->assertSame($collection[2], 'foo');
  33.     $this->assertSame($collection[3], 'bar');
  34.     $this->assertTrue(isset($collection[0]));
  35.     $this->assertTrue(isset($collection[1]));
  36.     $this->assertTrue(isset($collection[2]));
  37.     $this->assertTrue(isset($collection[3]));
  38.     $this->assertFalse(isset($collection[4]));
  39. }

静态方法 make 创建集合

可以使用 make 方法创建一个集合对象。

  1. public function testMake(): void
  2. {
  3.     $data = [
  4.         'hello', 'world', 'foo', 'bar',
  5.     ];
  7.     $collection = Collection::make($data);
  9.     foreach ($collection as $key => $val) {
  10.         switch ($key) {
  11.             case 0:
  12.                 $this->assertSame($val, 'hello');
  14.                 break;
  15.             case 1:
  16.                 $this->assertSame($val, 'world');
  18.                 break;
  19.             case 2:
  20.                 $this->assertSame($val, 'foo');
  22.                 break;
  23.             case 3:
  24.                 $this->assertSame($val, 'bar');
  26.                 break;
  27.         }
  28.     }
  30.     $this->assertSame($collection[0], 'hello');
  31.     $this->assertSame($collection[1], 'world');
  32.     $this->assertSame($collection[2], 'foo');
  33.     $this->assertSame($collection[3], 'bar');
  34.     $this->assertTrue(isset($collection[0]));
  35.     $this->assertTrue(isset($collection[1]));
  36.     $this->assertTrue(isset($collection[2]));
  37.     $this->assertTrue(isset($collection[3]));
  38.     $this->assertFalse(isset($collection[4]));
  39. }

集合支持迭代器

集合 collection 是一个标准的迭代器，支持迭代器的用法。

  1. public function testIterator(): void
  2. {
  3.     $data = [
  4.         'hello', 'world', 'foo', 'bar',
  5.     ];
  7.     $collection = new Collection($data);
  9.     $this->assertSame('hello', $collection->current());
  10.     $this->assertSame(0, $collection->key());
  12.     $this->assertNull($collection->next());
  14.     $this->assertSame('world', $collection->current());
  15.     $this->assertSame(1, $collection->key());
  17.     $this->assertNull($collection->next());
  18.     $this->assertNull($collection->next());
  20.     $this->assertSame('bar', $collection->current());
  21.     $this->assertSame(3, $collection->key());
  23.     $collection->next();
  25.     $this->assertFalse($collection->current());
  26.     $this->assertNull($collection->key());
  28.     $collection->rewind();
  29.     $this->assertSame(0, $collection->key());
  30.     $this->assertSame('hello', $collection->current());
  31. }

集合可统计

集合实现了 \Countable 可以像普通数组一样统计元素的个数。

  1. public function testCountable(): void
  2. {
  3.     $data = [
  4.         'hello', 'world', 'foo', 'bar',
  5.     ];
  7.     $collection = new Collection($data);
  9.     $this->assertCount(4, $collection);
  10. }

集合数据支持实现 \Leevel\Support\IArray 的对象

对象实现了 \Leevel\Support\IArray 可以转化为集合数据。

例子

  1. namespace Tests\Collection;
  3. class TestArray implements IArray
  4. {
  5.     public function toArray(): array
  6.     {
  7.         return [
  8.             'hello',
  9.             'world',
  10.         ];
  11.     }
  12. }

实现了 \Leevel\Support\IArray 的对象的方法 toArray 返回集合的数据。

  1. public function testGetArrayElements2(): void
  2. {
  3.     $data = [
  4.         'hello',
  5.         'world',
  6.     ];
  8.     $collection = new Collection(new TestArray());
  10.     $this->assertSame($collection->toArray(), $data);
  11. }

集合数据支持实现 \Leevel\Support\IJson 的对象

对象实现了 \Leevel\Support\IJson 可以转化为集合数据。

例子

  1. namespace Tests\Collection;
  3. class TestJson implements IJson
  4. {
  5.     public function toJson(?int $option = null): string
  6.     {
  7.         if (null === $option) {
  8.             $option = JSON_UNESCAPED_UNICODE;
  9.         }
  11.         return json_encode([
  12.             'hello',
  13.             'world',
  14.         ], $option);
  15.     }
  16. }

实现了 \Leevel\Support\IJson 的对象的方法 toJson 返回集合的数据。

  1. public function testGetArrayElements3(): void
  2. {
  3.     $data = [
  4.         'hello',
  5.         'world',
  6.     ];
  8.     $collection = new Collection(new TestJson());
  10.     $this->assertSame($collection->toArray(), $data);
  11. }

集合数据支持实现 \JsonSerializable 的对象

对象实现了 \JsonSerializable 可以转化为集合数据。

例子

  1. namespace Tests\Collection;
  3. class TestJsonSerializable implements JsonSerializable
  4. {
  5.     public function jsonSerialize()
  6.     {
  7.         return [
  8.             'hello',
  9.             'world',
  10.         ];
  11.     }
  12. }

实现了 \JsonSerializable 的对象的方法 jsonSerialize 返回集合的数据。

  1. public function testGetArrayElements4(): void
  2. {
  3.     $data = [
  4.         'hello',
  5.         'world',
  6.     ];
  8.     $collection = new Collection(new TestJsonSerializable());
  10.     $this->assertSame($collection->toArray(), $data);
  11. }

集合数据支持普通数据转化为数组

  1. public function testGetArrayElements5(): void
  2. {
  3.     $data = [
  4.         'hello',
  5.     ];
  7.     $collection = new Collection('hello');
  9.     $this->assertSame($collection->toArray(), $data);
  10. }

集合数据支持 \stdClass 的对象

对象为 \stdClass 可以转化为集合数据。

\stdClass 的对象返回转化为数组作为集合的数据。

  1. public function testGetArrayElementsWithStdClass(): void
  2. {
  3.     $data = [
  4.         'hello' => 'world',
  5.         'foo'   => 'bar',
  6.     ];
  8.     $std = new stdClass();
  9.     $std->hello = 'world';
  10.     $std->foo = 'bar';
  12.     $collection = new Collection($std);
  14.     $this->assertSame($collection->toArray(), $data);
  15. }

集合数据支持类型验证

比如下面的数据类型为 string，只有字符串类型才能加入集合。

  1. public function testTypeValidate(): void
  2. {
  3.     $data = [
  4.         'hello',
  5.         'world',
  6.     ];
  8.     $collection = new Collection($data, ['string']);
  9.     $this->assertSame($collection->toArray(), $data);
  10.     $this->assertSame(['string'], $collection->getType());
  11. }

集合数据支持类型验证不符合规则示例

比如下面的数据类型为 int，字符串类型就会抛出异常。

  1. public function testTypeValidateException(): void
  2. {
  3.     $this->expectException(\InvalidArgumentException::class);
  4.     $this->expectExceptionMessage(
  5.         'Collection type int validation failed.'
  6.     );
  8.     $data = [
  9.         'hello',
  10.         'world',
  11.     ];
  13.     new Collection($data, ['int']);
  14. }

each 集合数据遍历元素项

使用闭包进行遍历，闭包的第一个参数为元素值，第二为元素键。

  1. public function testEach(): void
  2. {
  3.     $data = [
  4.         'hello',
  5.         'world',
  6.     ];
  8.     $collection = new Collection($data);
  10.     $i = 0;
  11.     $collection->each(function ($item, $key) use (&$i) {
  12.         $this->assertSame($i, $key);
  14.         if (0 === $i) {
  15.             $this->assertSame($item, 'hello');
  16.         } else {
  17.             $this->assertSame($item, 'world');
  18.         }
  20.         $i++;
  21.     });
  22. }

each 集合数据遍历元素项支持中断

遍历元素项的时候返回 false 将会中断后续遍历操作。

  1. public function testEachAndBreak(): void
  2. {
  3.     $data = [
  4.         'hello',
  5.         'world',
  6.     ];
  8.     $collection = new Collection($data);
  10.     $i = 0;
  12.     $collection->each(function ($item, $key) use (&$i) {
  13.         $this->assertSame($i, $key);
  15.         if (0 === $i) {
  16.             $this->assertSame($item, 'hello');
  18.             return false;
  19.         }
  21.         $i++;
  22.     });
  24.     $this->assertSame($i, 0);
  25. }

toJson 集合数据支持 JSON 输出

集合实现了 \Leevel\Support\IJson 接口，可以通过方法 toJson 输出 JSON 字符串。

  1. public function testToJson(): void
  2. {
  3.     $data = [
  4.         'hello',
  5.         'world',
  6.     ];
  8.     $collection = new Collection($data);
  10.     $data = '["hello","world"]';
  12.     $this->assertSame($data, $collection->toJson());
  13. }

toJson 集合数据支持 JSON 输出默认不要编码 Unicode

JSON_UNESCAPED_UNICODE 可以让有中文的 JSON 字符串更加友好地输出。

  1. json_encode('中文', JSON_UNESCAPED_UNICODE);
  1. public function testToJsonWithCn(): void
  2. {
  3.     $data = [
  4.         '我',
  5.         '成都',
  6.     ];
  8.     $collection = new Collection($data);
  10.     $data = '["我","成都"]';
  12.     $this->assertSame($data, $collection->toJson());
  13. }

toJson 集合数据支持 JSON 输出

集合实现了 \JsonSerializable 接口，可以通过方法 toJson 输出 JSON 字符串。

  1. public function testJsonSerialize(): void
  2. {
  3.     $std = new stdClass();
  4.     $std->hello = 'world';
  5.     $std->foo = 'bar';
  7.     $data = [
  8.         new TestJsonSerializable(),
  9.         new TestArray(),
  10.         new TestJson(),
  11.         $std,
  12.         'foo',
  13.         'bar',
  14.     ];
  16.     $collection = new Collection($data);
  18.     $data = <<<'eot'
  19.         [
  20.             [
  21.                 "hello",
  22.                 "world"
  23.             ],
  24.             [
  25.                 "hello",
  26.                 "world"
  27.             ],
  28.             [
  29.                 "hello",
  30.                 "world"
  31.             ],
  32.             {
  33.                 "hello": "world",
  34.                 "foo": "bar"
  35.             },
  36.             "foo",
  37.             "bar"
  38.         ]
  39.         eot;
  41.     $this->assertSame(
  42.         $data,
  43.         $this->varJson(
  44.             $collection->jsonSerialize()
  45.         )
  46.     );
  47. }

__toString 集合数据可以转化为字符串

集合实现了 __toString 方法，可以强制转化为字符串。

  1. public function testGetSetString(): void
  2. {
  3.     $data = [
  4.         'hello' => 'world',
  5.         'foo'   => 'bar',
  6.     ];
  8.     $collection = new Collection($data);
  10.     $this->assertSame($collection->hello, 'world');
  11.     $this->assertSame($collection->foo, 'bar');
  12.     $collection->hello = 'new world';
  13.     $collection->foo = 'new bar';
  14.     $this->assertSame($collection->hello, 'new world');
  15.     $this->assertSame($collection->foo, 'new bar');
  16.     $this->assertSame((string) $collection, '{"hello":"new world","foo":"new bar"}');
  17. }