README

Data\DataObject

Data\DataObject 是一个用于存储数据但允许您通过模拟PHP处理类属性的方式访问数据的类。而不是在类中显式声明属性，Data\DataObject 将类的虚拟属性存储在一个私有的内部数组中。具体属性仍然可以定义，但这些属性与数据是分开的。

构造

新 Data\DataObject 对象的构造函数可以可选地接受一个数组或一个对象。数组的关键字或对象的属性将被绑定到 Data\DataObject 对象的属性上。

use Joomla\Data\DataObject;

// Create an empty object.
$object1 = new DataObject;

// Create an object with data. You can use an array or another object.
$data = array(
    'foo' => 'bar',
);

$object2 = new DataObject($data);

// The following should echo "bar".
echo $object2->foo;

通用用法

Data\DataObject 包含魔法获取器和设置器，以提供对内部属性存储的访问，就像它们是类中显式声明的属性一样。

bind 方法允许将现有的数组或对象注入到 Data\DataObject 对象中。

dump 方法获取 Data\DataObject 对象属性的简单 stdClass 版本。它还将支持递归到指定级别，默认为 3，深度为 0 将返回一个包含所有属性的原始形式的 stdClass 对象。请注意，dump 方法将只返回绑定和魔法方法设置的虚拟属性。它不会包括在类中定义的任何具体属性。

JsonSerializable 接口得到了实现。此方法代理到 dump 方法（默认递归深度为 3）。请注意，此接口仅在 PHP 5.4 中隐式生效，因此为 PHP 5.3 编写的任何代码都需要在传递到 json_encode 之前显式使用 jsonSerialize 或 dump 方法。

Data\DataObject 类还实现了 IteratorAggregate 接口，因此可以轻松地在 foreach 语句中使用。

use Joomla\Data\DataObject;

// Create an empty object.
$object = new DataObject;

// Set a property.
$object->foo = 'bar';

// Get a property.
$foo = $object->foo;

// Binding some new data to the object.
$object->bind(array('goo' => 'car');

// Get a plain object version of the data object.
$stdClass = $object->dump();

// Get a property with a default value if it is not already set.
$foo = $object->foo ?: 'The default';

// Iterate over the properties as if the object were a real array.
foreach ($object as $key => $value)
{
    echo "\n$key = $value";
}

if (version_compare(PHP_VERSION, '5.4') >= 0)
{
	// PHP 5.4 is aware of the JsonSerializable interface.
	$json = json_encode($object);
}
else
{
	// Have to do it the hard way to be compatible with PHP 5.3.
	$json = json_encode($object->jsonSerialize());
}

Data\DataSet

Data\DataSet 是一个集合类，允许开发者在典型PHP数组中操作 Data\DataObject 对象列表（Data\DataSet 实现了 ArrayAccess、Countable 和 Iterator 接口）。

构造

典型的 Data\DataSet 对象将通过在构造函数中传递 Data\DataObject 对象的数组来实例化。

use Joomla\Data\DataObject;
use Joomla\Data\DataSet;

// Create an empty object.
$players = new DataSet(
    array(
        new DataObject(array('race' => 'Elf', 'level' => 1)),
        new DataObject(array('race' => 'Chaos Dwarf', 'level' => 2)),
    )
);

通用用法

可以使用 offsetSet 和 offsetUnset 方法或使用PHP数组命名法来操纵数组元素。

Data\DataSet 类中的魔法 __get 方法类似于“获取列”方法。它将为列表中的所有对象返回属性值的数组。

魔法 __set 方法类似，类似于“设置列”方法。它将为列表中的所有对象的属性设置一个值。

clear 方法将清除数据集中的所有对象。

keys 方法将返回存储在集合中的所有对象的键。它类似于PHP数组上的 array_keys 函数。

use Joomla\Data\DataObject;

// Add a new element to the end of the list.
$players[] => new DataObject(array('race' => 'Skaven', 'level' => 2));

// Add a new element with an associative key.
$players['captain'] => new DataObject(array('race' => 'Human', 'level' => 3));

// Get a keyed element from the list.
$captain = $players['captain'];

// Set the value of a property for all objects. Upgrade all players to level 4.
$players->level = 4;

// Get the value of a property for all object and also the count (get the average level).
$average = $players->level / count($players);

// Clear all the objects.
$players->clear();

Data\DataSet 支持操作列表中所有对象的魔术方法。调用任意方法将遍历对象列表，检查每个对象是否有一个可调用的方法与调用的方法同名。在这种情况下，将返回值组装成一个数组，形成在 Data\DataSet 对象上调用该方法时的返回值。原始对象的键在结果数组中保持不变。

use Joomla\Data\DataObject;
use Joomla\Data\DataSet;

/**
 * A custom data object.
 *
 * @since  1.0
 */
class PlayerObject extends DataObject
{
    /**
     * Get player damage.
     *
     * @return  integer  The amount of damage the player has received.
     *
     * @since   1.0
     */
    public function hurt()
    {
        return (int) $this->maxHealth - $this->actualHealth;
    }
}

$players = new DataSet(
    array(
        // Add a normal player.
        new PlayerObject(array('race' => 'Chaos Dwarf', 'level' => 2,
        	'maxHealth' => 40, 'actualHealth' => '32')),
        // Add an invincible player.
        new PlayerObject(array('race' => 'Elf', 'level' => 1)),
    )
);

// Get an array of the hurt players.
$hurt = $players->hurt();

if (!empty($hurt))
{
    // In this case, $hurt = array(0 => 8);
    // There is no entry for the second player
    // because that object does not have a "hurt" method.
    foreach ($hurt as $playerKey => $player)
    {
        // Do something with the hurt players.
    }
};

Data\DumpableInterface

Data\DumpableInterface 是一个接口，它定义了一个用于将对象的属性以 stdClass 的形式输出（递归或不递归）的 dump 方法。

通过 Composer 安装

将 "joomla/data": "~3.0" 添加到您的 composer.json 文件中的 require 块，然后运行 composer install。

{
	"require": {
		"joomla/data": "~3.0"
	}
}

或者，您可以直接在命令行中运行以下命令

composer require joomla/data "~3.0"

如果您想包含测试源，使用

composer require --prefer-source joomla/data "~3.0"