[Entity] Misleading or misunderstood documentation

[Turecky]

PHP Version

8.3

CodeIgniter4 Version

4.4.5

CodeIgniter4 Installation Method

Composer (using codeigniter4/appstarter)

Which operating systems have you tested for this bug?

Linux

Which server did you use?

cli-server (PHP built-in webserver)

Database

SQLite3

What happened?

In documentation about Entities in section Create Model is sentence 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.
It is assumed that the results always bee as set in $returnType for example protected $returnType = UserEntity::class;

Steps to Reproduce

Create database table users:

CREATE TABLE `users` (
                id INTEGER PRIMARY KEY,
                user_name TEXT NOT NULL,
                user_full_name TEXT NOT NULL,
                password TEXT NOT NULL,
                email TEXT NOT NULL,
                created_at TEXT,
                updated_at TEXT,
                deleted_at TEXT
            );

Fill table with some random data to run queries.

Create controller, model and entity using php spark make:....
In UserEntity add few properties:

private $userName;
private $fullName;
private $password;
private $email;

In UserModel set protected $returnType = UserEntity::class;
In UserContoller create index to display results.
In Index function

  public function index()
  {
    $uModel = new UserModel();
    $user = $uModel->find(1);
    d($user->userName); //Display user name
    d($user->user_name); //Display user name
    d($user->getUserName()); //Cause error: Call to undefined method App\Entities\UserEntity::getUserName()
   }

In UserEntity create set/get method for [get/set]UserName and [get/set]FullName

    private $userName;
    private $fullName;
    public function setUserName($name)
    {
        $this->userName = $name;
        return $this;
    }
    
    public function getUserName() :?string
    {
        return $this->userName;
    }

    public function setFullName($name)
    {
        $this->fullName = $name;
        return $this;
    }
    public function getFullName()
    {
        return $this->fullName;
    }

Index method return:

d($user->user_name); // null
d($user->userName); // null
d($user->getUserName()); // null

In UserContoller swith from $user = $uModel->find(6); to $user = $uModel->find(1);
In UserModel create method:

public function getByID($id)
    {
        $q = $this->db->table($this->table)->where('id',$id)->get();

        // Result example 1
        //return $q->getRow();
        // Result example 2
        // return $q->getRow(0, UserEntity::class);
        // Result example 3
        // return $q->getCustomRowObject(0, UserEntity::class);      
        // Result example 4
        // $r = $q->getRowArray();
        // $u = new UserEntity();
        // $u->fill($r);
        // return $u;
    }

Result example 1: Undefined property: stdClass::$userName
Result example 2: userName still null
Result example 3: userName still null
Result example 4:

d($user->user_name); // field is filled with user name
d($user->userName);  // field is filled with user name
d($user->getUserName()); // field is filled with user name

When in controller call $user->fullName or $user->getFullName() result is NULL.
I added datamap as describer in doc

protected $datamap = [
        // property_name => db_column_name
        'userName' => 'user_name',
        'fullName' => 'user_full_name',
        'password' => 'password',
        'email' => 'email',
    ];

Result was no changed. But when i change places key and value

protected $datamap = [
        // db_column_name => property_name
        'user_name' => 'userName',
        'user_full_name' => 'fullName',
        'password' => 'password',
        'email' => 'email',
    ];

Then method $user->getFullName() in contoller return result as expected

Expected Output

Return UserEntity when returning result from model

Anything else?

No response

[kenjis]

Excuse me, but what do you want to do?

In UserEntity add few properties:

private $userName;
private $fullName;
private $password;
private $email;

Why do you need to add properties in the Entity?

[Turecky]

datamap chnage property naming to match "bussines logic" not the database and because PHP 8.3 do not like undefined properties.

[kenjis]

CodeIgniter Entity does not have real class properties for database columns.
It stores all data in the attributes property.

If you want to use class properties for database columns, you should not use the Entity.
The Entity is optional. You don't need to use it.

[Turecky]

I know the use of Entity is optional.
If shorten my first long description then if use Entity there is difference when getting results.
If in model define $returnType as Entity and in controller use find() and fildAll methods result object is Entity.
But when define custom methods in model and build query, then after call ..->getResult() or ->getRow() you do not get expected result object as defined in $returnType.

[paulbalandan]

If I understood correctly what you mean, here are the steps you did:

1. You create a model with $returnType set to an Entity class, for example UserEntity.
2. In controller, you call the model and get a record, for example:

