README

一个PHP库，用于使用点分隔符或其他任何键分隔符访问和设置数组值。

问：在Packagist上存在许多名为“dot”的项目，这个项目有什么不同之处？

其他所有“dot”项目都需要你创建数据的副本并实例化一个新的类，本项目使用轻量级静态方法来访问和修改你现有的数组，无需创建数据的第二个副本。

这个项目与其他许多实现相比的另一个优点是，你可以选择一个不同于“.”的键分隔符，这对于键值中包含“.”字符的情况是必要的。

问：为什么要将这个项目添加到Packagist？

这个包已经在我的几个项目和职业项目中使用过，我厌倦了从项目到项目复制类。如果我的团队和我从这个项目中受益，我希望分享它，让任何可能从中受益的人也能使用它。

兼容性

如果你仍在使用php 5.6，请使用1.x分支，我将尝试修复任何非破坏性更改和/或错误修复。但是，根据语义版本控制，将不会向该分支发布向后不兼容的版本，并且没有计划再发布支持php 5.6的另一个主要版本。但是，我会尝试将任何主要功能或特性添加到1.x分支。

2.x分支支持php ^7.1，如果你需要这个版本支持你的项目。与1.x分支一样，我将修复任何非破坏性更改和/或错误。

警告：当你启用xDebug时，递归深度设置为100，然而PHP手册建议不要使用100-200层递归，因为这可能会破坏堆栈并导致当前脚本的终止。这个类使用递归遍历数组。如果你需要遍历深度超过100层的数组，这个工具可能不适用。

安装

首选的安装方法是使用Composer。运行以下命令安装包并将其添加到你的项目composer.json文件的要求中

composer require ryanwhowe/dot

用法

Dot类包含静态方法，以方便在PHP中安全地访问、设置、取消设置和计算数组数据。

`Dot::has()`

Dot::has()检查搜索数组中是否存在指定的键值。此方法使用递归遍历数组。

存在一个全局可用的dotHas()函数，它封装了在自动加载器中包含的Dot::has()静态方法。

描述

Dot::has(array $searchArray, string $searchKey, string $delimiter = '.'): bool

参数

searchArray: 要搜索提供键值的数组
searchKey: 在提供的搜索数组中搜索的键。如果数组没有字符串键，则可以使用数字字符串来访问数组中的适当位置
delimiter: 可以指定关键分隔符，当期望的数组键中已经包含 '.' 值时，需要这样做。

返回值

如果找到，该方法返回 true；如果没有找到，返回 false。

示例

示例 #1 简单的键值查找

<?php
$array = ['test' => ['test1' => 'test1value']];

var_export(Dot::has($array, 'test.test1')); echo PHP_EOL;
var_export(Dot::has($array, 'test.test2')); echo PHP_EOL;

true
false

示例 #2 混合键查找

<?php
$array = ['test' => ['valueForKey0', 'valueForKey1']];

var_export(Dot::has($array, 'test.0')); echo PHP_EOL;
var_export(Dot::has($array, 'test~0', '~')); echo PHP_EOL;
var_export(Dot::has($array, 'test.5')); echo PHP_EOL;

true
true
false

`Dot::get()`

Dot::get() 方法用于从数组中获取数据，前提是在搜索位置存在键，如果不存在，则返回默认值。

存在一个全局可用的 dotGet() 函数，它包装了包含在自动加载器中的 Dot::get() 静态方法。

描述

Dot::get(array $searchArray, string $searchKey, mixed $default = null, string $delimiter = '.', int $missingKeyException = 0): mixed

参数

searchArray: 要搜索提供键值的数组
searchKey: 在提供的搜索数组中搜索的键。如果数组没有字符串键，则可以使用数字字符串来访问数组中的适当位置
默认值: 如果搜索键未在搜索数组中找到，则返回的默认值。
delimiter: 可以指定关键分隔符，当期望的数组键中已经包含 '.' 值时，需要这样做。
missingKeyException: 如果设置为 Dot::ARRAY_KEY_MISSING_EXCEPTION，则当搜索键未在搜索数组中找到时，方法将抛出 ArrayKeyNotSetException，而不是默认值。这允许在搜索键缺失时使用 try/catch 流程，如果需要额外的逻辑。

