You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: user_guide_src/source/models/entities.rst
+20-15Lines changed: 20 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -10,8 +10,9 @@ be used directly with the :doc:`Model </models/model>` if that fits your needs b
10
10
:local:
11
11
:depth: 2
12
12
13
+
************
13
14
Entity Usage
14
-
============
15
+
************
15
16
16
17
At its core, an Entity class is simply a class that represents a single database row. It has class properties
17
18
to represent the database columns, and provides any additional methods to implement the business logic for
@@ -34,7 +35,7 @@ Assume you have a database table named ``users`` that has the following schema::
34
35
.. important:: ``attributes`` is a reserved word for internal use. If you use it as a column name, the Entity does not work correctly.
35
36
36
37
Create the Entity Class
37
-
-----------------------
38
+
=======================
38
39
39
40
Now create a new Entity class. Since there's no default location to store these classes, and it doesn't fit
40
41
in with the existing directory structure, create a new directory at **app/Entities**. Create the
@@ -45,7 +46,7 @@ Entity itself at **app/Entities/User.php**.
45
46
At its simplest, this is all you need to do, though we'll make it more useful in a minute.
46
47
47
48
Create the Model
48
-
----------------
49
+
================
49
50
50
51
Create the model first at **app/Models/UserModel.php** so that we can interact with it:
51
52
@@ -58,7 +59,7 @@ class as the ``$returnType``. This ensures that all methods on the model that re
58
59
instances of our User Entity class instead of an object or array like normal.
59
60
60
61
Working with the Entity Class
61
-
-----------------------------
62
+
=============================
62
63
63
64
Now that all of the pieces are in place, you would work with the Entity class as you would any other class:
64
65
@@ -79,7 +80,7 @@ a new row, or update an existing one.
79
80
call the ``update()``, then only values that have changed are passed.
80
81
81
82
Filling Properties Quickly
82
-
--------------------------
83
+
==========================
83
84
84
85
The Entity class also provides a method, ``fill()`` that allows you to shove an array of key/value pairs into the class
85
86
and populate the class properties. Any property in the array will be set on the Entity. However, when saving through
@@ -93,15 +94,16 @@ You can also pass the data in the constructor and the data will be passed throug
93
94
.. literalinclude:: entities/005.php
94
95
95
96
Bulk Accessing Properties
96
-
-------------------------
97
+
=========================
97
98
98
99
The Entity class has two methods to extract all available properties into an array: ``toArray()`` and ``toRawArray()``.
99
100
Using the raw version will bypass magic "getter" methods and casts. Both methods can take a boolean first parameter
100
101
to specify whether returned values should be filtered by those that have changed, and a boolean final parameter to
101
102
make the method recursive, in case of nested Entities.
102
103
104
+
***********************
103
105
Handling Business Logic
104
-
=======================
106
+
***********************
105
107
106
108
While the examples above are convenient, they don't help enforce any business logic. The base Entity class implements
107
109
some smart ``__get()`` and ``__set()`` methods that will check for special methods and use those instead of using
@@ -131,8 +133,9 @@ business logic and create objects that are pleasant to use.
131
133
132
134
.. literalinclude:: entities/007.php
133
135
136
+
************
134
137
Data Mapping
135
-
============
138
+
************
136
139
137
140
At many points in your career, you will run into situations where the use of an application has changed and the
138
141
original column names in the database no longer make sense. Or you find that your coding style prefers camelCase
@@ -168,11 +171,12 @@ to the database. However, ``unset()`` and ``isset()`` only work on the mapped pr
168
171
for the database column name. In this example, you must define ``setFullName()`` and
169
172
``getFullName()``.
170
173
174
+
********
171
175
Mutators
172
-
========
176
+
********
173
177
174
178
Date Mutators
175
-
-------------
179
+
=============
176
180
177
181
By default, the Entity class will convert fields named `created_at`, `updated_at`, or `deleted_at` into
178
182
:doc:`Time </libraries/time>` instances whenever they are set or retrieved. The Time class provides a large number
@@ -190,7 +194,7 @@ current timezone, as set in **app/Config/App.php**:
190
194
.. _entities-property-casting:
191
195
192
196
Property Casting
193
-
----------------
197
+
================
194
198
195
199
You can specify that properties in your Entity should be converted to common data types with the ``$casts`` property.
196
200
This option should be an array where the key is the name of the class property, and the value is the data type it
@@ -206,7 +210,7 @@ For example, if you had a User entity with an ``is_banned`` property, you can ca
206
210
.. literalinclude:: entities/012.php
207
211
208
212
Array/Json Casting
209
-
------------------
213
+
==================
210
214
211
215
Array/Json casting is especially useful with fields that store serialized arrays or json in them. When cast as:
212
216
@@ -227,7 +231,7 @@ the value whenever the property is set:
227
231
.. literalinclude:: entities/014.php
228
232
229
233
CSV Casting
230
-
-----------
234
+
===========
231
235
232
236
If you know you have a flat array of simple values, encoding them as a serialized or JSON string
233
237
may be more complex than the original structure. Casting as Comma-Separated Values (CSV) is
@@ -243,7 +247,7 @@ Stored in the database as "red,yellow,green":
243
247
.. note:: Casting as CSV uses PHP's internal ``implode`` and ``explode`` methods and assumes all values are string-safe and free of commas. For more complex data casts try ``array`` or ``json``.
244
248
245
249
Custom casting
246
-
--------------
250
+
==============
247
251
248
252
You can define your own conversion types for getting and setting data.
249
253
@@ -275,8 +279,9 @@ Additional parameters are indicated in square brackets and listed with a comma.
275
279
the value ``nullable`` will be passed to the casting type handler.
276
280
If casting type has predefined parameters, then ``nullable`` will be added to the end of the list.
277
281
282
+
*******************************
278
283
Checking for Changed Attributes
279
-
===============================
284
+
*******************************
280
285
281
286
You can check if an Entity attribute has changed since it was created. The only parameter is the name of the
0 commit comments