README

这个库不再积极开发。许多其他集合库提供我们需要的绝大多数功能。

仅修复错误。

数组对象

ArrayObject 是一个 PHP 库，它提供了一个轻量级接口，用于流畅地处理数组。

ArrayObject 在 PHP 内置的 array 类型周围提供了一个包装器，包括过滤、检索项的方法，并方便地将单个项和集合视为相同的对象。

这对于处理 API 请求的 JSON 响应特别有用。

此库被 Hyper Http Client 使用，以使从响应中提取数据变得超级直观。

安装

composer require rexlabs/array-object

用法

<?php
require 'vendor/autoload.php';
use Rexlabs\ArrayObject\ArrayObject;

// Initialise from an Array
$obj = ArrayObject::fromArray([...]);

// Initialise from a JSON encoded string
$obj = ArrayObject::fromJson($str);

// Output to array
$arr = $obj->toArray();

// Output to JSON encoded string
$json = $obj->toJson();

以下示例基于以下输入数据。

{
  "books": [
    {
      "id": 1,
      "title": "1984",
      "author": "George Orwell"
    },
    {
      "id": 2,
      "title": "Pride and Prejudice",
      "author": "Jane Austen"
    }
  ]
}

基本用法

$obj->books; // Instance of ArrayObject
$obj->books->pluckArray('author'); // array [ 'George Orwell', 'Jane Austen' ]
$obj->pluckArray('books.author'); // array [ 'George Orwell', 'Jane Austen' ]
$obj->books->count(); // 2
$obj->books->isCollection(); // true
$obj->books[0]; // Instance of ArrayObject
$obj->books[0]->isCollection(); // false
$obj->books[0]->id; // 1

注意：所有方法都能优雅地处理将单个项作为数组处理。

get($key, $default = null)

get() 方法允许您获取属性的值，如果值不存在，则返回默认值。它还支持深度，用 . 表示。

$obj->get('books.0');       // ArrayObject
$obj->get('books.0.title'); // "1984"
$obj->get('books.1.title'); // "Pride and Prejudice"
$obj->get('books.0.missing', 'Default value'); // "Default value"

您还可以使用对象属性语法来获取属性（我们通过重载 __get() 来实现这一点）

$obj->books[0];           // ArrayObject
$obj->books[0]->title;    // "1984"
$obj->books[1]->title;    // "Pride and Prejudice"
$obj->books[0]->missing;  // throws InvalidPropertyException

getRaw($key, $default = null)

当通过 get('some.key') 获取的值是一个数组时，它会被包装成一个 ArrayObject 实例。然而，getRaw() 方法不会对返回值执行任何 '包装'。

$obj->get('books');            // ArrayObject
$obj->getRaw('books');         // (array)
$obj->get('books.0.title');    // "1984"
$obj->getRaw('books.0.title'); // "1984"

set($key, $value, $onlyIfExists = false)

set() 方法允许您使用点符号设置属性。它将自动创建底层的数组结构

$obj->set('some.deep.key', $value);  // Set nested property
$obj->set('some_key', $anotherArrayObject);  // Pass an ArrayObjectInterface as value

当将 $onlyIfExists 标志传递为 true 时，它将仅在键存在时设置该属性。

getOrFail($key)

类似于 get()，但如果键不存在，则将抛出 InvalidPropertyException。

has($key)

要检查元素是否存在，请使用 has() 方法

$obj->has('books'); // true
$obj->has('books.0.id'); // true
$obj->has('books.1.name'); // false
$obj->has('books.5'); // false

each(callback)

通过传递一个回调给 each()，可以实现遍历集合

$obj->books->each(function($book) {
    echo "ID: {$book->id}, title: {$book->title}\n";
});

foreach ($obj->books as $book) {
    echo "ID: {$book->id}, title: {$book->title}\n";
}

如果您有一个单个项，它仍然可以工作。

迭代器

由于 ArrayObject 实现了迭代器接口，因此您可以直接使用 foreach() 遍历对象。这适用于单个项或集合。

foreach ($obj->books as $book) {
    echo "ID: {$book->id}, title: {$book->title}\n";
}

pluck($key)

返回一个新的集合，其中包含提取的属性。

$titles = $obj->books->pluck('title');  // ArrayObject
$arr = $titles->toArray();  // ['1984', 'Pride and Prejudice']

pluckArray($key)

返回一个新的包含提取属性的数组。这提供了从 pluck($key)->toArray() 的快捷方式

$arr = $obj->books->pluckArray('title');  // ['1984', 'Pride and Prejudice']

count()

您可以在任何节点上调用 count

$obj->count(); // 1
$obj->books->count(); // 2
$obj->books[0]->count(); // 1

注意：当在单个项（即不是集合）上调用时，它将返回 1。

hasItems()

当集合至少包含一个项时返回 true。

$obj->hasItems();

注意：当在单个项（即不是集合）上调用时，它将返回 true

filter(callback|array $filter)

应用回调或 "where" 条件数组，并仅返回匹配的项。

使用回调时，每个项都是一个 ArrayObject 实例

// Only return items with a title
$filteredBooksWithTitle = $obj->books->filter(function($book) {
  return $book->has('title');
});

您还可以使用数组指定条件列表

// Only return items with a title
$filteredBooksWithTitle = $obj->books->filter(["title" => '1984']);

toArray()

通过 toArray() 方法获取原始数组

$obj->books[0]->toArray(); // [ 'id' => 1, 'title' => '1984', 'author' => 'George Orwell' ]
$obj->get(1)->toArray(); // [ 'id' => 2, 'title' => 'Pride and Prejudice', 'author' => 'Jane Austen' ]
$obj->books->toArray(); // [ [ 'id' => 1, 'title' => '1984', 'author' => 'George Orwell' ], [ 'id' => 2, 'title' => 'Pride and Prejudice', 'author' => 'Jane Austen' ] ]
$obj->toArray(); // [ 'books' => [ [ 'id' => 1, 'title' => '1984', 'author' => 'George Orwell' ], [ 'id' => 2, 'title' => 'Pride and Prejudice', 'author' => 'Jane Austen' ] ] ]

toJson()

返回底层数组的JSON编码字符串

$json = $obj->toJson(); // '{ "some_prop": [ "val1", "val2" ] }`

isCollection()

确定底层数组是否为集合。

$obj->books->isCollection(); // true
$obj->get('books.0')->isCollection(); // false
$obj->isCollection(); // false

unshift($val[, $val...])

向集合的开始添加一个或多个项目。如果数组当前不是集合，它将被转换为包含一个元素的集合。

$obj->unshift('value')
    ->unshift('value1', 'value2', 'value3');

注意：您可以传递 ArrayObject 作为值。

shift()

从集合中取出第一个项目。
如果数组当前不是集合，它将被转换为包含一个元素的集合。

$item = $obj->shift(); // ArrayObject

push($val[, $val...])

向集合的末尾添加一个或多个项目。如果数组当前不是集合，它将被转换为包含一个元素的集合。

$obj->push('value')
    ->push('value1', 'value2', 'value3');