PHPackages                             peterujah/php-string-list - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. peterujah/php-string-list

ActiveLibrary[Utility & Helpers](/categories/utility)

peterujah/php-string-list
=========================

PHP string Lists is a utility class for converting between string lists and arrays, providing a straightforward way to handle structured data in a string format.

20PHP

Since Aug 10Pushed 1y ago1 watchersCompare

[ Source](https://github.com/peterujah/php-string-list)[ Packagist](https://packagist.org/packages/peterujah/php-string-list)[ RSS](/packages/peterujah-php-string-list/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (1)DependenciesVersions (1)Used By (0)

PHP String List
---------------

[](#php-string-list)

The class provides utility methods for manipulating and validating string lists, converting between string representations and arrays. It includes methods to check if a string is a valid list format, convert between list strings and arrays, and perform other related operations.

Installtion
-----------

[](#installtion)

Install via composer

```
composer require peterujah/php-string-list
```

### What is a String List?

[](#what-is-a-string-list)

A string list is a string form that represents an array in a specific format. This format allows for easy conversion between string and array forms. This can be useful for handling comma-separated strings and performing conversions, validations or configuration of simple data storage, in a scenarios where data needs to be easily readable and writable in a string format.

### How It Works

[](#how-it-works)

- Converts an array to a string list using comma-separated values for non-nested arrays and semicolons for nested arrays. The string list can include empty arrays or strings.
- Translates a string list into an array, parsing values based on their format (e.g., `null`, `true`, `false`) will be translated as string allowing to convert it back to it original form.

---

### List Formatting

[](#list-formatting)

A valid string list in this context follows specific formats:

1. **Comma-Separated Non-Nested Arrays**: Use commas to separate elements in a flat array both key-value pairs.

    ```
    $list = 'foo,bar,baz=100';
    $array = ['foo', 'bar', 'baz' => 100];
    ```
2. **Nested Arrays Separation**: Use semicolons for elements within nested arrays both key-value pairs.

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

    - **Key-Value Pair**: Use `key=value` syntax.
    - **Nested Arrays**: Use square brackets `[]` and semicolons `;` for nested values.

---

### Capabilities of Lists Class

[](#capabilities-of-lists-class)

While PHP’s built-in `implode` and `explode` functions are useful for basic string manipulation, the `Lists` class provides additional functionality that addresses more complex requirements for working with string representations of arrays. Here’s what makes the `Lists` class more powerful:

#### 1. **Nested Array Handling**

[](#1-nested-array-handling)

**PHP’s `explode` and `implode`**:

- Handle only flat, non-nested strings.
- Limited to basic string manipulation.
- Cannot process arrays within arrays.

    **PHP Explode**:

    With php explode, the output is not as expected.

    ```
    $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]
    )
    ```

**Lists Class**:

- Supports conversion between nested arrays and string lists with nested structures.
- Uses delimiters like `;` for nested elements.
- Converts complex string structures into multidimensional arrays.

    ```
    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
        )
    )
    ```

    **Multidimensional Array**

    ```
    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. **Key-Value Pair Representation**

[](#2-key-value-pair-representation)

**PHP’s `explode` and `implode`**:

- Do not support key-value pairs inherently.
- Require manual processing for strings and keys.

**Lists Class**:

- Simplifies conversion of key-value pairs within lists.
- Supports both simple and complex key-value structures.

---

#### 3. **Validation of List Format**

[](#3-validation-of-list-format)

**PHP’s `explode` and `implode`**:

- Lack built-in validation for list formats.

**Lists Class**:

- Includes methods to validate string conformity to list formats.
- Ensures adherence to rules for separators and nesting.

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

---

#### 4. **Custom Parsing and Conversion**

[](#4-custom-parsing-and-conversion)

**PHP’s `explode` and `implode`**:

- Basic parsing with fixed delimiters.
- Cannot handle custom formatting or complex structures.

**Lists Class**:

- Provides custom parsing rules for converting between lists and arrays.
- Supports specific formatting requirements and custom delimiters.

---

#### 5. **Flexible Array to String Conversion**

[](#5-flexible-array-to-string-conversion)

**PHP’s `implode`**:

- Limited to simple arrays.
- Cannot handle multidimensional or associative arrays directly.

    > Will encounter a `TypeError` because implode expects a simple array of values, not an associative array or multidimensional array.

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

**Lists Class**:

- Converts any array, including multidimensional and associative arrays, into a formatted string.
- Handles various data types and nested arrays gracefully.

    ```
    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]'
    ```

---

Available Methods
-----------------

[](#available-methods)

### isList

[](#islist)

Determines if a string is a valid list based on the expected list format.

```
public static isList(string $list): bool
```

**Parameters:**

ParameterTypeDescription`$list`**string**The string to check.**Return Value:**

`bool` - Return true if the string is a valid list; otherwise, false.

---

### toArray

[](#toarray)

Converts a string list to its original array structure.

```
public static toArray(string $list): array
```

**Parameters:**

ParameterTypeDescription`$list`**string**The string list to convert.**Return Value:**

`array` - Return the extracted array.

**Throws:**

- `RuntimeException` - Throws if invalid list format is detected.

---

### toList

[](#tolist)

Builds a string representation of an array.

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

**Parameters:**

ParameterTypeDescription`$array`**array**The input array to convert.`$delimiter`**string**The delimiter to use between (default: ',').
- For none nested array use `,`.
- For nested array use `;`.**Return Value:**

`string` - Return the resulting string representation of the array.

**Throws:**

- `InvalidArgumentException` - Throws if invalid delimiter was passed.

> It's recommended to leave the default delimiter to automatically decide which one to use.

---

### More Usages Examples

[](#more-usages-examples)

Here are some examples demonstrating the use of the `Lists` class methods:

**Convert Array to List**:

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

**Convert List to Array**:

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

**Check Valid List**:

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

**Handle Nested Arrays**:

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

###  Health Score

14

—

LowBetter than 2% of packages

Maintenance28

Infrequent updates — may be unmaintained

Popularity3

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity17

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://www.gravatar.com/avatar/ce34af529a4ed50696211a2b4d330fbadd2d1738bc5d010523eb4a85cf342b17?d=identicon)[peterujah](/maintainers/peterujah)

---

Top Contributors

[![peterujah](https://avatars.githubusercontent.com/u/16369609?v=4)](https://github.com/peterujah "peterujah (8 commits)")

### Embed Badge

![Health badge](/badges/peterujah-php-string-list/health.svg)

```
[![Health](https://phpackages.com/badges/peterujah-php-string-list/health.svg)](https://phpackages.com/packages/peterujah-php-string-list)
```

###  Alternatives

[nunomaduro/essentials

Just better defaults for your Laravel projects.

1.2k317.5k51](/packages/nunomaduro-essentials)[snowplow/referer-parser

Snowplow Refer(r)er parser for PHP

3782.2M30](/packages/snowplow-referer-parser)[n98/junit-xml

JUnit XML Document generation library

168.7M8](/packages/n98-junit-xml)[zenstruck/bytes

Parse, manipulate, humanize, and format bytes.

25662.7k9](/packages/zenstruck-bytes)[yajra/laravel-disqus

A simple Disqus platform integration with Laravel.

8456.9k](/packages/yajra-laravel-disqus)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)