From 03c3ca3618acc28b4440047be0895f90daa962ba Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 26 Feb 2024 17:15:07 +0900 Subject: [PATCH 1/7] docs: add empty lines --- user_guide_src/source/models/entities.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/models/entities.rst b/user_guide_src/source/models/entities.rst index 6e683dcafe0b..d3443093d47e 100644 --- a/user_guide_src/source/models/entities.rst +++ b/user_guide_src/source/models/entities.rst @@ -60,9 +60,13 @@ Create the model first at **app/Models/UserModel.php** so that we can interact w .. literalinclude:: entities/002.php -The model uses the ``users`` table in the database for all of its activities. We've set the ``$allowedFields`` property +The model uses the ``users`` table in the database for all of its activities. + +We've set the ``$allowedFields`` property to include all of the fields that we want outside classes to change. The ``id``, ``created_at``, and ``updated_at`` fields -are handled automatically by the class or the database, so we don't want to change those. Finally, we've set our Entity +are handled automatically by the class or the database, so we don't want to change those. + +Finally, we've set our Entity class as the ``$returnType``. This ensures that all methods on the model that return rows from the database will return instances of our User Entity class instead of an object or array like normal. From 053929712f55742341839d6e3e6f42f3b68610a8 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 26 Feb 2024 17:15:38 +0900 Subject: [PATCH 2/7] docs: break long lines --- user_guide_src/source/models/entities.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/user_guide_src/source/models/entities.rst b/user_guide_src/source/models/entities.rst index d3443093d47e..202e39ed7365 100644 --- a/user_guide_src/source/models/entities.rst +++ b/user_guide_src/source/models/entities.rst @@ -62,13 +62,14 @@ Create the model first at **app/Models/UserModel.php** so that we can interact w The model uses the ``users`` table in the database for all of its activities. -We've set the ``$allowedFields`` property -to include all of the fields that we want outside classes to change. The ``id``, ``created_at``, and ``updated_at`` fields -are handled automatically by the class or the database, so we don't want to change those. - -Finally, we've set our Entity -class as the ``$returnType``. This ensures that all methods on the model that return rows from the database will return -instances of our User Entity class instead of an object or array like normal. +We've set the ``$allowedFields`` property to include all of the fields that we +want outside classes to change. The ``id``, ``created_at``, and ``updated_at`` +fields are handled automatically by the class or the database, so we don't want +to change those. + +Finally, we've set our Entity class as the ``$returnType``. This ensures that all +methods on the model that return rows from the database will return instances of +our User Entity class instead of an object or array like normal. Working with the Entity Class ============================= From 25fb054fa2fd55a6db9be779789bee7469d5cf49 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 26 Feb 2024 17:20:05 +0900 Subject: [PATCH 3/7] docs: add description --- user_guide_src/source/models/model.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide_src/source/models/model.rst b/user_guide_src/source/models/model.rst index d40c07ba6e6b..cdf32f5baeda 100644 --- a/user_guide_src/source/models/model.rst +++ b/user_guide_src/source/models/model.rst @@ -145,7 +145,7 @@ This requires either a DATETIME or INTEGER field in the database as per the mode `$dateFormat`_ setting. The default field name is ``deleted_at`` however this name can be configured to any name of your choice by using `$deletedField`_ property. -.. important:: The ``deleted_at`` field must be nullable. +.. important:: The ``deleted_at`` field in the database must be nullable. $allowedFields -------------- From 8b1e3a0e06ee899e34de2638bda40684e7d74ec8 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 26 Feb 2024 17:22:44 +0900 Subject: [PATCH 4/7] docs: add empty lines --- user_guide_src/source/models/model.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/models/model.rst b/user_guide_src/source/models/model.rst index cdf32f5baeda..91d39cd6a4fe 100644 --- a/user_guide_src/source/models/model.rst +++ b/user_guide_src/source/models/model.rst @@ -124,10 +124,14 @@ $returnType ----------- The Model's CRUD methods will take a step of work away from you and automatically return -the resulting data, instead of the Result object. This setting allows you to define +the resulting data, instead of the Result object. + +This setting allows you to define the type of data that is returned. Valid values are '**array**' (the default), '**object**', or the **fully qualified name of a class** that can be used with the Result object's ``getCustomResultObject()`` -method. Using the special ``::class`` constant of the class will allow most IDEs to +method. + +Using the special ``::class`` constant of the class will allow most IDEs to auto-complete the name and allow functions like refactoring to better understand your code. .. _model-use-soft-deletes: From 16842062bddbf236b541c6accc789d3dd378b82b Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 26 Feb 2024 17:23:23 +0900 Subject: [PATCH 5/7] docs: break long lines --- user_guide_src/source/models/model.rst | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/user_guide_src/source/models/model.rst b/user_guide_src/source/models/model.rst index 91d39cd6a4fe..de188fa74f67 100644 --- a/user_guide_src/source/models/model.rst +++ b/user_guide_src/source/models/model.rst @@ -123,16 +123,16 @@ default value is ``true``. $returnType ----------- -The Model's CRUD methods will take a step of work away from you and automatically return -the resulting data, instead of the Result object. +The Model's CRUD methods will take a step of work away from you and automatically +return the resulting data, instead of the Result object. -This setting allows you to define -the type of data that is returned. Valid values are '**array**' (the default), '**object**', or the **fully -qualified name of a class** that can be used with the Result object's ``getCustomResultObject()`` -method. +This setting allows you to define the type of data that is returned. Valid values +are '**array**' (the default), '**object**', or the **fully qualified name of a class** +that can be used with the Result object's ``getCustomResultObject()`` method. Using the special ``::class`` constant of the class will allow most IDEs to -auto-complete the name and allow functions like refactoring to better understand your code. +auto-complete the name and allow functions like refactoring to better understand +your code. .. _model-use-soft-deletes: From 6615763349f5b1d01f1d0f752af4a7102539d5c4 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 26 Feb 2024 17:23:50 +0900 Subject: [PATCH 6/7] docs: fix description --- user_guide_src/source/models/model.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/user_guide_src/source/models/model.rst b/user_guide_src/source/models/model.rst index de188fa74f67..41a754bc25ee 100644 --- a/user_guide_src/source/models/model.rst +++ b/user_guide_src/source/models/model.rst @@ -123,7 +123,7 @@ default value is ``true``. $returnType ----------- -The Model's CRUD methods will take a step of work away from you and automatically +The Model's **find*()** methods will take a step of work away from you and automatically return the resulting data, instead of the Result object. This setting allows you to define the type of data that is returned. Valid values From a5be00b6be4d1d8857c37e4c01c3056099ef78f4 Mon Sep 17 00:00:00 2001 From: kenjis Date: Mon, 26 Feb 2024 17:37:27 +0900 Subject: [PATCH 7/7] docs: fix misleading description and add note --- user_guide_src/source/models/entities.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/models/entities.rst b/user_guide_src/source/models/entities.rst index 202e39ed7365..bcc0c2ec57d0 100644 --- a/user_guide_src/source/models/entities.rst +++ b/user_guide_src/source/models/entities.rst @@ -68,8 +68,12 @@ fields are handled automatically by the class or the database, so we don't want to change those. Finally, we've set our Entity class as the ``$returnType``. This ensures that all -methods on the model that return rows from the database will return instances of -our User Entity class instead of an object or array like normal. +built-in methods on the model that return rows from the database will return +instances of our User Entity class instead of an object or array like normal. + +.. note:: + Of course, if you add a custom method to your model, you must implement it + so that instances of ``$returnType`` are returned. Working with the Entity Class =============================