README

该类提供了用于操作和验证字符串列表的实用方法，包括在字符串表示和数组之间的转换。它包括检查字符串是否为有效列表格式、在列表字符串和数组之间进行转换以及其他相关操作的方法。

安装

通过Composer安装

composer require peterujah/php-string-list

什么是字符串列表？

字符串列表是一种字符串形式，用于以特定格式表示数组。这种格式允许轻松地在字符串和数组形式之间进行转换。这对于在需要以字符串格式轻松读取和写入数据的场景中处理以逗号分隔的字符串、进行转换、验证或配置简单数据存储非常有用。

工作原理

• 使用逗号分隔非嵌套数组的值，使用分号分隔嵌套数组中的值。字符串列表可以包含空数组或字符串。

• 将字符串列表转换为数组，根据其格式解析值（例如，null、true、false）将转换为字符串，以便将其转换回原始形式。

列表格式

在此上下文中，有效的字符串列表遵循特定格式

1. 逗号分隔的非嵌套数组：使用逗号分隔平面数组中的元素，包括键值对。

   $list = 'foo,bar,baz=100';
   $array = ['foo', 'bar', 'baz' => 100];

2. 嵌套数组分隔：使用分号分隔嵌套数组中的元素，包括键值对。

   $list = 'foo=bar,bar=2,baz=[1;2;3]';
   $array = [
       'foo' => 'bar', 
       'bar' => 2, 
       'baz' => [1, 2, 3]
   ];

   • 键值对：使用key=value语法。
   • 嵌套数组：使用方括号[]和分号;表示嵌套值。

列表类的功能

虽然PHP的内置implode和explode函数对基本字符串操作很有用，但Lists类提供了更多功能，以解决使用数组字符串表示形式的更复杂要求。以下是使Lists类更强大的原因

1. 嵌套数组处理

PHP的explode和implode:

• 仅处理平面、非嵌套字符串。

• 限于基本字符串操作。

• 不能处理数组中的数组。

  PHP Explode:

  使用php explode，输出结果不符合预期。

  $list = 'foo=bar,bar=2,baz=[1;2;3]';
  $array = explode(',', $list);
  
  //Output:
  Array
  (
      [0] => foo=bar
      [1] => bar=2
      [2] => baz=[1;2;3]
  )

列表类:

• 支持具有嵌套结构的嵌套数组和字符串列表之间的转换。

• 使用分号;作为嵌套元素的定界符。

• 将复杂的字符串结构转换为多维数组。

  use \Peterujah\Strings\Lists;
  $list = 'foo=bar,bar=2,baz=[1;2;3]';
  $array = Lists::toArray($list);
  // Output:
  Array
  (
      [foo] => bar
      [bar] => 2
      [baz] => Array (
          [0] => 1
          [1] => 2
          [2] => 3
      )
  )

  多维数组

  use \Peterujah\Strings\Lists;
  $list = 'name=Peter,age=33,address=[country=Nigeria;city=EN]';
  $array = Lists::toArray($list);
  // Output: ['name' => 'Peter', 'age' => 33, 'address' => ['country' => 'Nigeria', 'city' => 'EN']]

2. 键值对表示

PHP的explode和implode:

• 不支持键值对。
• 需要手动处理字符串和键。

列表类:

• 简化了列表中键值对的转换。
• 支持简单和复杂的键值结构。

3. 列表格式验证

PHP的explode和implode:

• 缺乏对列表格式的内置验证。

列表类:

• 包括验证字符串是否符合列表格式的方法。

• 确保遵循分隔符和嵌套的规则。

  use \Peterujah\Strings\Lists;
  $list = 'foo=bar,bar=2,baz=[1;2;3]';
  $isValid = Lists::isList($list);
  // Output: true

4. 自定义解析和转换

PHP的explode和implode:

• 使用固定分隔符的基本解析。
• 无法处理自定义格式或复杂结构。

列表类:

• 提供自定义解析规则以在列表和数组之间转换。
• 支持特定的格式要求以及自定义分隔符。

5. 灵活的数组到字符串转换

PHP的implode:

• 限于简单的数组。

• 无法直接处理多维或关联数组。

  将遇到TypeError，因为implode期望一个值简单数组，而不是关联数组或多维数组。

  $array = [
      'name' => 'Peter', 
      'age' => 33, 
      'address' => [
          'country' => 'Nigeria', 
          'city' => 'EN'
      ]
  ];
  $list = implode(',', $array); // Results in TypeError

列表类:

• 将任何数组（包括多维和关联数组）转换为格式化的字符串。

• 优雅地处理各种数据类型和嵌套数组。

  use \Peterujah\Strings\Lists;
  $array = [
      'name' => 'Peter', 
      'age' => 33, 
      'address' => [
          'country' => 'Nigeria', 
          'city' => 'EN'
      ]
  ];
  $list = Lists::toList($array);
  // Output: 'name=Peter,age=33,address=[country=Nigeria;city=EN]'

可用方法

isList

根据预期的列表格式确定一个字符串是否是有效的列表。

public static isList(string $list): bool

参数

返回值

bool - 如果字符串是有效的列表则返回 true，否则返回 false。

toArray

将字符串列表转换为原始数组结构。

public static toArray(string $list): array

参数

返回值

array - 返回提取的数组。

抛出

• RuntimeException - 如果检测到无效的列表格式则抛出。

toList

构建数组的字符串表示形式。

public static toList(array $array, string $delimiter = ','): string

参数

返回值

string - 返回数组的字符串表示形式。

抛出

• InvalidArgumentException - 如果传递了无效的分隔符则抛出。

建议使用默认分隔符以自动决定使用哪个分隔符。

更多使用示例

以下是一些演示 Lists 类方法使用的示例

将数组转换为列表:

$array = ['foo', 'bar', 'baz'];
$list = Lists::toList($array);
// Output: 'foo,bar,baz'

将列表转换为数组:

$list = 'foo,bar,baz';
$array = Lists::toArray($list);
// Output: ['foo', 'bar', 'baz']

检查有效列表:

$list = 'foo=bar,bar=2,baz=[1;2;3]';
$isValid = Lists::isList($list);
// Output: true

处理嵌套数组:

$list = 'foo=bar,[address=[New York;city=NY]]';
$array = Lists::toArray($list);
// Output: ['foo' => 'bar', 'address' => ['New York', 'city' => 'NY']]