Download the PHP package rotexsoft/versatile-collections without Composer
On this page you can find all versions of the php package rotexsoft/versatile-collections. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download rotexsoft/versatile-collections
More information about rotexsoft/versatile-collections
Files in rotexsoft/versatile-collections
Package versatile-collections
Short Description A collection package that can be extended to implement things such as a Dependency Injection Container, RecordSet objects for housing database records, a bag of http cookies, or technically any collection of items that can be looped over and whose items can each be accessed using array-access syntax or object property syntax.
License BSD-3-Clause
Homepage https://github.com/rotexsoft/versatile-collections
Informations about the package versatile-collections
Versatile Collections
A collection package that can be extended to implement things such as a Dependency Injection Container, RecordSet objects for housing database records, a bag of http cookies, or technically any collection of items that can be looped over and whose items can each be accessed using array-access syntax or object property syntax.
You can:
- use one of the provided Collection classes directly in your application(s)
- or include one or more of the provided Collection classes within an existing class in your application and expose features you want (Composition)
- or extend one or more of the the provided Collection classes (Inheritance) and then use those extended classes in your application(s)
- or just implement one or more of the Collection Interfaces and use the corresponding trait (Contract fulfillment)
This package provides optional strict-typing of collection items and strives for 100 % unit-test coverage.
Installation
Via composer: (Requires PHP 7.4+ or PHP 8.0+).
Switch to the 3.X branch to read the documentation for the 3.X version.
Switch to the 4.X branch to read the documentation for the 4.X version.
Switch to the 5.x branch to read the documentation for the 5.x version.
Switch to the master branch to read the documentation for the latest version.
composer require rotexsoft/versatile-collections
Basics
If you are simply looking to store items of the same or differing types in a collection you can use simply use the GenericCollection class like so:
You can also make any class in your application behave exactly like \VersatileCollections\GenericCollection by implementing \VersatileCollections\CollectionInterface and using \VersatileCollections\CollectionInterfaceImplementationTrait in such classes.
If you want to enforce strict-typing, the following Collection classes are provided in this package:
- Arrays Collections: a collection that only stores items that are arrays (i.e. items for which is_array is true)
- Callables Collections: a collection that only stores items that are callables (i.e. items for which is_callable is true)
- Objects Collections: a collection that only stores items that are objects (i.e. items for which is_object is true)
- Arrays Collections to store arrays or you could create a new collection class that accepts all iterables (both arrays & every other type for which is_iterable returns true)
- Specific Objects Collections: a collection that only stores items that are instances of a specified class or any of its sub-classes
- Resources Collections: a collection that only stores items that are resources (i.e. items for which is_resource is true)
- Scalars Collections: a collection that only stores items that are scalars (i.e. items for which is_scalar is true)
- Numerics Collections: a collection that only stores items that are either floats or integers (i.e. items for which is_int or is_float is true)
- Floats Collections: a collection that only stores items that are floats (i.e. items for which is_float is true)
- Ints Collections: a collection that only stores items that are integers (i.e. items for which is_int is true)
- Strings Collections: a collection that only stores items that are strings (i.e. items for which is_string is true)
- Numerics Collections: a collection that only stores items that are either floats or integers (i.e. items for which is_int or is_float is true)
To implement a custom collection that only contains objects that are instances of a specific class (for example \PDO), your custom collection class must adhere to the following requirements:
-
Your custom collection class must implement \VersatileCollections\StrictlyTypedCollectionInterface which currently contains the methods below:
- public function checkType(mixed $item): bool : it must return true if
$item
is of the expected type or false otherwise - public function getTypes() : it must return an instance of \VersatileCollections\StringsCollection of strings representing the name(s) of the expected type(s)
- public function checkType(mixed $item): bool : it must return true if
-
Your custom collection class should use \VersatileCollections\StrictlyTypedCollectionInterfaceImplementationTrait (which contains implementation of the methods in \VersatileCollections\StrictlyTypedCollectionInterface). If you choose not to use \VersatileCollections\StrictlyTypedCollectionInterfaceImplementationTrait, then you will have to implement all the methods specified in \VersatileCollections\StrictlyTypedCollectionInterface and make sure you call the checkType(mixed $item) method in every method where you add items to or modify items in the collection such as offsetSet($key, $val) and throw an VersatileCollections\Exceptions\InvalidItemException exception whenever checkType(mixed $item) returns false. If you use \VersatileCollections\StrictlyTypedCollectionInterfaceImplementationTrait in your custom collection class but add new methods that also add items to or modify items in the collection you can use the helper method isRightTypeOrThrowInvalidTypeException($item, $calling_functions_name) provided in \VersatileCollections\StrictlyTypedCollectionInterfaceImplementationTrait to validate items (it will automatically throw an exception for you if the item you are validating is of the wrong type; see \VersatileCollections\StrictlyTypedCollectionInterfaceImplementationTrait::offsetSet($key, $val) for an example of how this helper method should be used).
- You can optionally override StrictlyTypedCollectionInterfaceImplementationTrait::__construct(mixed ...$arr_objs) with a constructor with the same signature but with the specific type. For example, __construct(\PDO ...$pdo_objs) ensures that only instances of \PDO can be injected into the constructor via argument unpacking.
The code example below shows how a custom collection class called PdoCollection, that only stores items that are instances of \PDO, can be implemented:
You can declare your custom typed collection classes as final so that users of your classes will not be able to extend them and thereby circumvent the type-checking being enforced at construct time and item addition time.
NOTE: If you only want to store items that are only instances of a specific class or its sub-classes in a collection and don't want to have to create a custom collection class for that purpose, simply use SpecificObjectsCollection
Documentation
- Methods Glossary by Category
- Methods Descriptions with Examples
- Generic Collections
- Strictly Typed Collections
- arrays
- callables
- objects (any kind of object)
- \is_iterable returns true
- Objects Collections) if no class is specified
- resources
- strings. It accepts any mix of scalars, e.g. ints, booleans, floats and strings can all be present in an instance of this type of collection.
- integers
- floats
- integers
- strings
- integers
-
Laravel Collection Methods Equivalence
- Please submit an issue or a pull request if you find any issues with the documentation.
Issues
- Please submit an issue or a pull request if you find any bugs or better and more efficient way(s) things could be implemented in this package.
Contributing
- master branch currently contains code for the latest version, which as of March 2024 is 6.x
- Bugfixes for version 5.x should be applied to the 5.x branch.
- Bugfixes for version 4.x should be applied to the 4.X branch.
- Bugfixes for version 3.x should be applied to the 3.X branch.
- Bugfixes for version 2.x should be applied to the 2.X branch.