README

Fluid

一个基于著名的 Laravel 的 Fluent 和 Eloquent Model 类的灵活类。

Fluid 允许您将类作为属性（或数组键）的集合灵活操作，同时允许简单序列化并隐藏敏感数据供用户使用。

安装

启动 composer 并将其要求到您的项目中。

composer require darkghosthunter/fluid

否则，您可以将其作为 ZIP 文件下载，并在您的代码中手动要求

<?php

require_once 'path/to/fluid/Fluid.php';
require_once 'path/to/fluid/Concerns/HasArrayAccess.php';
require_once 'path/to/fluid/Concerns/HidesAttributes.php';
require_once 'path/to/fluid/Concerns/HasInstanceHelpers.php';

// Optionally, these two together too
require_once 'path/to/fluid/FluidFillable.php';
require_once 'path/to/fluid/Exceptions/InvalidAttributeException.php';

用法

Fluid 类是一个可以作为普通对象或数组访问的类。它可以序列化为数组、字符串或 JSON。

您可以使用常规方式实例化 Fluid，也可以使用 make()

<?php

use DarkGhostHunter\Fluid\Fluid;

$emptyFluid = new Fluid;

$fluid = new Fluid(['foo' => 'bar']);

$otherFluid = Fluid::make(['foo' => 'bar']);

$otherEmptyFluid = Fluid::make();

如果您需要从 JSON 字符串创建实例，也可以使用 fromJson()

<?php

use DarkGhostHunter\Fluid\Fluid;

$fluid = Fluid::fromJson('"{"foo":"bar"}"');

echo $fluid->foo; // 'bar'

为了完全安全地使用，这些静态辅助方法将返回扩展了 Fluid 的类实例而不是基类。因此使用 Oil::make() 将返回 Oil 的实例。

<?php

use DarkGhostHunter\Fluid\Fluid;

class Water extends Fluid
{
    // ...
}

$water = Water::make();

get_class($water); // 'Water'

重写静态辅助方法

Fluid 使用 __callStatic 的魔法来创建新的实例。在以前的版本中，您不能使用自己的逻辑覆盖静态方法，但现在可以了。

<?php

use DarkGhostHunter\Fluid\Fluid;

class Water extends Fluid
{
    /**
     * My Custom "Make" static method
     * 
     * @return \DarkGhostHunter\Fluid\Fluid|string
     */
    public static function make()
    {
        return 'My Custom Logic';
    }
}

echo Water::make(); // 'My Custom Logic'

属性

每个属性都位于一个名为 $attributes 的受保护数组中，并且这些属性都可以像属性或数组一样设置。

<?php

use DarkGhostHunter\Fluid\Fluid;

$fluid = new Fluid(['foo' => 'bar']);

$fluid->foo = 'notBar';
$fluid['baz'] = 'qux';

echo $fluid->foo; // 'notBar';
echo $fluid['baz']; // 'qux'

echo $fluid['thisAttributeDoesNotExists']; // null
echo $fluid->thisAlsoDoesNotExists; // null

为了方便起见，如果属性或数组键不存在，它将返回 null。

序列化

序列化意味着将类转换为另一种表示形式，如数组或字符串。

要将数组序列化，请使用 toArray() 方法。

<?php 

use DarkGhostHunter\Fluid\Fluid;

$fluid = new Fluid(['foo' => 'bar']);

$array = $fluid->toArray();

echo $fluid['foo']; // 'bar'

由于没有使用 (array)$fluid 的魔法，因此后者将序列化每个属性，因此为了避免这种情况。

使用 toJson() 方法将序列化为字符串，输出 JSON。

<?php 

use DarkGhostHunter\Fluid\Fluid;

$fluid = new Fluid(['foo' => 'bar']);

$json = (string)$fluid;
$moreJson = $fluid->toJson();

echo $json; // "{"foo":"bar"}"
echo $moreJson; // "{"foo":"bar"}"

从序列化中隐藏属性

有时隐藏属性以便于序列化很有用，例如应用程序密钥、API 密钥、用户凭证或证书位置。

您可以使用 shouldHide() 方法启用此功能，或者在扩展 Fluid 时将 $shouldHide 设置为 false。

<?php

use DarkGhostHunter\Fluid\Fluid;

class Water extends Fluid
{
    /**
     * Attributes to hide on serialization
     *
     * @var array
     */
    protected $hidden;
    
    /**
     * Should hide attributes on serialization
     *
     * @var bool
     */
    protected $shouldHide = true;
    
    // ...
}

$fluid = new Fluid;

$fluid->shouldHide();

在 $hidden 属性中设置要隐藏的属性。或者，您可以在实例化后使用 setHidden() 方法。

<?php 

use DarkGhostHunter\Fluid\Fluid;

$fluid = new Fluid(['foo' => 'bar', 'baz' => 'qux']);

$fluid->setHidden(['baz']);

$fluid->shouldHide();

echo $fluid->baz; // 'qux'
echo $fluid['baz']; // 'qux'

print_r($fluid->toArray()); // Array( ['foo' => 'bar'] )
echo (string)$fluid; // "{"foo":"bar"}"

可填充

有时您想确保用户不要填写超过一些预先设定的属性。您可以使用 FluidFillable 类来强制执行此操作。

您可以将允许设置的属性放入 $fillable 数组中，或者在之后使用 setFillable()。

<?php

use DarkGhostHunter\Fluid\FluidFillable;

$fluid = new FluidFillable(['foo' => 'bar', 'baz' => 'qux']);

$fluid->setFillable(['foo', 'baz']);

$fluid->alpha = 'bravo';

/*
 * [!] DarkGhostHunter\Fluid\Exceptions\InvalidAttributeException
 * 
 * Attribute [foo] in not set as fillable in FluidFillable.
 */

当尝试设置类中不可填充的属性时，用户将收到一个 InvalidAttributeException 异常。

您可以使用此功能来强制开发者在实例中仅允许某些属性，这样您就可以在应用处理完实例后取消任何过滤逻辑。

许可证

此软件包由 MIT 许可证 许可。