tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-10-22 14:05:37 +02:00
Code Issues Projects Releases Wiki Activity

Merge pull request #9550 from jakxnz/pulls/4/docs-regarding-cached-get-ones

Browse Source 
Added documentation regarding some cached ORM scenarios
This commit is contained in:
Guy Marriott 2020-06-17 09:04:07 -07:00 committed by GitHub
commit 4df45f4fe0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 22 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md
View File

@ -186,6 +186,12 @@ $members = Player::get()->filter([
Provided `filter` values are automatically escaped and do not require any escaping.
[/info]
[info]
`DataObject::get()->byID()` and `DataObject::get_by_id()` achieve similar results, but the object returned by `DataObject::get_by_id()` is cached against a `static` property within `DataObject`.
`DataObject::get_by_id()` is a legacy ORM method, and it is recommended that you use `DataObject::get()->byID()` wherever possible
[/info]
## Lazy Loading
The `ORM` doesn't actually execute the [SQLSelect](api:SilverStripe\ORM\Queries\SQLSelect) until you iterate on the result with a `foreach()` or `<% loop %>`.

12
src/ORM/DataList.php
View File

@ -926,6 +926,8 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
/**
* Returns the first item in this DataList
*
* The object returned is not cached, unlike {@link DataObject::get_one()}
*
* @return DataObject
*/
public function first()
@ -939,7 +941,9 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
/**
* Returns the last item in this DataList
*
* @return DataObject
* The object returned is not cached, unlike {@link DataObject::get_one()}
*
* @return DataObject
*/
public function last()
{
@ -962,6 +966,8 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
/**
* Find the first DataObject of this DataList where the given key = value
*
* The object returned is not cached, unlike {@link DataObject::get_one()}
*
* @param string $key
* @param string $value
* @return DataObject|null
@ -998,6 +1004,8 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
/**
* Return the first DataObject with the given ID
*
* The object returned is not cached, unlike {@link DataObject::get_by_id()}
*
* @param int $id
* @return DataObject
*/
@ -1244,6 +1252,8 @@ class DataList extends ViewableData implements SS_List, Filterable, Sortable, Li
/**
* Returns item stored in list with index $key
*
* The object returned is not cached, unlike {@link DataObject::get_one()}
*
* @param mixed $key
* @return DataObject
*/

6
src/ORM/DataObject.php
View File

@ -3217,7 +3217,9 @@ class DataObject extends ViewableData implements DataObjectInterface, i18nEntity
/**
* Return the first item matching the given query.
* All calls to get_one() are cached.
*
* The object returned is cached, unlike DataObject::get()->first() {@link DataList::first()}
* and DataObject::get()->last() {@link DataList::last()}
*
* The filter argument supports parameterised queries (see SQLSelect::addWhere() for syntax examples). Because
* of that (and differently from e.g. DataList::filter()) you need to manually escape the field names:
@ -3326,6 +3328,8 @@ class DataObject extends ViewableData implements DataObjectInterface, i18nEntity
* This can be called either via `DataObject::get_by_id(MyClass::class, $id)`
* or `MyClass::get_by_id($id)`
*
* The object returned is cached, unlike DataObject::get()->byID() {@link DataList::byID()}
*
* @param string|int $classOrID The class of the object to be returned, or id if called on target class
* @param int|bool $idOrCache The id of the element, or cache if called on target class
* @param boolean $cache See {@link get_one()}