Views: 3180
Last Modified: 30.03.2022

Collections allow performing group actions for items contained inside such collections.

  • save (adding)

    The method save() performs primary saving in case of new objects, by generating a single group query:

    use \Bitrix\Main\Test\Typography\Books;
    use \Bitrix\Main\Test\Typography\Book;
    
    $books = new Books;
    
    $books[] = (new Book)->setTitle('Title 112');
    $books[] = (new Book)->setTitle('Title 113');
    $books[] = (new Book)->setTitle('Title 114');
    
    $books->save(true);
    
    // INSERT INTO ...  (`TITLE`, `ISBN`) VALUES
    	('Title 112', DEFAULT),
    	('Title 113', DEFAULT),
    	('Title 114', '114-000')

    The method receives the parameter $ignoreEvents = true, cancelling the ORM events when adding entries. In case of multiple inserting with autoincremental field (ID) you cannot get multiple values of this field which is possible when inserting a single entry using the function similar to mysqli_insert_id().

    In the rest of cases, when entity doesn't have autoincremental fields, events are left to the discretion of a developer. Events are executed by default.

  • save (editing)

    The method save() saves already existing, but modified objects using a single query UPDATE:

    use \Bitrix\Main\Test\Typography\PublisherTable;
    use \Bitrix\Main\Test\Typography\BookTable;
    
    $books = BookTable::getList()->fetchCollection();
    $publisher = PublisherTable::wakeUpObject(254);
    
    foreach ($books as $book)
    {
    	$book->setPublisher($publisher);
    }
    
    $books->save();
    
    // UPDATE ... SET `PUBLISHER_ID` = '254'
    	WHERE `ID` IN ('1', '2')

    Group update works only in case, when set of updated data is the same for all objects. When at least a single object has different data, all entries/records will be saved individually.

    As in the case with the adding action, the update action can disable event using the parameter $ignoreEvents in the method save(). By default, events are executed for each collection item individually.

  • fill

    Collection operation fill is a great alternative to the similar operation in Object, executed in a loop. In case of a loop, number of database queries will be equal to the number of objects:

    /** @var \Bitrix\Main\Test\Typography\Book[] $books */
    $books = [
    	\Bitrix\Main\Test\Typography\Book::wakeUp(1),
    	\Bitrix\Main\Test\Typography\Book::wakeUp(2)
    ];
    
    foreach ($books as $book)
    {
    	$book->fill();
    	// SELECT ... WHERE ID = ...
    	// do not do this!
    }

    In case of collection the query will be an only single one:

    $books = new \Bitrix\Main\Test\Typography\Books;
    // or $books = \Bitrix\Main\Test\Typography\BookTable::createCollection();
    
    $books[] = \Bitrix\Main\Test\Typography\Book::wakeUp(1);
    $books[] = \Bitrix\Main\Test\Typography\Book::wakeUp(2);
    
    $books->fill();
    // SELECT ... WHERE ID IN(1,2)
    

    As in the case with objects, the parameter fill can pass the array with names of fields for completing or a mask type as follows:

    $books->fill(['TITLE', 'PUBLISHER_ID']);
    $books->fill(\Bitrix\Main\ORM\Fields\FieldTypeMask::FLAT);

    You can find more details on possible parameter values in this article for Objects fill.

  • get*List

    Not the most rare case: getting list of values for dedicated field from the query result. In standard case this can look as follows:

    $books = \Bitrix\Main\Test\Typography\BookTable::getList()
    	->fetchCollection();
    
    $titles = [];
    
    foreach ($books as $book)
    {
    	$titles[] = $book->getTitle();
    }

    Named group "getter" method allows to reduce such loop to a single code line:

    $books = \Bitrix\Main\Test\Typography\BookTable::getList()
    	->fetchCollection();
    
    $titles = $books->getTitleList();

    Such "getters" are available for all entity fields and are described in annotations for IDE.





Courses developed by Bitrix24