Home

Collection documentation

This wiki is mainly meant to provide a handbook to work with collection. If you need help or a tuturial to work with collection this is the first place to look. At top-level of collection is also an examples directory to look at.

Collection Outline

The reason I created collection are:

1. PHP array syntax and its hundrets of functions (array_*) are awkward to use
2. PHP has just one type for lists, dictionaries, maps and so on
3. You have no certain method to dinstinguish between sequences and hash-table like structures
4. Allow full proxying of objects which are added to this types
5. Build view helpers to allow beautiful one-line syntax

The main API-inspiration comes from python and the Qt-Framework. In python you can write many operations in one line where you have to write many lines of php code to get the same (and often not as explicit/exact) result. Collection will always throw an exception if a key or index does not exist.

Basic Types/Primitives

The most basic types in collection are: OrderedList and Dictionary. If list was not a reserved word in PHP I had name it List...

OrderedList

The OrderedList represents a sequence of items. It has always a gapless numeric index. Therefore it is easy to use it as a container to manage ordered items. It has simple methods to add, remove and reorder its items. Read more here.

Dictionary

The Dictionary is the opposite of an OrderedList. It holds key/value pairs. The keys have to be scalar (which will be change in future PHP versions). There is no guarantee that the insertion order will be remembered. Because the current implementation uses a normal PHP array to store its values it will remember insertion order but this might change. Read more here

Extended Types

To help with views or special cases a view extended classes are available. These classes are used as helpers or to allow better view formatting.

StringList

This is a view helper. It works exactly like a OrderedList but can be displayed as a string. It has a delimiter, a prexix and a suffix to control its output. A __toString() method renders the list to a string, a StringList::fromString($string,$delimiter) method creates one by a string. One good use case is the list of css classes typically found in a class attribute in html. Read more here

StringDictionary

A StringDictionary is the counterpart of a StringList for dictionaries. You have a row delimiter, a key/value delimiter, a prefix and a suffix. With it you can build xml attribute lists, SQL columns and such things. Read more here

Map

A Map is an object which behaves like a Dictionary/array but is just a proxy to a another OrderedList/array. So you would create a Map, assign a so called Extractor (a callable) which will extract the values from your objects. So you could just assign a bunch of Contact objects to an array, assign function($item, $index){ return [$index,$item->email] } and have an object which behaves exactly like an array but holds all data. You can then pass this map to the view and have all objects with it. Read more here.

Table/ColumnList/Column

A Table is a more complex and view oriented class. It helps to build tabular data without loosing the original objects. You can assign an extractor like on Map which extracts the values and a ColumnList. Then you can iterate through your table rows and on each row iterate over your columns. This holds your view very clean and allows to defer the actual fetching of records into the render method. With the help of StringList you can build a semantic view of css-annotated table an then render it into a excel file. Read more here