From 8bc589a8ab860efac65a4812fd2949f803cca0d8 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 21 Jul 2022 14:55:49 +0900 Subject: [PATCH 1/7] docs: decorate db column names --- user_guide_src/source/models/entities.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/user_guide_src/source/models/entities.rst b/user_guide_src/source/models/entities.rst index d2c99c8623b6..473194d3b80b 100644 --- a/user_guide_src/source/models/entities.rst +++ b/user_guide_src/source/models/entities.rst @@ -144,9 +144,9 @@ As an example, imagine you have the simplified User Entity that is used througho .. literalinclude:: entities/008.php Your boss comes to you and says that no one uses usernames anymore, so you're switching to just use emails for login. -But they do want to personalize the application a bit, so they want you to change the name field to represent a user's +But they do want to personalize the application a bit, so they want you to change the ``name`` field to represent a user's full name now, not their username like it does currently. To keep things tidy and ensure things continue making sense -in the database you whip up a migration to rename the `name` field to `full_name` for clarity. +in the database you whip up a migration to rename the ``name`` field to ``full_name`` for clarity. Ignoring how contrived this example is, we now have two choices on how to fix the User class. We could modify the class property from ``$name`` to ``$full_name``, but that would require changes throughout the application. Instead, we can From abe670ef583515a0f812f7e65468ab8f9aed382f Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 21 Jul 2022 15:14:33 +0900 Subject: [PATCH 2/7] docs: improve code comments --- user_guide_src/source/models/entities/009.php | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/user_guide_src/source/models/entities/009.php b/user_guide_src/source/models/entities/009.php index 411961833749..772cb6509d38 100644 --- a/user_guide_src/source/models/entities/009.php +++ b/user_guide_src/source/models/entities/009.php @@ -8,7 +8,7 @@ class User extends Entity { protected $attributes = [ 'id' => null, - 'full_name' => null, // In the $attributes, the key is the column name + 'full_name' => null, // In the $attributes, the key is the db column name 'email' => null, 'password' => null, 'created_at' => null, @@ -16,6 +16,7 @@ class User extends Entity ]; protected $datamap = [ + // property_name => db_column_name 'name' => 'full_name', ]; } From f422f3b3a83e29e0ac34e55161d18b590957e320 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 21 Jul 2022 15:15:58 +0900 Subject: [PATCH 3/7] docs: update PHPDocs --- system/Entity/Entity.php | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/system/Entity/Entity.php b/system/Entity/Entity.php index 7c451f646ea5..73fe16d791cc 100644 --- a/system/Entity/Entity.php +++ b/system/Entity/Entity.php @@ -146,7 +146,7 @@ public function fill(?array $data = null) * __get() magic method so will have any casts, etc applied to them. * * @param bool $onlyChanged If true, only return values that have changed since object creation - * @param bool $cast If true, properties will be casted. + * @param bool $cast If true, properties will be cast. * @param bool $recursive If true, inner entities will be casted as array as well. */ public function toArray(bool $onlyChanged = false, bool $cast = true, bool $recursive = false): array @@ -287,7 +287,7 @@ public function setAttributes(array $data) * Checks the datamap to see if this property name is being mapped, * and returns the db column name, if any, or the original property name. * - * @return string + * @return string db column name */ protected function mapProperty(string $key) { From 9c8d05ee8bd81d24e37a491bcae3ddc1aec8de02 Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 21 Jul 2022 15:16:36 +0900 Subject: [PATCH 4/7] fix: hasChanged() returns wrong result to mapped property --- system/Entity/Entity.php | 2 ++ tests/system/Entity/EntityTest.php | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+) diff --git a/system/Entity/Entity.php b/system/Entity/Entity.php index 73fe16d791cc..06f962328759 100644 --- a/system/Entity/Entity.php +++ b/system/Entity/Entity.php @@ -256,6 +256,8 @@ public function hasChanged(?string $key = null): bool return $this->original !== $this->attributes; } + $key = $this->mapProperty($key); + // Key doesn't exist in either if (! array_key_exists($key, $this->original) && ! array_key_exists($key, $this->attributes)) { return false; diff --git a/tests/system/Entity/EntityTest.php b/tests/system/Entity/EntityTest.php index d88f509694f7..2838aa02269e 100644 --- a/tests/system/Entity/EntityTest.php +++ b/tests/system/Entity/EntityTest.php @@ -929,6 +929,24 @@ public function testHasChangedNoChange() $this->assertFalse($entity->hasChanged('default')); } + public function testHasChangedMappedNoChange() + { + $entity = $this->getEntity(); + + $entity->createdAt = null; + + $this->assertFalse($entity->hasChanged('createdAt')); + } + + public function testHasChangedMappedChanged() + { + $entity = $this->getEntity(); + + $entity->createdAt = '2022-11-11 11:11:11'; + + $this->assertTrue($entity->hasChanged('createdAt')); + } + public function testHasChangedWholeEntity() { $entity = $this->getEntity(); From c48ed132fc0573897c8797fdb96c2926dbd2df1b Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 21 Jul 2022 15:29:40 +0900 Subject: [PATCH 5/7] docs: add note for setter and getter with data mapping --- user_guide_src/source/models/entities.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/user_guide_src/source/models/entities.rst b/user_guide_src/source/models/entities.rst index 473194d3b80b..55187ae7a0ad 100644 --- a/user_guide_src/source/models/entities.rst +++ b/user_guide_src/source/models/entities.rst @@ -164,6 +164,10 @@ through the original ``$user->full_name``, also, as this is needed for the model to the database. However, ``unset()`` and ``isset()`` only work on the mapped property, ``$user->name``, not on the database column name, ``$user->full_name``. +.. note:: When you use Data Mapping, you must define ``set*()`` and ``get*()`` method + for the database column name. In this example, you must define ``setFullName()`` and + ``getFullName()``. + Mutators ======== From 77347707c69446e8adb9b50a9e69cfba88fa7ada Mon Sep 17 00:00:00 2001 From: kenjis Date: Thu, 21 Jul 2022 15:30:12 +0900 Subject: [PATCH 6/7] docs: fix comment --- system/Entity/Entity.php | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/system/Entity/Entity.php b/system/Entity/Entity.php index 06f962328759..39adf0661215 100644 --- a/system/Entity/Entity.php +++ b/system/Entity/Entity.php @@ -482,7 +482,7 @@ public function __get(string $key) // Convert to CamelCase for the method $method = 'get' . str_replace(' ', '', ucwords(str_replace(['-', '_'], ' ', $key))); - // if a set* method exists for this key, + // if a get* method exists for this key, // use that method to insert this value. if (method_exists($this, $method)) { $result = $this->{$method}(); From 010a5cffcf47638807b7c6a962a56a079abb6b98 Mon Sep 17 00:00:00 2001 From: kenjis Date: Fri, 22 Jul 2022 10:43:04 +0900 Subject: [PATCH 7/7] docs: fix PHPDoc types --- system/Entity/Cast/BaseCast.php | 12 ++++++------ system/Entity/Cast/CastInterface.php | 12 ++++++------ system/Entity/Cast/DatetimeCast.php | 2 ++ 3 files changed, 14 insertions(+), 12 deletions(-) diff --git a/system/Entity/Cast/BaseCast.php b/system/Entity/Cast/BaseCast.php index c79dfc5f56b4..bfb156da3e53 100644 --- a/system/Entity/Cast/BaseCast.php +++ b/system/Entity/Cast/BaseCast.php @@ -19,10 +19,10 @@ abstract class BaseCast implements CastInterface /** * Get * - * @param mixed $value Data - * @param array $params Additional param + * @param array|bool|float|int|object|string|null $value Data + * @param array $params Additional param * - * @return mixed + * @return array|bool|float|int|object|string|null */ public static function get($value, array $params = []) { @@ -32,10 +32,10 @@ public static function get($value, array $params = []) /** * Set * - * @param mixed $value Data - * @param array $params Additional param + * @param array|bool|float|int|object|string|null $value Data + * @param array $params Additional param * - * @return mixed + * @return array|bool|float|int|object|string|null */ public static function set($value, array $params = []) { diff --git a/system/Entity/Cast/CastInterface.php b/system/Entity/Cast/CastInterface.php index e4a36384dba0..c1dcf1c40ead 100644 --- a/system/Entity/Cast/CastInterface.php +++ b/system/Entity/Cast/CastInterface.php @@ -19,20 +19,20 @@ interface CastInterface /** * Get * - * @param mixed $value Data - * @param array $params Additional param + * @param array|bool|float|int|object|string|null $value Data + * @param array $params Additional param * - * @return mixed + * @return array|bool|float|int|object|string|null */ public static function get($value, array $params = []); /** * Set * - * @param mixed $value Data - * @param array $params Additional param + * @param array|bool|float|int|object|string|null $value Data + * @param array $params Additional param * - * @return mixed + * @return array|bool|float|int|object|string|null */ public static function set($value, array $params = []); } diff --git a/system/Entity/Cast/DatetimeCast.php b/system/Entity/Cast/DatetimeCast.php index 99f425a410be..41af062cfe2b 100644 --- a/system/Entity/Cast/DatetimeCast.php +++ b/system/Entity/Cast/DatetimeCast.php @@ -24,6 +24,8 @@ class DatetimeCast extends BaseCast * {@inheritDoc} * * @throws Exception + * + * @return Time */ public static function get($value, array $params = []) {