Group actions

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.

Bitrix Framework