versatile collections
New Major Release
一个集合包，可以扩展以实现诸如依赖注入容器、用于容纳数据库记录的 RecordSet 对象、一袋 http cookie 或技术上可以循环且每个项目都可以使用数组访问的任何项目集合之类的东西-访问语法或对象属性语法。
你可以：
该包提供了可选的严格类型化的集合项目，并力求 100% 的单元测试覆盖率。
通过作曲家：（需要 PHP 7.4+ 或 PHP 8.0+）。
切换到3.X分支阅读3.X版本的文档。
切换到4.X分支阅读4.X版本的文档。
切换到5.x分支阅读5.x版本的文档。
切换到master分支阅读最新版本的文档。
composer require rotexsoft/versatile-collections
如果您只是想在集合中存储相同或不同类型的项目，您可以简单地使用GenericCollection类，如下所示：
<?php
use VersatileCollections GenericCollection ;
// items to be stored in your collection
$ item1 = [ ' yabadoo ' ]; // an array
$ item2 = function (){ echo ' Hello World! ' ; }; // a callable
$ item3 = 777.888 ; // a float
$ item4 = 777 ; // an int
$ item5 = new stdClass (); // an object
$ item6 = new ArrayObject ([]); // another object
$ item7 = tmpfile (); // a resource
$ item8 = true ; // a boolean
$ item9 = " true " ; // a string
// Technique 1: pass the items to the constructor of the collection class
$ collection = new VersatileCollections GenericCollection (
$ item1 , $ item2 , $ item3 , $ item4 , $ item5 , $ item6 , $ item7 , $ item8 , $ item9
);
// Technique 2: pass the items in an array using argument unpacking
// to the constructor of the collection class
$ collection = new GenericCollection (
...[ $ item1 , $ item2 , $ item3 , $ item4 , $ item5 , $ item6 , $ item7 , $ item8 , $ item9 ]
);
// Technique 3: pass the items in an iterable (such as an array) to the static makeNew helper method
// available in all collection classes
$ collection = GenericCollection:: makeNew (
[ $ item1 , $ item2 , $ item3 , $ item4 , $ item5 , $ item6 , $ item7 , $ item8 , $ item9 ]
);
// Technique 4: create an empty collection object and subsequently add each
// item to the collection via array assignment syntax or object
// property assignment syntax or using the appendItem($item),
// prependItem($item, $key=null), push($item) or put($key, $value)
// methods
$ collection = new GenericCollection (); // empty collection
// OR
$ collection = GenericCollection:: makeNew (); // empty collection
$ collection [] = $ item1 ; // array assignment syntax without key
// the item is automatically assigned
// the next available integer key. In
// this case 0
$ collection [] = $ item2 ; // array assignment syntax without key
// the next available integer key in this
// case is 1
$ collection [ ' some_key ' ] = $ item3 ; // array assignment syntax with specified key `some_key`
$ collection -> some_key = $ item4 ; // object property assignment syntax with specified property
// `some_key`. This will update $collection['some_key']
// changing its value from $item3 to $item4
$ collection -> appendItem ( $ item3 ) // same effect as:
-> appendItem ( $ item5 ); // $collection[] = $item3;
// $collection[] = $item5;
// Adds an item to the end of the collection
// You can chain the method calls
$ collection -> prependItem ( $ item6 , ' new_key ' ); // adds an item with the optional
// specified key to the front of
// collection.
// You can chain the method calls
$ collection -> push ( $ item7 ); // same effect as:
// $collection[] = $item7;
// Adds an item to the end of the collection
// You can chain the method calls
$ collection -> put ( ' eight_item ' , $ item8 ) // same effect as:
-> put ( ' ninth_item ' , $ item9 ); // $collection['eight_item'] = $item8;
// $collection['ninth_item'] = $item9;
// Adds an item with the specified key to
// the collection. If the specified key
// already exists in the collection the
// item previously associated with the
// key is overwritten with the new item.
// You can chain the method calls您还可以通过实现VersatileCollectionsCollectionInterface并在此类中使用VersatileCollectionsCollectionInterfaceImplementationTrait ，使应用程序中的任何类的行为与VersatileCollectionsGenericCollection完全相同。
如果您想强制执行严格类型，此包中提供了以下 Collection 类：
要实现仅包含特定类实例的对象（例如PDO ）的自定义集合，您的自定义集合类必须遵守以下要求：
您的自定义集合类必须实现VersatileCollectionsStrictlyTypedCollectionInterface当前包含以下方法：
$item是预期类型，则必须返回 true，否则返回 false您的自定义集合类应使用VersatileCollectionsStrictlyTypedCollectionInterfaceImplementationTrait （其中包含VersatileCollectionsStrictlyTypedCollectionInterface中方法的实现）。如果您选择不使用VersatileCollectionsStrictlyTypedCollectionInterfaceImplementationTrait ，那么您将必须实现VersatileCollectionsStrictlyTypedCollectionInterface中指定的所有方法，并确保在添加项目或修改项目的每个方法中调用checkType(mixed $item)方法在集合中，例如offsetSet($key, $val)并抛出一个每当checkType(mixed $item)返回 false 时， VersatileCollectionsExceptionsInvalidItemException异常。如果您在自定义集合类中使用VersatileCollectionsStrictlyTypedCollectionInterfaceImplementationTrait ，但添加了同时向集合中添加项目或修改项目的新方法，则可以使用VersatileCollectionsStrictlyTypedCollectionInterfaceImplementationTrait中提供的辅助方法isRightTypeOrThrowInvalidTypeException($item, $calling_functions_name)来验证项目（它会如果您正在验证的项目类型错误，则会自动抛出异常；请参阅VersatileCollectionsStrictlyTypedCollectionInterfaceImplementationTrait::offsetSet($key, $val)了解如何使用此帮助器方法的示例）。
您可以选择使用具有相同签名但具有特定类型的构造函数来覆盖StrictlyTypedCollectionInterfaceImplementationTrait::__construct(mixed ...$arr_objs) 。例如， __construct(PDO ...$pdo_objs)确保只有PDO的实例可以通过参数解包注入到构造函数中。
下面的代码示例显示了如何实现名为PdoCollection的自定义集合类，该类仅存储作为PDO实例的项目：
<?php
use VersatileCollections StrictlyTypedCollectionInterface ;
class PdoCollection implements StrictlyTypedCollectionInterface { //1. Implement interface
use VersatileCollections StrictlyTypedCollectionInterfaceImplementationTrait; //2. Use trait
public function __construct ( PDO ... $ pdo_objs ) { //3. Optionally override the constructor with a type
// specific one
$ this -> versatile_collections_items = $ pdo_objs ;
}
/**
*
* @return bool true if $item is of the expected type, else false
*
*/
public function checkType ( mixed $ item ): bool { //4. implement interface methods not implemented in trait above
return ( $ item instanceof PDO );
}
/**
*
* @return string|array a string or array of strings of type name(s)
* for items acceptable in instances of this
* collection class
*
*/
public function getTypes (): VersatileCollections StringsCollection { //4. implement interface methods not implemented in trait above
return new VersatileCollections StringsCollection ( PDO ::class);
}
}您可以将自定义类型化集合类声明为最终类，以便您的类的用户将无法扩展它们，从而规避在构造时和项目添加时强制执行的类型检查。
注意：如果您只想存储集合中特定类或其子类的实例的项目，并且不想为此目的创建自定义集合类，只需使用 SpecificObjectsCollection
方法词汇表（按类别）
方法描述与示例
通用集合
严格类型集合
Laravel 集合方法等价
如果您发现文档有任何问题，请提交问题或拉取请求。
