From 6813c0f7e89453c59b4c7d3926cec18d555df738 Mon Sep 17 00:00:00 2001
From: Jackson Darlow <jackson.e.darlow@gmail.com>
Date: Wed, 17 Jun 2020 17:14:08 +1200
Subject: [PATCH] Added documentation regarding some cached ORM scenarios

---
 .../00_Model/01_Data_Model_and_ORM.md                |  6 ++++++
 src/ORM/DataList.php                                 | 12 +++++++++++-
 src/ORM/DataObject.php                               |  6 +++++-
 3 files changed, 22 insertions(+), 2 deletions(-)

diff --git a/docs/en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md b/docs/en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md
index d9a9fff23..ccfeebd72 100644
--- a/docs/en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md
+++ b/docs/en/02_Developer_Guides/00_Model/01_Data_Model_and_ORM.md
@@ -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 %>`.
diff --git a/src/ORM/DataList.php b/src/ORM/DataList.php
index b494c7441..ac87c082f 100644
--- a/src/ORM/DataList.php
+++ b/src/ORM/DataList.php
@@ -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
      */
diff --git a/src/ORM/DataObject.php b/src/ORM/DataObject.php
index b34cb9a86..e74342336 100644
--- a/src/ORM/DataObject.php
+++ b/src/ORM/DataObject.php
@@ -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()}