refactor: Improve phpDoc, typos

Author: neznaika0

system/Entity/Entity.php

@@ -30,7 +30,6 @@
 use CodeIgniter\Entity\Cast\URICast;
 use CodeIgniter\Entity\Exceptions\CastException;
 use CodeIgniter\I18n\Time;
-use DateTime;
 use DateTimeInterface;
 use Exception;
 use JsonSerializable;
@@ -79,14 +78,14 @@ class Entity implements JsonSerializable
     protected $casts = [];
 
     /**
-     * Custom convert handlers
+     * Custom convert handlers.
      *
      * @var array<string, string>
      */
     protected $castHandlers = [];
 
     /**
-     * Default convert handlers
+     * Default convert handlers.
      *
      * @var array<string, string>
      */
@@ -131,17 +130,19 @@ class Entity implements JsonSerializable
     protected DataCaster $dataCaster;
 
     /**
-     * Holds info whenever properties have to be casted
+     * Holds info whenever properties have to be casted.
      */
     private bool $_cast = true;
 
     /**
-     * Indicates whether all attributes are scalars (for optimization)
+     * Indicates whether all attributes are scalars (for optimization).
      */
     private bool $_onlyScalars = true;
 
     /**
      * Allows filling in Entity parameters during construction.
+     *
+     * @param array<string, mixed> $data
      */
     public function __construct(?array $data = null)
     {
@@ -162,7 +163,7 @@ public function __construct(?array $data = null)
      * properties, using any `setCamelCasedProperty()` methods
      * that may or may not exist.
      *
-     * @param array<string, array|bool|float|int|object|string|null> $data
+     * @param array<string, array<int|string, mixed>|bool|float|int|object|string|null> $data
      *
      * @return $this
      */
@@ -184,9 +185,11 @@ public function fill(?array $data = null)
      * of this entity as an array. All values are accessed through the
      * __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 $onlyChanged If true, only return values that have changed since object creation.
      * @param bool $cast        If true, properties will be cast.
      * @param bool $recursive   If true, inner entities will be cast as array as well.
+     *
+     * @return array<string, mixed>
      */
     public function toArray(bool $onlyChanged = false, bool $cast = true, bool $recursive = false): array
     {
@@ -227,8 +230,10 @@ public function toArray(bool $onlyChanged = false, bool $cast = true, bool $recu
     /**
      * Returns the raw values of the current attributes.
      *
-     * @param bool $onlyChanged If true, only return values that have changed since object creation
+     * @param bool $onlyChanged If true, only return values that have changed since object creation.
      * @param bool $recursive   If true, inner entities will be cast as array as well.
+     *
+     * @return array<string, mixed>
      */
     public function toRawArray(bool $onlyChanged = false, bool $recursive = false): array
     {
@@ -370,8 +375,6 @@ public function syncOriginal()
      * Checks a property to see if it has changed since the entity
      * was created. Or, without a parameter, checks if any
      * properties have changed.
-     *
-     * @param string|null $key class property
      */
     public function hasChanged(?string $key = null): bool
     {
@@ -500,7 +503,9 @@ private function normalizeValue(mixed $data): mixed
     }
 
     /**
-     * Set raw data array without any mutations
+     * Set raw data array without any mutations.
+     *
+     * @param array<string, mixed> $data
      *
      * @return $this
      */
@@ -514,7 +519,7 @@ public function injectRawData(array $data)
     }
 
     /**
-     * Set raw data array without any mutations
+     * Set raw data array without any mutations.
      *
      * @return $this
      *
@@ -527,28 +532,28 @@ 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.
+     * and returns the DB column name, if any, or the original property name.
      *
-     * @return string db column name
+     * @return string Database column name.
      */
     protected function mapProperty(string $key)
     {
         if ($this->datamap === []) {
             return $key;
         }
 
-        if (! empty($this->datamap[$key])) {
+        if (array_key_exists($key, $this->datamap) && $this->datamap[$key] !== '') {
             return $this->datamap[$key];
         }
 
         return $key;
     }
 
     /**
-     * Converts the given string|timestamp|DateTime|Time instance
+     * Converts the given string|timestamp|DateTimeInterface|Time instance
      * into the "CodeIgniter\I18n\Time" object.
      *
-     * @param DateTime|float|int|string|Time $value
+     * @param DateTimeInterface|float|int|string|Time $value
      *
      * @return Time
      *
@@ -568,7 +573,7 @@ protected function mutateDate($value)
      * @param string                     $attribute Attribute name
      * @param string                     $method    Allowed to "get" and "set"
      *
-     * @return array|bool|float|int|object|string|null
+     * @return array<int|string, mixed>|bool|float|int|object|string|null
      *
      * @throws CastException
      */
@@ -581,9 +586,9 @@ protected function castAs($value, string $attribute, string $method = 'get')
     }
 
     /**
-     * Support for json_encode()
+     * Support for json_encode().
      *
-     * @return array
+     * @return array<string, mixed>
      */
     #[ReturnTypeWillChange]
     public function jsonSerialize()
@@ -592,7 +597,7 @@ public function jsonSerialize()
     }
 
     /**
-     * Change the value of the private $_cast property
+     * Change the value of the private $_cast property.
      *
      * @return bool|Entity
      */
@@ -616,7 +621,7 @@ public function cast(?bool $cast = null)
      *  $this->my_property = $p;
      *  $this->setMyProperty() = $p;
      *
-     * @param array|bool|float|int|object|string|null $value
+     * @param array<int|string, mixed>|bool|float|int|object|string|null $value
      *
      * @return void
      *
@@ -667,11 +672,9 @@ public function __set(string $key, $value = null)
      *  $p = $this->my_property
      *  $p = $this->getMyProperty()
      *
-     * @return array|bool|float|int|object|string|null
+     * @return array<int|string, mixed>|bool|float|int|object|string|null
      *
      * @throws Exception
-     *
-     * @params string $key class property
      */
     public function __get(string $key)
     {