README

Time2Help is an utility library made in the first place to be shared across all Time2Split's projects. Nevertheless, its functionnalities may be used in any php project.

Installation

The library is distributed as a Composer project.

$ composer require time2split/time2help

Documentation

API documentation

Features

The library serves 3 main domains:

container
inputs/outputs (IO)
tests

Container

The container domain provides functionalities to works on different type of containers. It's purpose is

to facilitate operations through iteration on each container entry (key => value) and
provides implementations of usefull data structure.

Iterating through an iterable to do some operations on each item appears to be a common task in a program. The library provides functionnalities to works on arrays, and more generally on iterables (which have the advantage to be able to work on efficient Generators).

For instance, an iterating function can be: to iterate in reverse order, iterate only on key, filter the entries to be iterated, apply an operation to each entries of a container, flip the entry key and value; and any composition of the provided functions. (Consult the API documentation if interested to know all the existing functions.)

The container functions return mainly \Iterator instances, that internally are more specifically \Generator. Generators have the advantage to be space-efficient: they just return an entry through an iteration without the need to store all the entries to be returned. All iteration operations on containers return iterators. Moreover it's so easy to get an array from an iterable with \iterator_to_array() that the library as no interest in returning less space-efficient array values.

Concerning the second purpose of the container domain, the library provides implementations for the Set and Optional data-structures and more basic functionnalities on lists (array with integer keys).

IO

The IO domain provides 3 utility classes.

CharPredicates Functions to create char predicate closures.
IO Functions for inputs/outputs.
Streams Functions for stream resource.

Streams and Char predicate where made mainly to facilitate the writing of parsers. CharPredicate permits to generate char predicate closures. Streams provides functions for reading on php resource streams.

IO provides functions to works with the filesystem and the php output buffer, and also somme facilities to launch an external cli command and retrieves the output and the errors.

tests

The tests domain was mad to facilitate the writting of unit test with PHPUnit. It provides 2 classes

The use case is to

Write an iterable of Provided, that can be viewed as an incomplete database of arguments to be send to a unit test method
Make the complete iterable of dataset to be returned by a DataProvider with a space-efficient cartesian product between multiple Provided databases.

The advantage of this workflow is that it's easy to conceptualise the different database to write and to compose them. The cartesian product generate automatically a PHPUnit dataset's name and arguments, and is able to dynamically generate a data when a specific database argument is selected by the cartesian product. The cartesian product implementation uses internally a Generator. That Generator do not stores the all cartesian product in a container, but it generates each dataset only when needed by a test method.

time2split / time2help

Maintainers

Details