ElementCollection

The class provides a flexible tool for working with cached lists of model elements.

Method List:

make($arElementIDList = [])

• arElementIDList - array of element ID

Static method. Used to create a new object of the ElementCollection class.

    $obList = ElementCollection::make([1, 2, 10, 15]);

set($arElementIDList)

• arElementIDList - array of element ID

Method allow to set list of element IDs in the collection

    $obList = ElementCollection::make()->set([1,2]);

isEmpty()

Method returns true, if the element list is empty.

    $obList = ElementCollection::make([1, 2, 10, 15]);
    if($obList->isEmpty()) {
        return false;
    }

isNotEmpty()

The method returns true, if the element list isn't empty.

    $obList = ElementCollection::make([1, 2, 10, 15]);
    if($obList->isNotEmpty()) {
        //...
    }

getIDList()

Method returns an array of element IDs.

    $obList = ElementCollection::make([1, 2, 10, 15]);
    return $obList->getIDList();

has($iElementID)

• iElementID - element ID

Method returns true, if the collection contains the element with ID = $iElementID.

    $obList = ElementCollection::make([1, 2, 10, 15]);
    if($obList->has(10)) {
        //...
    }

find($iElementID)

• iElementID - element ID

Method returns an object ElementItem with ID = $iElementID.

    $obList = ElementCollection::make([1, 2, 10, 15]);
    return $obList->find(10);

clear()

Method clears the collection.

    $obList = ElementCollection::make([1, 2, 10, 15]);
    $obList->clear();

count()

Method returns the count of elements in a collection.

    $obList = ElementCollection::make([1, 2, 10, 15]);
    return $obList->count();

intersect($arElementIDList)

• $arElementIDList - list of element IDs for intersection

Method applies the array_intersect() function to the collection and the array of element IDs $arElementIDList.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   
   $arElementIDList = [2,14,18];
   $obList->intersect($arElementIDList);

applySorting($arElementIDList)

• $arElementIDList - list of element IDs for intersection

Method applies the array_intersect() function to the array of element IDs $arElementIDList and the collection.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   
   $arElementIDList = [2,14,18];
   $obList->applySorting($arElementIDList);

merge($arElementIDList)

• $arElementIDList - list of element IDs to merge

Method applies array_merge() function to the collection and the array of element IDs $arElementIDList.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   
   $arElementIDList = [2,14,18];
   $obList->merge($arElementIDList);

diff($arElementIDList)

• $arElementIDList - list of element IDs

Method applies array_diff() function to the collection and the array of element IDs $arElementIDList.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   
   $arElementIDList = [2,14,18];
   $obList->diff($arElementIDList);

all()

Method returns an array of objects ElementItem, for all the elements in a collection.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   
   $arElementIDList = [2,14,18];
   $obList->merge($arElementIDList);

skip($iCount)

• $iCount - count of elements to skip

Method is used in combination with the take() method to specify the count of elements needed to be skipped.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   return $obList->skip(2)->take(1);

take($iCount = 0)

• $iCount - count of elements to be get

Method returns an array of ElementItem objects. Count of elements = $iCount, starting from the position specified in the skip() method. If you send $iCount = 0, you will obtain all elements, starting from the position specified in the skip() method.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   return $obList->skip(2)->take(1);

exclude($iElementID)

• $iElementID - element ID

Method excludes the element with ID = $iElementID from the collection.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   $obList->exclude(2);

random($iCount)

• $iCount - count of elements generated

Method returns an array of random ElementItem objects.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   return $obList->random(2);

page($iPage, $iElementOnPage = 10)

• $iPage - current page number
• $iElementOnPage - count of elements on the page

Method returns an array of ElementItem objects for the $iPage page.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   return $obList->page(2, 10);

first()

Method returns the first ElementItem object in a collection.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   return $obList->first();

last()

Method returns the last ElementItem object in a collection.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   return $obList->last();

shift()

Method returns the first ElementItem object in a collection and excludes it from the collection

   $obList = ElementCollection::make([1, 2, 10, 15]);
   return $obList->shift();

unshift($iElementID)

Method adds element to the beginning of collection

   $obList = ElementCollection::make([1, 2, 10, 15]);
   $obList->unshift(4);

pop()

Method returns the first ElementItem object in a collection and excludes it from the collection.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   return $obList->pop();

push($iElementID)

Method adds element to the end of collection

   $obList = ElementCollection::make([1, 2, 10, 15]);
   $obList->push(4);

pluck($sFieldName)

Method returns array of the values for a given field name.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   return $obList->pluck('name');

implode($sFieldName, $sDelimiter = ', ')

Method returns array of the values for a given field name and applies implode function to array.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   return $obList->implode('name', '-');

getNearestNext($iElementID, $iCount = 1, $bCyclic = false)

Method returns new collection with next nearest elements.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   
   //Collection has elements: 10
   $obNewList = $obList->getNearestNext(2);
   
   //Collection has elements: 2,10,15
   $obNewList = $obList->getNearestNext(1, 3);
   
   //Collection has elements: 10,15
   $obNewList = $obList->getNearestNext(2, 3);
   
   //Collection has elements: 10,15,1
   $obNewList = $obList->getNearestNext(2, 3, true);

getNearestPrev($iElementID, $iCount = 1, $bCyclic = false)

Method returns new collection with previous nearest elements.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   
   //Collection has elements: 1
   $obNewList = $obList->getNearestPrev(2);
   
   //Collection has elements: 10,2,1
   $obNewList = $obList->getNearestPrev(15, 3);
   
   //Collection has elements: 2,1
   $obNewList = $obList->getNearestPrev(10, 3);
   
   //Collection has elements: 2,1,15
   $obNewList = $obList->getNearestPrev(10, 3, true);

save($sKey)/saved($sKey)

• $sKey - collection state key to save

Method saves the state of a collection for it to be obtained later.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   $obList->save('my_key');
   
   ...
   
   $obSavedList = ElementCollection::make()->saved('my_key');
   
   //result: $obSavedList == clone $obList

debug()

Method allows to set a break point while using xDebug in the case of calling collection methods in Twig templates.

   $obList = ElementCollection::make([1, 2, 10, 15]);
   $obList->skip(2)->debug()->take(2);

Extending

You can add methods and properties in collection class with extending constructors.

Example

ElementCollection::extend(function($obCollection) {
             
     $obCollection->addDynamicMethod('my_method', function($arElementIDList) use ($obCollection) {
            return $obCollection->diff($arElementIDList);
     });
});