$user = new UserModel();
dd($user->find(1));

3. In above, you expect the result to be an Entity. That's correct.
4. I'm not sure what you mean by "build query", but if you yourself will call ->getResult() or ->getRow() or ->getFirstRow() you expect it to be an Entity also?
5. If such the case, then you have them wrong, when using those query methods, you must supply the return type. Otherwise, the default object return type will be passed which is equivalent of giving stdClass result.

[Turecky]

In model if create method getByID

public function getByID($id)
    {
        $query = $this->db->table($this->table)->where('id',$id)->get();

        // Result example 1
        return $q->getRow(); // Will return stdClass
        // Result example 2
        return $q->getCustomRowObject(0, UserEntity::class); // Will return UserEntity
        // Result example 3
        $r = $q->getRowArray();
        $u = new UserEntity();
        $u->fill($r);
        return $u; // Will return UserEntity
    }

In example 2 i was expect to result will be the same as in example 3 but result is not the same.
In example 2 if try to get email i'm getting Undefined property: App\Entities\UserEntity::$email
But if use example 3 result i can get email and have no errors.

[paulbalandan]

Okay, for example 1, you need to do the same with ->getCustomRowObject, that is you need to ->getRow(0, UserEntity::class).

In example 2 i was expect to result will be the same as in example 3 but result is not the same.

Can you show a dump of example 2 and 3 results?

[Turecky]

Example 2 var_dump($user)

object(App\Entities\UserEntity)#89 (8) {
  ["datamap":protected]=>
  array(4) {
    ["user_name"]=>
    string(8) "userName"
    ["user_full_name"]=>
    string(8) "fullName"
    ["password"]=>
    string(8) "password"
    ["email"]=>
    string(5) "email"
  }
  ["dates":protected]=>
  array(3) {
    [0]=>
    string(10) "created_at"
    [1]=>
    string(10) "updated_at"
    [2]=>
    string(10) "deleted_at"
  }
  ["casts":protected]=>
  array(0) {
  }
  ["castHandlers":protected]=>
  array(0) {
  }
  ["defaultCastHandlers":"CodeIgniter\Entity\Entity":private]=>
  array(15) {
    ["array"]=>
    string(33) "CodeIgniter\Entity\Cast\ArrayCast"
    ["bool"]=>
    string(35) "CodeIgniter\Entity\Cast\BooleanCast"
    ["boolean"]=>
    string(35) "CodeIgniter\Entity\Cast\BooleanCast"
    ["csv"]=>
    string(31) "CodeIgniter\Entity\Cast\CSVCast"
    ["datetime"]=>
    string(36) "CodeIgniter\Entity\Cast\DatetimeCast"
    ["double"]=>
    string(33) "CodeIgniter\Entity\Cast\FloatCast"
    ["float"]=>
    string(33) "CodeIgniter\Entity\Cast\FloatCast"
    ["int"]=>
    string(35) "CodeIgniter\Entity\Cast\IntegerCast"
    ["integer"]=>
    string(35) "CodeIgniter\Entity\Cast\IntegerCast"
    ["int-bool"]=>
    string(35) "CodeIgniter\Entity\Cast\IntBoolCast"
    ["json"]=>
    string(32) "CodeIgniter\Entity\Cast\JsonCast"
    ["object"]=>
    string(34) "CodeIgniter\Entity\Cast\ObjectCast"
    ["string"]=>
    string(34) "CodeIgniter\Entity\Cast\StringCast"
    ["timestamp"]=>
    string(37) "CodeIgniter\Entity\Cast\TimestampCast"
    ["uri"]=>
    string(31) "CodeIgniter\Entity\Cast\URICast"
  }
  ["attributes":protected]=>
  array(8) {
    ["id"]=>
    int(6)
    ["user_name"]=>
    string(13) "nathen.feeney"
    ["user_full_name"]=>
    string(12) "Owen Farrell"
    ["password"]=>
    string(9) "[FQZ&35Kb"
    ["email"]=>
    string(20) "kfeeney@collier.info"
    ["created_at"]=>
    NULL
    ["updated_at"]=>
    NULL
    ["deleted_at"]=>
    NULL
  }
  ["original":protected]=>
  array(8) {
    ["id"]=>
    int(6)
    ["user_name"]=>
    string(13) "nathen.feeney"
    ["user_full_name"]=>
    string(12) "Owen Farrell"
    ["password"]=>
    string(9) "[FQZ&35Kb"
    ["email"]=>
    string(20) "kfeeney@collier.info"
    ["created_at"]=>
    NULL
    ["updated_at"]=>
    NULL
    ["deleted_at"]=>
    NULL
  }
  ["_cast":"CodeIgniter\Entity\Entity":private]=>
  bool(true)
}

