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.