README

关于 Dot

Dot 以轻量级和快速的方式，通过点符号提供对数据数组的便捷访问。受 Laravel Collection 的启发。

Dot 实现了 PHP 的 ArrayAccess 接口，Dot 对象也可以像常规数组一样使用，并添加了点符号。

示例

使用 Dot，您可以改变这种常规数组语法

$array['info']['home']['address'] = 'Kings Square';

echo $array['info']['home']['address'];

// Kings Square

到这种（Dot 对象）

$dot->set('info.home.address', 'Kings Square');

echo $dot->get('info.home.address');

甚至这种（ArrayAccess）

$dot['info.home.address'] = 'Kings Square';

echo $dot['info.home.address'];

安装

使用 Composer 安装最新版本

composer require adbario/php-dot-notation

用法

创建一个新的 Dot 对象

$dot = new \Adbar\Dot;

// With existing array
$dot = new \Adbar\Dot($array);

// Or with auto parsing dot notation keys in existing array
$dot = new \Adbar\Dot($array, true);

// You can also set a custom delimiter instead of the default dot (.)
$dot = new \Adbar\Dot($array, false, "_");

您还可以使用辅助函数来创建对象

$dot = dot();

// With existing array
$dot = dot($array);

// Or with auto parsing dot notation keys in existing array
$dot = dot($array, true);

// You can also set a custom delimiter instead of the default dot (.)
$dot = dot($array, true, "_");

所有不返回特定值的函数都返回 Dot 对象以进行链式调用

$dot = dot();

$dot->add('user.name', 'John')
    ->set('user.email', '[email protected]')
    ->clear(); // returns empty Dot

方法

Dot 有以下方法

add()
all()
clear()
count()
delete()
flatten()
get()
has()
isEmpty()
merge()
mergeRecursive()
mergeRecursiveDistinct()
pull()
push()
replace()
set()
setArray()
setReference()
toJson()

add()

如果键不存在，则设置给定的键/值对

$dot->add('user.name', 'John');

// Equivalent vanilla PHP
if (!isset($array['user']['name'])) {
    $array['user']['name'] = 'John';
}

多个键/值对

$dot->add([
    'user.name' => 'John',
    'page.title' => 'Home'
]);

all()

返回存储的所有项目作为数组

$values = $dot->all();

clear()

删除给定键的内容（设置空数组）

$dot->clear('user.settings');

// Equivalent vanilla PHP
$array['user']['settings'] = [];

多个键

$dot->clear(['user.settings', 'app.config']);

所有存储的项目

$dot->clear();

// Equivalent vanilla PHP
$array = [];

count()

返回给定键中的项目数量

$dot->count('user.siblings');

Dot 对象根部的项目

$dot->count();

// Or use count() function as Dot implements Countable
count($dot);

delete()

删除给定的键

$dot->delete('user.name');

// ArrayAccess
unset($dot['user.name']);

// Equivalent vanilla PHP
unset($array['user']['name']);

多个键

$dot->delete([
    'user.name',
    'page.title'
]);

flatten()

返回由给定字符（默认为"."）分隔的键的扁平化数组

$flatten = $dot->flatten();

get()

返回给定键的值

echo $dot->get('user.name');

// ArrayAccess
echo $dot['user.name'];

// Equivalent vanilla PHP < 7.0
echo isset($array['user']['name']) ? $array['user']['name'] : null;

// Equivalent vanilla PHP >= 7.0
echo $array['user']['name'] ?? null;

如果给定的键不存在，则返回给定默认值

echo $dot->get('user.name', 'some default value');

has()

检查给定的键是否存在（返回布尔值 true 或 false）

$dot->has('user.name');

// ArrayAccess
isset($dot['user.name']);

多个键

$dot->has([
    'user.name',
    'page.title'
]);

isEmpty()

检查给定的键是否为空（返回布尔值 true 或 false）

$dot->isEmpty('user.name');

// ArrayAccess
empty($dot['user.name']);