返回值

方法返回的值是在搜索键位置存储的混合值或提供的默认值。

示例

示例 #1 简单的键值查找

<?php
$array = ['test' => ['test1' => 'test1value']];

echo Dot::get($array, 'test.test1', 'Nothing Here'), PHP_EOL;
echo Dot::get($array, 'test.test2', 'Nothing Here'), PHP_EOL;

test1value
Nothing Here

示例 #2 混合键查找

<?php
$array = ['test' => ['valueForKey0', 'valueForKey1']];

echo Dot::get($array, 'test.0', 'Nothing Here'), PHP_EOL;
echo Dot::get($array, 'test|0', 'Nothing Here', '|'), PHP_EOL;
echo Dot::get($array, 'test.4', 'Nothing Here'), PHP_EOL;

valueForKey0
valueForKey0
Nothing Here

示例 #3 使用 get() 的异常逻辑

$array = ['test' => ['test1' => 'test1value']];

try {
    echo Dot::get($array, 'test.test1', 'Nothing Here', Dot::DEFAULT_DELIMITER, Dot::ARRAY_KEY_MISSING_EXCEPTION), PHP_EOL;
} catch(ArrayKeyNotSetException $e){
    echo $e->getMessate(), PHP_EOL;
}

try {
    echo Dot::get($array, 'test.test2', 'Nothing Here', Dot::DEFAULT_DELIMITER, Dot::ARRAY_KEY_MISSING_EXCEPTION), PHP_EOL;
} catch(ArrayKeyNotSetException $e){
    echo $e->getMessage(), PHP_EOL;
}

test1value
The arrayKey, 'test.test2' is not set in the source array.

`Dot::set()`

Dot::set() 方法将在提供的数组中设置传递的值在键的位置。
如果键不存在，则设置方法将创建所需的键结构以将值放入数组。

存在一个全局可用的 dotSet() 函数，它包装了包含在自动加载器中的 Dot::set() 静态方法。

描述

Dot::set(array &$setArray, string $setKey, mixed $value, string $delimiter = '.'): void

参数

setArray: 将值放置在内的数组。
setKey: 在提供的搜索数组中搜索的键。如果数组没有字符串键，则可以使用数字字符串来访问数组中的适当位置
value: 如果搜索键未在搜索数组中找到，则返回的默认值。
delimiter: 可以指定关键分隔符，当期望的数组键中已经包含 '.' 值时，需要这样做。

返回值

此方法没有返回值，数组通过引用传递，并更新为插入的值。

示例

示例 #1 简单的键值查找

<?php
$array = ['test' => []];

Dot::set($array, 'test.test1', 'test1value');
var_export($array); echo PHP_EOL;
Dot::set($array, 'test.test2', 'test2value');
var_export($array); echo PHP_EOL;

array (
  'test' => 
  array (
    'test1' => 'test1value',
  ),
)
array (
  'test' => 
  array (
    'test1' => 'test1value',
    'test2' => 'test2value',
  ),
)

示例 #2 嵌套设置

<?php
$array = ['test' => []];

Dot::set($array, 'test.test2.test21', 'test21value');
var_export($array); echo PHP_EOL;
Dot::set($array, 'test~test2~test22', 'test22value', '~');
var_export($array); echo PHP_EOL;

array (
  'test' => 
  array (
    'test2' => 
    array (
      'test21' => 'test21value',
    ),
  ),
)
array (
  'test' => 
  array (
    'test2' => 
    array (
      'test21' => 'test21value',
      'test22' => 'test22value',
    ),
  ),
)

`Dot::append()`

Dot::append() 方法将在提供的数组中将传递的值设置为键的位置上的数组值。如果该位置已经包含值，则将值合并到一个数组中。如果不存在键结构，则 append 方法将创建所需的键结构以将数组值放入数组。

存在一个全局可用的 dotAppend() 函数，它包装了包含在自动加载器中的 Dot::append() 静态方法。

描述

Dot::append(array &$appendArray, string $appendKey, mixed $value, string $delimiter = '.', int $missingKeyException): void

参数