Example 3 var_rump($user)

object(App\Entities\UserEntity)#89 (14) {
  ["datamap":protected]=>
  array(4) {
    ["user_name"]=>
    string(8) "userName"
    ["user_full_name"]=>
    string(8) "fullName"
    ["password"]=>
    string(8) "password"
    ["email"]=>
    string(5) "email"
  }
  ["dates":protected]=>
  array(3) {
    [0]=>
    string(10) "created_at"
    [1]=>
    string(10) "updated_at"
    [2]=>
    string(10) "deleted_at"
  }
  ["casts":protected]=>
  array(0) {
  }
  ["castHandlers":protected]=>
  array(0) {
  }
  ["defaultCastHandlers":"CodeIgniter\Entity\Entity":private]=>
  array(15) {
    ["array"]=>
    string(33) "CodeIgniter\Entity\Cast\ArrayCast"
    ["bool"]=>
    string(35) "CodeIgniter\Entity\Cast\BooleanCast"
    ["boolean"]=>
    string(35) "CodeIgniter\Entity\Cast\BooleanCast"
    ["csv"]=>
    string(31) "CodeIgniter\Entity\Cast\CSVCast"
    ["datetime"]=>
    string(36) "CodeIgniter\Entity\Cast\DatetimeCast"
    ["double"]=>
    string(33) "CodeIgniter\Entity\Cast\FloatCast"
    ["float"]=>
    string(33) "CodeIgniter\Entity\Cast\FloatCast"
    ["int"]=>
    string(35) "CodeIgniter\Entity\Cast\IntegerCast"
    ["integer"]=>
    string(35) "CodeIgniter\Entity\Cast\IntegerCast"
    ["int-bool"]=>
    string(35) "CodeIgniter\Entity\Cast\IntBoolCast"
    ["json"]=>
    string(32) "CodeIgniter\Entity\Cast\JsonCast"
    ["object"]=>
    string(34) "CodeIgniter\Entity\Cast\ObjectCast"
    ["string"]=>
    string(34) "CodeIgniter\Entity\Cast\StringCast"
    ["timestamp"]=>
    string(37) "CodeIgniter\Entity\Cast\TimestampCast"
    ["uri"]=>
    string(31) "CodeIgniter\Entity\Cast\URICast"
  }
  ["attributes":protected]=>
  array(8) {
    ["id"]=>
    NULL
    ["user_name"]=>
    NULL
    ["user_full_name"]=>
    NULL
    ["email"]=>
    NULL
    ["password"]=>
    string(9) "[FQZ&35Kb"
    ["created_at"]=>
    NULL
    ["updated_at"]=>
    NULL
    ["deleted_at"]=>
    NULL
  }
  ["original":protected]=>
  array(7) {
    ["id"]=>
    NULL
    ["user_name"]=>
    NULL
    ["user_full_name"]=>
    NULL
    ["email"]=>
    NULL
    ["password"]=>
    NULL
    ["created_at"]=>
    NULL
    ["updated_at"]=>
    NULL
  }
  ["_cast":"CodeIgniter\Entity\Entity":private]=>
  bool(true)
  ["id":"App\Entities\UserEntity":private]=>
  int(6)
  ["userName":"App\Entities\UserEntity":private]=>
  string(13) "nathen.feeney"
  ["fullName":"App\Entities\UserEntity":private]=>
  string(12) "Owen Farrell"
  ["user_full_name":"App\Entities\UserEntity":private]=>
  NULL
  ["password":"App\Entities\UserEntity":private]=>
  NULL
  ["email":protected]=>
  string(20) "kfeeney@collier.info"
}

For example 3 added private properties for Entity to work with them and not DB field names.

[kenjis]

@Turecky

In example 2 if try to get email i'm getting Undefined property: App\Entities\UserEntity::$email
But if use example 3 result i can get email and have no errors.

Because you called fill() in the example 3.

In my opinion, Entity is strongly opinionated, and if you use it, you must follow the design of the Entity.

1. You cannot have PHP's class properties for the columns.
2. It stores raw data from the database in the attributes property.