集合¶

概览¶

Phalcon\Support\Collection是一个面向对象的数组。它提供了速度，以及各种 PHP 接口的实现。这些是：

<?php

use Phalcon\Support\Collection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
    'year'   => 1987,
];

$collection = new Collection($data);

构造函数¶

您可以像构造 PHP 中的任何其他对象一样构造该对象。然而，构造函数接受一个可选参数，该参数将为您填充对象。array参数，它将为你填充对象。

<?php

use Phalcon\Support\Collection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
    'year'   => 1987,
];

$collection = new Collection($data);

大小写敏感性¶

在实例化对象时，可以指定第二个bool参数，它将控制对象中的键搜索。默认情况下$insensitive被设置为true，这使得集合中的搜索不区分大小写。将此值设置为false将以区分大小写的方式搜索元素。

<?php

use Phalcon\Support\Collection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
    'year'   => 1987,
];

$collection = new Collection($data, false);

echo $collection->has('COLORS'); // false

重用¶

您还可以通过重新填充来重用该组件。Phalcon\Support\Collection暴露了clear()和init()方法，它们将分别清除并重新填充内部数组，

<?php

use Phalcon\Support\Collection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
    'year'   => 1987,
];

$collection = new Collection($data);

echo $collection->count(); // 2

$data = [
    'year' => 1987,
];

$collection->clear();
$collection->init($data);

echo $collection->count(); // 1

获取¶

如上所述，Phalcon\Support\Collection实现了几个接口，以使该组件尽可能灵活。可以通过以下方式检索存储在元素中的数据：- 属性 -__get()- 基于数组的获取 ($collection[$element]) -offsetGet() - get()

最快的方法是使用属性语法：

<?php

use Phalcon\Support\Collection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
    'year'   => 1987,
];

$collection = new Collection($data);

echo $collection->year;                    // 1987

你可以使用__get($element)但是不建议这样做，因为它比属性语法慢得多。同样的规则适用于offsetGet

echo $collection->__get('year');           // 1987
echo $collection['year'];                  // 1987
echo $collection->offsetGet('year');       // 1987
echo $collection->get('year', 1987, true); // 1987

public function get(
    string $element, 
    mixed $defaultValue = null, 
    string $cast = null
):  mixed

使用get()提供了三个参数。$key是我们要检索的元素的键

如果$defaultValue如果已设置，则会在未设置$key或$key已设置且其值为null

The cast接受定义返回值将被转换为何种类型的字符串。可用的值有：

array
bool
boolean
double
float
int
integer
null
object
string

集合对象还提供了两个额外的 gettergetKeys和getValues getKeys( bool $insensitive = true )返回集合中内部存储的所有键。默认情况下，它将以不区分大小写的方式返回键，即全部小写。如果在调用中传递了false，它将精确地返回存储的键。getValues返回内部集合中存储的值。

是否存在¶

要检查集合中是否存在某个元素，可以使用以下方法：-isset()在属性上 -__isset()- 基于数组的 isset (isset($coollection[$element])) -offsetExists() - has()

最快的方法是使用属性语法：

<?php

use Phalcon\Support\Collection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
    'year'   => 1987,
];

$collection = new Collection($data);

echo isset($collection->year); // true

你可以使用__isset(element)但是不建议这样做，因为它比属性语法慢得多。同样的规则适用于offsetExists

echo $collection->__isset('year');        // true
echo isset($collection['year']);          // true
echo $collection->offsetExists('year');   // true
echo $collection->has('year', true);      // true

public function has(string $element):  bool

设置¶

要在集合中设置一个元素，可以使用以下方法：- 将值赋给属性 -__set()- 基于数组的赋值 -offsetSet() - set()

最快的方法是使用属性语法：

<?php

use Phalcon\Support\Collection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
];

$collection = new Collection($data);

$collection->year = 1987;

你可以使用__set($element, $value)但是不建议这样做，因为它比属性语法慢得多。同样的规则适用于offsetSet

$collection->__set('year', 1987);
$collection['year'] = 1987;
$collection->offsetSet('year', 1987);
$collection->set('year', 1987);

移除¶

要从集合中移除一个元素，可以使用以下方法：- unset 属性 -__unset()- 基于数组的 unset -offsetUnset() - remove()

最快的方法是使用属性语法：

<?php

use Phalcon\Support\Collection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
];

$collection = new Collection($data);

unset($collection->year);

