使用实体类
CodeIgniter 全面支持实体类,同时保持它们的完全可选。它们通常用作存储库模式的一部分,但如果更符合你的需求,也可以直接与 Model 一起使用。
实体用法
本质上,实体类仅仅是一个代表单个数据库行的类。它具有表示数据库列的类属性,并提供任何其他方法来实现该行的业务逻辑。
备注
为了便于理解,这里的解释是基于使用数据库的情况。然而,实体也可以用于不来自数据库的数据。
然而,关键是它不知道如何持久化自己。这是模型或存储库类的责任。这样,如果你需要保存对象的方式发生了任何更改,你不需要更改整个应用程序中该对象的使用方式。
这使得在快速原型阶段使用 JSON 或 XML 文件存储对象成为可能,然后在概念证明有效时轻松切换到数据库。
让我们来看一个非常简单的用户实体示例,并介绍如何使用它以使事情变得清楚。
假设你有一个名为 users
的数据库表,具有以下模式:
id - integer
username - string
email - string
password - string
created_at - datetime
重要
attributes
是一个保留字,供内部使用。如果你将其用作列名,实体将无法正确工作。
创建实体类
现在创建一个新的实体类。由于没有默认的位置来存储这些类,也不符合现有的目录结构,所以在 app/Entities 中创建一个新目录。在 app/Entities/User.php 中创建实体本身。
<?php
namespace App\Entities;
use CodeIgniter\Entity\Entity;
class User extends Entity
{
// ...
}
就这么简单,尽管我们马上会让它更有用。
创建模型
首先在 app/Models/UserModel.php 创建模型,以便我们可以与其交互:
<?php
namespace App\Models;
use CodeIgniter\Model;
class UserModel extends Model
{
protected $table = 'users';
protected $allowedFields = [
'username', 'email', 'password',
];
protected $returnType = \App\Entities\User::class;
protected $useTimestamps = true;
}
模型在数据库中使用 users
表进行所有活动。
我们设置了 $allowedFields
属性来包含所有我们希望外部类可以更改的字段。id
、created_at
和 updated_at
字段由类或数据库自动处理,所以我们不希望更改这些字段。
最后,我们将我们的实体类设置为 $returnType
。这确保了模型中所有内置的方法在从数据库返回行时,将返回我们的 User 实体类的实例,而不是像通常那样返回对象或数组。
备注
当然,如果你向模型添加自定义方法,你必须实现它,以便返回 $returnType
的实例。
使用实体类
现在各部分就绪,你将像使用任何其他类一样使用实体类:
<?php
$user = $userModel->find($id);
// Display
echo $user->username;
echo $user->email;
// Updating
unset($user->username);
if (! isset($user->username)) {
$user->username = 'something new';
}
$userModel->save($user);
// Create
$user = new \App\Entities\User();
$user->username = 'foo';
$user->email = 'foo@example.com';
$userModel->save($user);
你可能已经注意到, User
类还没有为列设置任何属性,但你仍然可以像它们是公共属性一样访问它们。基类 CodeIgniter\Entity\Entity
会替你处理这些,以及提供使用 isset()
检查属性,或 unset()
属性的能力,并跟踪对象创建或从数据库中提取后哪些列发生了更改。
备注
实体类在内部的类属性 $attributes
中存储数据。
当 User 传递给模型的 save()
方法时,它会自动读取属性并保存 $allowedFields
属性中列出的任何更改。它还知道是创建新行还是更新现有行。
备注
当我们调用 insert()
时,实体的所有值都传递给该方法,但当我们调用 update()
时,只传递更改的值。
快速填充属性
实体类还提供了一个方法 fill()
,允许你将键/值对数组推入类中并填充类属性。数组中的任何属性都将在实体上设置。但是,通过模型保存时,实际上只会将 $allowedFields
中的字段保存到数据库,所以你可以在实体上存储其他数据,而不必担心错误地保存多余的字段。
<?php
$data = $this->request->getPost();
$user = new \App\Entities\User();
$user->fill($data);
$userModel->save($user);
你也可以在构造函数中传递数据,数据将在实例化过程中通过 fill()
方法传递。
<?php
$data = $this->request->getPost();
$user = new \App\Entities\User($data);
$userModel->save($user);
批量访问属性
实体类有两个方法可以将所有可用属性提取到一个数组中:toArray()
和 toRawArray()
。使用原始版本将绕过魔术“getter”方法和转换。两个方法都可以接受一个布尔第一个参数,指定返回的值是否应该由更改的那些过滤,以及一个布尔最后一个参数,以使方法递归,以防出现嵌套的实体。
处理业务逻辑
虽然上面的例子很方便,但它们没有帮助执行任何业务逻辑。基本实体类实现了一些智能的 __get()
和 __set()
方法,这些方法将检查特殊方法并使用那些方法,而不是直接使用属性,从而允许你执行任何需要的业务逻辑或数据转换。
这是一个更新的用户实体,提供了一些如何使用它的示例:
<?php
namespace App\Entities;
use CodeIgniter\Entity\Entity;
use CodeIgniter\I18n\Time;
class User extends Entity
{
public function setPassword(string $pass)
{
$this->attributes['password'] = password_hash($pass, PASSWORD_BCRYPT);
return $this;
}
public function setCreatedAt(string $dateString)
{
$this->attributes['created_at'] = new Time($dateString, 'UTC');
return $this;
}
public function getCreatedAt(string $format = 'Y-m-d H:i:s')
{
// Convert to CodeIgniter\I18n\Time object
$this->attributes['created_at'] = $this->mutateDate($this->attributes['created_at']);
$timezone = $this->timezone ?? app_timezone();
$this->attributes['created_at']->setTimezone($timezone);
return $this->attributes['created_at']->format($format);
}
}
首先要注意我们添加的方法的名称。对于每一个,类都期望 snake_case 列名转换为 PascalCase,并分别以 set
或 get
为前缀。然后,每当你使用直接语法(即 $user->email
)设置或检索类属性时,就会自动调用这些方法。除非你希望它们从其他类访问,否则这些方法不需要是公共的。例如, created_at
类属性将通过 setCreatedAt()
和 getCreatedAt()
方法访问。
备注
这只适用于试图从类外部访问属性时。类内部的任何方法必须直接调用 setX()
和 getX()
方法。
在 setPassword()
方法中,我们确保密码始终被散列。
在 setCreatedAt()
中,我们将从模型接收的字符串转换为 DateTime 对象,确保我们的时区为 UTC,以便轻松转换查看者当前的时区。在 getCreatedAt()
中,它将时间转换为应用程序当前时区的格式化字符串。
虽然相当简单,但这些例子表明,使用实体类可以以非常灵活的方式执行业务逻辑和创建愉快使用的对象。
<?php
// Auto-hash the password - both do the same thing
$user->password = 'my great password';
$user->setPassword('my great password');
特殊的 Getter/Setter
在 4.4.0 版本加入.
例如,如果你的实体的父类已经定义了一个名为 getParent()
的方法,并且你的实体还有一个名为 parent
的列,当你尝试在实体类中为 getParent()
方法添加业务逻辑时,该方法已经被定义了。
在这种情况下,你可以使用特殊的 getter/setter。而不是使用 getX()
/setX()
,使用 _getX()
/_setX()
。
在上面的示例中,如果你的实体有一个名为 _getParent()
的方法,当你获取 $entity->parent
时将使用该方法,当你设置 $entity->parent
时将使用 _setParent()
方法。
数据映射
在你的职业生涯的多个时间点上,你会遇到应用程序使用的情况发生变化,数据库中的原始列名不再有意义的情况。或者你发现你的编程风格更喜欢驼峰式类属性,但你的数据库模式要求使用蛇形名称。这些情况可以通过实体类的数据映射功能轻松处理。
举个例子,假设你有在整个应用程序中使用的简化的 User 实体:
<?php
namespace App\Entities;
use CodeIgniter\Entity\Entity;
class User extends Entity
{
protected $attributes = [
'id' => null,
'name' => null, // Represents a username
'email' => null,
'password' => null,
'created_at' => null,
'updated_at' => null,
];
}
你的老板过来告诉你现在没有人再使用用户名了,所以你们要切换到只使用电子邮件登录。但他们确实希望对应用程序进行一些个性化,所以他们现在想要你把 name
字段改为代表用户的全名,而不仅仅是目前的用户名。为了保持数据库的整洁和保证继续有意义,你制作了一个迁移来将 name
字段重命名为 full_name
,以获得清晰度。
无视这个例子有多牵强,我们现在对 User 类有两个选择。我们可以将类属性从 $name
修改为 $full_name
,但这将需要整个应用程序的更改。或者,我们可以简单地将数据库中的 full_name
列映射到 $name
属性,就完成了实体的更改:
<?php
namespace App\Entities;
use CodeIgniter\Entity\Entity;
class User extends Entity
{
protected $attributes = [
'id' => null,
'full_name' => null, // In the $attributes, the key is the db column name
'email' => null,
'password' => null,
'created_at' => null,
'updated_at' => null,
];
protected $datamap = [
// property_name => db_column_name
'name' => 'full_name',
];
}
通过将新的数据库名称添加到 $datamap
数组中,我们可以告诉类数据库列应该通过哪个类属性访问。数组的键是要映射到的类属性,数组中的值是数据库中的列名称。
在这个例子中,当模型在 User 类上设置 full_name
字段时,它实际上会将该值分配给类的 $name
属性,所以它可以通过 $user->name
设置和检索。该值仍然可以通过原始的 $user->full_name
访问,这也是模型将数据取回并保存到数据库所需的。但是, unset()
和 isset()
只适用于映射的属性 $user->name
,而不适用于数据库列名 $user->full_name
。
备注
当你使用数据映射时,你必须为数据库列名定义 set*()
和 get*()
方法。在这个例子中,你必须定义 setFullName()
和 getFullName()
。
变更器
日期变更器
默认情况下,当设置或检索名称为 created_at、updated_at 或 deleted_at 的字段时,实体类会将其转换为 时间 实例。Time 类以不可变的本地化方式提供了大量有用的方法。
你可以通过将名称添加到 $dates
属性来定义哪些属性会自动转换:
<?php
namespace App\Entities;
use CodeIgniter\Entity\Entity;
class User extends Entity
{
protected $dates = ['created_at', 'updated_at', 'deleted_at'];
}
现在,每当设置这些属性中的任何一个时,它都会使用应用程序的当前时区(在 app/Config/App.php 中设置)转换为 Time 实例:
<?php
$user = new \App\Entities\User();
// Converted to Time instance
$user->created_at = 'April 15, 2017 10:30:00';
// Can now use any Time methods:
echo $user->created_at->humanize();
echo $user->created_at->setTimezone('Europe/London')->toDateString();
属性转换
你可以使用 $casts
属性指定实体中的属性应该转换为常见的数据类型。
该选项应该是一个数组,其中键是类属性的名称,值是应该转换为的数据类型。
属性转换影响读取(获取)和写入(设置),但某些类型只影响读取(获取)。
标量类型转换
属性可以转换为以下任何数据类型: integer、float、double、string、boolean、object、array、datetime、timestamp、uri 和 int-bool。 在类型的开头加上问号,将属性标记为可为空,例如 ?string、?integer。
备注
int-bool 可以从 v4.3.0 开始使用。
例如,如果你有一个带有 is_banned
属性的 User 实体,可以将其转换为布尔值:
<?php
namespace App\Entities;
use CodeIgniter\Entity\Entity;
class User extends Entity
{
protected $casts = [
'is_banned' => 'boolean',
'is_banned_nullable' => '?boolean',
];
}
数组/JSON 转换
当转换为以下类型时,数组/JSON 转换特别适用于存储序列化数组或 JSON 的字段:
array 时,它们将自动反序列化,
json 时,它们将自动设置为
json_decode($value, false)
的值,json-array 时,它们将自动设置为
json_decode($value, true)
的值,
当你设置属性的值时。 与可以将属性转换成的其他数据类型不同,
array 转换类型在设置属性时将序列化,
json 和 json-array 转换在设置属性时将使用 json_encode 函数
在该值上:
<?php
namespace App\Entities;
use CodeIgniter\Entity\Entity;
class User extends Entity
{
protected $casts = [
'options' => 'array',
'options_object' => 'json',
'options_array' => 'json-array',
];
}
<?php
$user = $userModel->find(15);
$options = $user->options;
$options['foo'] = 'bar';
$user->options = $options;
$userModel->save($user);
CSV 转换
如果你知道有一个简单值的平面数组,将它们编码为序列化或 JSON 字符串可能比原始结构更复杂。转换为逗号分隔值(CSV)是一个更简单的替代方法,结果是一个使用的空间更少、更容易被人类读取的字符串:
<?php
namespace App\Entities;
use CodeIgniter\Entity\Entity;
class Widget extends Entity
{
protected $casts = [
'colors' => 'csv',
];
}
在数据库中存储为“red,yellow,green”:
<?php
$widget->colors = ['red', 'yellow', 'green'];
备注
CSV 转换使用 PHP 的内部 implode
和 explode
方法,并假设所有值都是安全的不包含逗号的字符串。对于更复杂的数据转换,请尝试 array
或 json
。
自定义转换
你可以为获取和设置数据定义自己的转换类型。
首先你需要为你的类型创建一个处理程序类。 假设这个类将位于 app/Entities/Cast 目录中:
<?php
namespace App\Entities\Cast;
use CodeIgniter\Entity\Cast\BaseCast;
// The class must inherit the CodeIgniter\Entity\Cast\BaseCast class
class CastBase64 extends BaseCast
{
public static function get($value, array $params = [])
{
return base64_decode($value, true);
}
public static function set($value, array $params = [])
{
return base64_encode($value);
}
}
现在你需要注册它:
<?php
namespace App\Entities;
use CodeIgniter\Entity\Entity;
class MyEntity extends Entity
{
// Specify the type for the field
protected $casts = [
'key' => 'base64',
];
// Bind the type to the handler
protected $castHandlers = [
'base64' => Cast\CastBase64::class,
];
}
// ...
$entity->key = 'test'; // dGVzdA==
echo $entity->key; // test
如果在获取或设置值时不需要更改值。那么就不要实现相应的方法:
<?php
namespace App\Entities\Cast;
use CodeIgniter\Entity\Cast\BaseCast;
class CastBase64 extends BaseCast
{
public static function get($value, array $params = [])
{
return base64_decode($value, true);
}
}
参数
在某些情况下,一种类型是不够的。在这种情况下,你可以使用额外的参数。
额外的参数用方括号表示,并以逗号分隔列表,例如 type[param1, param2]
。
<?php
namespace App\Entities;
use CodeIgniter\Entity\Entity;
class MyEntity extends Entity
{
// Define a type with parameters
protected $casts = [
'some_attribute' => 'class[App\SomeClass, param2, param3]',
];
// Bind the type to the handler
protected $castHandlers = [
'class' => 'SomeHandler',
];
}
<?php
namespace App\Entities\Cast;
use CodeIgniter\Entity\Cast\BaseCast;
class SomeHandler extends BaseCast
{
public static function get($value, array $params = [])
{
var_dump($params);
/*
* Output:
* array(3) {
* [0]=>
* string(13) "App\SomeClass"
* [1]=>
* string(6) "param2"
* [2]=>
* string(6) "param3"
* }
*/
}
}
备注
如果强制转换类型标记为 nullable 类型,如 ?bool
,并且传递的值不为 null,那么带有值 nullable
的参数将传递给强制转换类型处理器。
如果强制转换类型有预定义的参数,那么 nullable
将被添加到参数列表的末尾。
检查更改的属性
你可以检查自创建以来实体属性是否发生了更改。唯一的参数是要检查的属性名称:
<?php
$user = new \App\Entities\User();
$user->hasChanged('name'); // false
$user->name = 'Fred';
$user->hasChanged('name'); // true
或者省略参数检查整个实体的更改值:
<?php
$user->hasChanged(); // true