appendArray: 将值放置在内的数组，该值位于 appendKey 位置。
appendKey: 将在提供的 appendArray 中搜索的分隔键。如果数组没有字符串键，可以使用数字字符串来访问数组中的适当位置。
value: 将在数组中设置的值。如果键位置在数组中未设置，则将创建键位置的完整路径，并将值添加到键位置。如果键位置已经存在值，则新值将附加到数组的末尾。如果键位置的值不是数组，则将位置转换为数组，并将新值附加到新数组的末尾。
delimiter: 可以指定关键分隔符，当期望的数组键中已经包含 '.' 值时，需要这样做。
missingKeyException: 如果设置为 Dot::ARRAY_KEY_MISSING_EXCEPTION，则当搜索键未在搜索数组中找到时，方法将抛出 ArrayKeyNotSetException，而不是默认值。这允许在搜索键缺失时使用 try/catch 流程，如果需要额外的逻辑。

返回值

此方法没有返回值，数组通过引用传递，并更新为插入的值。

示例

示例 #1 插入现有值

<?php
$test = array (
    'a' => array (
        'b' => array (
            'c' => 'd'
            )
        )
    );

Dot::append($test, 'a.b.c', 'e');
var_export($test);

array (
  'a' => 
  array (
    'b' => 
    array (
      'c' => 
      array (
        0 => 'd',
        1 => 'e',
      ),
    ),
  ),
)

示例 #2 设置键并创建初始数组

<?php
$test = array (
    'a' => array (
        'b' => array ()
        )
    );

Dot::append($test, 'a.b.c', 'd');

var_export($test);

array (
  'a' => 
  array (
    'b' => 
    array (
      'c' => 
      array (
        0 => 'd',
      ),
    ),
  ),
)

`Dot::delete()`

Dot::delete() 方法将取消键位置。如果键位置不在数组中，则对传递的数组没有影响。

存在一个全局可用的 dotDelete() 函数，它包装了包含在自动加载器中的 Dot::delete() 静态方法。

描述

Dot::delete(array &$deleteArray, string $deleteKey, string $delimiter = '.', int $missingKeyException): void

参数

deleteArray: 将取消值的数组，如果 deleteKey 在数组中。
deleteKey: 在提供的deleteArray中将搜索的分隔键。如果数组没有字符串键，可以使用数字字符串来访问数组中的适当位置。
delimiter: 可以指定关键分隔符，当期望的数组键中已经包含 '.' 值时，需要这样做。
missingKeyException: 如果设置为 Dot::ARRAY_KEY_MISSING_EXCEPTION，则当搜索键未在搜索数组中找到时，方法将抛出 ArrayKeyNotSetException，而不是默认值。这允许在搜索键缺失时使用 try/catch 流程，如果需要额外的逻辑。

返回值

此方法没有返回值，数组是通过引用传递的，并会更新。

示例

示例 #1 简单的键值未设置

<?php
$test = array (
    'a' => array (
        'b' => array (
            'c' => array (
                'd',
                'e',
                'f'
                )
            )
        )
    );

Dot::delete($test, 'a.b.c');
var_export($test);

array (
  'a' => 
  array (
    'b' => 
    array (
    ),
  ),
)

`Dot::count()`

Dot::count() 方法将生成提供键位置上的元素计数。如果提供的键位置的值不是数组（或提供的键没有值），默认情况下，该方法将返回 0。此行为可以更改为在没有值或非数组值时返回 -1。

存在一个全局可用的 dotCount() 函数，它封装了包含在自动加载器中的 Dot::count() 静态方法。

描述

Dot::count(array &$setArray, string $setKey, string $delimiter = '.', int $return = Dot::ZERO_ON_NON_ARRAY, int $missingKeyException = 0): int

参数

setArray: 将值放置在内的数组。
setKey: 在提供的搜索数组中搜索的键。如果数组没有字符串键，则可以使用数字字符串来访问数组中的适当位置
delimiter: 可以指定关键分隔符，当期望的数组键中已经包含 '.' 值时，需要这样做。
返回: 默认情况下，如果键位置的值未设置或不是数组，该方法将返回 0。这可以通过使用 Dot::NEGATIVE_ON_NON_ARRAY 常量来更改，从而在键位置没有值或值不是数组时返回 -1。
missingKeyException: 如果设置为 Dot::ARRAY_KEY_MISSING_EXCEPTION，则当搜索键未在搜索数组中找到时，方法将抛出 ArrayKeyNotSetException，而不是默认值。这允许在搜索键缺失时使用 try/catch 流程，如果需要额外的逻辑。