// Equivalent vanilla PHP
empty($array['user']['name']);

多个键

$dot->isEmpty([
    'user.name',
    'page.title'
]);

检查整个 Dot 对象

$dot->isEmpty();

merge()

合并给定的数组或另一个 Dot 对象

$dot->merge($array);

// Equivalent vanilla PHP
array_merge($originalArray, $array);

合并给定的数组或另一个 Dot 对象与给定的键

$dot->merge('user', $array);

// Equivalent vanilla PHP
array_merge($originalArray['user'], $array);

mergeRecursive()

递归地合并给定的数组或另一个 Dot 对象

$dot->mergeRecursive($array);

// Equivalent vanilla PHP
array_merge_recursive($originalArray, $array);

递归地合并给定的数组或另一个 Dot 对象与给定的键

$dot->mergeRecursive('user', $array);

// Equivalent vanilla PHP
array_merge_recursive($originalArray['user'], $array);

mergeRecursiveDistinct()

递归地合并给定的数组或另一个 Dot 对象。重复键将覆盖原始数组中的值（与 mergeRecursive() 不同，在 mergeRecursive() 中，重复键将转换为包含多个值的数组）

$dot->mergeRecursiveDistinct($array);

递归地合并给定的数组或另一个 Dot 对象与给定的键。重复键将覆盖原始数组中的值。

$dot->mergeRecursiveDistinct('user', $array);

pull()

返回给定键的值并删除该键

echo $dot->pull('user.name');

// Equivalent vanilla PHP < 7.0
echo isset($array['user']['name']) ? $array['user']['name'] : null;
unset($array['user']['name']);

// Equivalent vanilla PHP >= 7.0
echo $array['user']['name'] ?? null;
unset($array['user']['name']);

如果给定的键不存在，则返回给定默认值

echo $dot->pull('user.name', 'some default value');

返回存储的所有项目作为数组并清空 Dot 对象

$items = $dot->pull();

push()

将给定的值推送到给定键的数组末尾

$dot->push('users', 'John');

// Equivalent vanilla PHP
$array['users'][] = 'John';

将给定的值推送到给定键的数组末尾

$dot->push('John');

// Equivalent vanilla PHP
$array[] = 'John';

replace()

用具有相同键的给定数组或 Dot 对象中的值替换值

$dot->replace($array);

// Equivalent vanilla PHP
array_replace($originalArray, $array);

用具有相同键的给定数组或 Dot 对象中的值替换值与给定的键

$dot->merge('user', $array);

// Equivalent vanilla PHP
array_replace($originalArray['user'], $array);

replace() 不是递归的。

set()

设置给定的键/值对

$dot->set('user.name', 'John');

// ArrayAccess
$dot['user.name'] = 'John';

// Equivalent vanilla PHP
$array['user']['name'] = 'John';

多个键/值对

$dot->set([
    'user.name' => 'John',
    'page.title'     => 'Home'
]);

setArray()

用给定的数组替换 Dot 对象中的所有项目

$dot->setArray($array);

setReference()

用给定的数组作为引用替换 Dot 对象中的所有项目，并且所有未来的更改都将直接应用于原始数组

$dot->setReference($array);

toJson()

以 JSON 格式返回给定键的值

echo $dot->toJson('user');

以 JSON 格式返回存储的所有项目

echo $dot->toJson();

贡献

拉取请求

分支Dot仓库
为每个特性或改进创建一个新的分支
从每个特性分支向3.x分支发送拉取请求

将新特性或改进分开到各自的特性分支中，并为每个分支发送拉取请求非常重要。这让我可以单独审查和合并新特性或改进。

样式指南

所有拉取请求都必须遵循PSR-12标准。

单元测试

所有拉取请求都必须附带有通过单元测试和完整的代码覆盖率。Dot使用PHPUnit进行测试。

静态分析

所有拉取请求都必须通过使用PHPStan进行的静态分析。

许可

MIT许可

adbario / php-dot-notation

维护者

详细信息