你可以使用__unset($element)但是不建议这样做，因为它比属性语法慢得多。同样的规则适用于offsetUnset

$collection->__unset('year');
unset($collection['year']);
$collection->offsetUnset('year');
$collection->remove('year');

public function remove(string $element):  void

迭代¶

由于集合对象实现了\IteratorAggregate，您可以轻松地遍历该对象。方法getIterator()返回一个ArrayIterator()对象

<?php

use Phalcon\Support\Collection;

$data = [
   'red',
   'green',
   'blue'
];

$collection = new Collection($data);

foreach ($collection as $key => $value) {
    echo $key . ' - ' . $value . PHP_EOL;
}

计数¶

对\Countable接口的实现暴露了count()方法，该方法存储集合中的元素数量。

<?php

use Phalcon\Support\Collection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
    'year'   => 1987,
];

$collection = new Collection($data);

echo $collection->count();    // 2

序列化¶

The \Serializable和\JsonSerializable接口暴露了允许您序列化和反序列化对象的方法。serialize()和unserialize()使用 PHP 的serialize和unserialize函数。jsonSerialize()返回一个可用于序列化的数组json_encode来序列化对象。

<?php

use Phalcon\Support\Collection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
    'year'   => 1987,
];

$collection = new Collection($data);

echo $collection->serialize();    
// a:2:{s:6:"colors";a:3:{i:0;s:3:"red";
//  i:1;s:5:"green";i:2;s:4:"blue";}s:4:"year";i:1987;}

$serialized = 'a:2:{s:6:"colors";a:3:{i:0;s:3:"red";'
    . 'i:1;s:5:"green";i:2;s:4:"blue";}s:4:"year";i:1987;}';
$collection->unserialize($serialized);

echo $collection->jsonSerialize(); // $data

转换¶

Phalcon\Support\Collection还暴露了两个转换方法：toArray()和toJson(int $options). toArray()返回作为数组转换的对象。此方法返回与jsonSerialize().

<?php

use Phalcon\Support\Collection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
    'year'   => 1987,
];

$collection = new Collection($data);

echo $collection->toArray();  // $data

toJson(int $options)返回对象的 JSON 表示形式。它内部使用json_encode并接受一个表示标志的参数json_encode接受。默认情况下，选项设置为 79，(RFC4327) 其含义为：

JSON_HEX_TAG
JSON_HEX_APOS
JSON_HEX_AMP
JSON_HEX_QUOT
JSON_UNESCAPED_SLASHES

您可以根据需要向该方法传递任何有效的标志。

<?php

use Phalcon\Support\Collection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
    'year'   => 1987,
];

$collection = new Collection($data);

echo $collection->toJson();    // ["red","green","blue"],"year":1987}

echo $collection->toJson(74 + JSON_PRETTY_PRINT);
/**
{
    "colors": [
        "red",
        "green",
        "blue"
    ],
    "year": 1987
}
*/

只读集合¶

Phalcon 还提供了一个可以以只读方式使用的组件。Phalcon\Support\Collection\ReadOnlyCollection可以作为您应用程序中的集合使用，只能用初始数据填充，但不允许在应用程序中更改其内容。

注意

该类已从ReadOnly重命名，以避免与 PHP 8.x 的保留字冲突。

<?php

use Phalcon\Support\Collection\ReadOnlyCollection;

$data = [
    'colors' => [
        'red',
        'green',
        'blue',
    ],
    'year'   => 1987,
];

$collection = new ReadOnly($data);

echo $collection->toJson();    // ["red","green","blue"],"year":1987}

$collection->set('colors', ['red']); // Exception

自定义对象¶

Phalcon 允许开发人员定义自己的集合对象。这些对象必须实现Phalcon\Support\Collection\CollectionInterface:

<?php

namespace MyApp;

use Phalcon\Support\Collection\CollectionInterface

class MyCollection implements CollectionInterface
{
    public function __get(string $element): mixed;

    public function __isset(string $element): bool;

    public function __set(string $element, mixed $value): void;

    public function __unset(string $element): void;

    public function clear(): void;

    public function get(
        string $element, 
        mixed $defaultValue = null, 
        string $cast = null
    ): mixed;

    public function getKeys(bool $insensitive = true): array;

    public function getValues(): array;

    public function has(string $element): bool;

    public function init(array $data = []): void;

    public function remove(string $element): void;

    public function set(string $element, var $value): void;

    public function toArray(): array;

    public function toJson(int $options = 79): string;
}