返回值

该方法返回一个 int，包含数组元素的计数。如果键位置的值不是数组或未设置，则默认情况下将返回 0，这可以通过将 return 参数设置为 Dot::NEGATIVE_ON_NON_ARRAY 来更改，以返回 -1。

示例

示例 #1 简单数组计数

<?php
$array = ['test' => [1,2,3,4,5], 'test1' => ['test2' => [1,2,3]]];

$result = Dot::count($array, 'test');
var_export($result); echo PHP_EOL;
$result = Dot::count($array, 'test1.test2');
var_export($result); echo PHP_EOL;

5
3

示例 #2 没有找到元素和非数组元素

<?php
$array = ['test' => 1, 'test1' => []];

/* A non array value */
$result = Dot::count($array, 'test');
var_export($result); echo PHP_EOL;
$result = Dot::count($array, 'test', Dot::DEFAULT_DELIMITER, Dot::NEGATIVE_ON_NON_ARRAY);
var_export($result); echo PHP_EOL;

/* A key that has no value */
$result = Dot::count($array, 'test1.test2');
var_export($result); echo PHP_EOL;
$result = Dot::count($array, 'test1.test2', Dot::DEFAULT_DELIMITER, Dot::NEGATIVE_ON_NON_ARRAY);
var_export($result); echo PHP_EOL;

/* An empty array */
$result = Dot::count($array, 'test1');
var_export($result); echo PHP_EOL;
$result = Dot::count($array, 'test1', Dot::DEFAULT_DELIMITER, Dot::NEGATIVE_ON_NON_ARRAY);
var_export($result); echo PHP_EOL;

`Dot::flatten()`

Dot::flatten() 方法将多维数组展平为单维数组，其中 dotKeys => values 作为返回的新数组的键。源数组中的每个非数组值将在输出数组中对应一行。

存在一个全局可用的 dotFlatten() 函数，它封装了包含在自动加载器中的 Dot::flatten() 静态方法。

描述

Dot::flatten(array $array, string $delimiter = '.', string $prepend = ''): array

参数

数组: 源数据数组
delimiter: 可以指定键分隔符，当预期数组键中已包含 '.' 值时，需要此值，"flattened" 键将由此值分隔。
prepend: 主要在方法递归中使用，可用于在生成的键前添加字符串。

返回值

方法将返回一个深度为 1 的数组，其中 array<dotKeys, mixed>。

INFO: 可以使用 Dot::set() 方法遍历展平数组的结果行，以重建原始输入数组。

示例

示例 #1 简单的键值查找

<?php
$array = [
    'test1' => 
        [
            'test2' => 'test12value',
            'test3' => ['test4' => 'test134value'],
            'test5' => ['test150value', 'test151value']
        ]
    ];

var_export(Dot::flatten($array));

array (
  'test1.test2' => 'test12value',
  'test1.test3.test4' => 'test134value',
  'test1.test5.0' => 'test150value',
  'test1.test5.1' => 'test151value',
)

ryanwhowe / dot

维护者

详细信息

README

兼容性

安装

用法

Dot::has()

描述

参数

返回值

示例

示例 #1 简单的键值查找

示例 #2 混合键查找

Dot::get()

描述

参数

返回值

示例

示例 #1 简单的键值查找

示例 #2 混合键查找

示例 #3 使用 get() 的异常逻辑

Dot::set()

描述

参数

返回值

示例

示例 #1 简单的键值查找

示例 #2 嵌套设置

Dot::append()

描述

参数

返回值

示例

示例 #1 插入现有值

示例 #2 设置键并创建初始数组

Dot::delete()

描述

参数

返回值

示例

示例 #1 简单的键值未设置

Dot::count()

描述

参数

返回值

示例

示例 #1 简单数组计数

示例 #2 没有找到元素和非数组元素

Dot::flatten()

描述

参数

返回值

示例

示例 #1 简单的键值查找

`Dot::has()`

`Dot::get()`

`Dot::set()`

`Dot::append()`

`Dot::delete()`

`Dot::count()`

`Dot::flatten()`