{"id":26796435,"url":"https://github.com/peterujah/php-string-list","last_synced_at":"2025-03-29T18:18:42.135Z","repository":{"id":252550698,"uuid":"840770376","full_name":"peterujah/php-string-list","owner":"peterujah","description":null,"archived":false,"fork":false,"pushed_at":"2024-08-10T16:56:00.000Z","size":19,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-08-11T17:33:53.891Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/peterujah.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-08-10T16:23:23.000Z","updated_at":"2024-08-10T16:56:03.000Z","dependencies_parsed_at":"2024-08-10T17:32:43.941Z","dependency_job_id":"26f69366-5033-4287-a4dc-2173dc6d54f0","html_url":"https://github.com/peterujah/php-string-list","commit_stats":null,"previous_names":["peterujah/php-string-list"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterujah%2Fphp-string-list","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterujah%2Fphp-string-list/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterujah%2Fphp-string-list/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/peterujah%2Fphp-string-list/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/peterujah","download_url":"https://codeload.github.com/peterujah/php-string-list/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246223304,"owners_count":20743168,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-29T18:18:41.601Z","updated_at":"2025-03-29T18:18:42.127Z","avatar_url":"https://github.com/peterujah.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n## PHP String List\n\nThe 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.\n\n## Installtion \n\nInstall via composer \n\n```bash\ncomposer require peterujah/php-string-list\n```\n\n### What is a String List?\n\nA 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.\n\n\n### How It Works\n\n- 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.\n  \n- 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.\n\n***\n\n### List Formatting\n\nA valid string list in this context follows specific formats:\n\n1. **Comma-Separated Non-Nested Arrays**: Use commas to separate elements in a flat array both key-value pairs.\n\n    ```php\n    $list = 'foo,bar,baz=100';\n    $array = ['foo', 'bar', 'baz' =\u003e 100];\n    ```\n\n2. **Nested Arrays Separation**: Use semicolons for elements within nested arrays both key-value pairs.\n\n    ```php\n    $list = 'foo=bar,bar=2,baz=[1;2;3]';\n    $array = [\n        'foo' =\u003e 'bar', \n        'bar' =\u003e 2, \n        'baz' =\u003e [1, 2, 3]\n    ];\n    ```\n\n    - **Key-Value Pair**: Use `key=value` syntax.\n    - **Nested Arrays**: Use square brackets `[]` and semicolons `;` for nested values.\n\n***\n\n### Capabilities of Lists Class\n\nWhile 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:\n\n#### 1. **Nested Array Handling**\n\n**PHP’s `explode` and `implode`**:\n\n- Handle only flat, non-nested strings.\n- Limited to basic string manipulation.\n- Cannot process arrays within arrays.\n\n    **PHP Explode**:\n\n    With php explode, the output is not as expected.\n\n    ```php\n    $list = 'foo=bar,bar=2,baz=[1;2;3]';\n    $array = explode(',', $list);\n\n    //Output:\n    Array\n    (\n        [0] =\u003e foo=bar\n        [1] =\u003e bar=2\n        [2] =\u003e baz=[1;2;3]\n    )\n    ```\n\n**Lists Class**:\n\n- Supports conversion between nested arrays and string lists with nested structures.\n- Uses delimiters like `;` for nested elements.\n- Converts complex string structures into multidimensional arrays.\n\n    ```php\n    use \\Peterujah\\Strings\\Lists;\n    $list = 'foo=bar,bar=2,baz=[1;2;3]';\n    $array = Lists::toArray($list);\n    // Output:\n    Array\n    (\n        [foo] =\u003e bar\n        [bar] =\u003e 2\n        [baz] =\u003e Array (\n            [0] =\u003e 1\n            [1] =\u003e 2\n            [2] =\u003e 3\n        )\n    )\n    ```\n\n    **Multidimensional Array**\n\n    ```php\n    use \\Peterujah\\Strings\\Lists;\n    $list = 'name=Peter,age=33,address=[country=Nigeria;city=EN]';\n    $array = Lists::toArray($list);\n    // Output: ['name' =\u003e 'Peter', 'age' =\u003e 33, 'address' =\u003e ['country' =\u003e 'Nigeria', 'city' =\u003e 'EN']]\n    ```\n***\n\n#### 2. **Key-Value Pair Representation**\n\n**PHP’s `explode` and `implode`**:\n\n- Do not support key-value pairs inherently.\n- Require manual processing for strings and keys.\n\n**Lists Class**:\n\n- Simplifies conversion of key-value pairs within lists.\n- Supports both simple and complex key-value structures.\n\n***\n\n#### 3. **Validation of List Format**\n\n**PHP’s `explode` and `implode`**:\n\n- Lack built-in validation for list formats.\n\n**Lists Class**:\n\n- Includes methods to validate string conformity to list formats.\n- Ensures adherence to rules for separators and nesting.\n\n    ```php\n    use \\Peterujah\\Strings\\Lists;\n    $list = 'foo=bar,bar=2,baz=[1;2;3]';\n    $isValid = Lists::isList($list);\n    // Output: true\n    ```\n\n***\n\n#### 4. **Custom Parsing and Conversion**\n\n**PHP’s `explode` and `implode`**:\n\n- Basic parsing with fixed delimiters.\n- Cannot handle custom formatting or complex structures.\n\n**Lists Class**:\n\n- Provides custom parsing rules for converting between lists and arrays.\n- Supports specific formatting requirements and custom delimiters.\n\n***\n\n#### 5. **Flexible Array to String Conversion**\n\n**PHP’s `implode`**:\n\n- Limited to simple arrays.\n- Cannot handle multidimensional or associative arrays directly.\n\n    \u003e Will encounter a `TypeError` because implode expects a simple array of values, not an associative array or multidimensional array.\n\n    ```php\n    $array = [\n        'name' =\u003e 'Peter', \n        'age' =\u003e 33, \n        'address' =\u003e [\n            'country' =\u003e 'Nigeria', \n            'city' =\u003e 'EN'\n        ]\n    ];\n    $list = implode(',', $array); // Results in TypeError\n    ```\n\n**Lists Class**:\n\n- Converts any array, including multidimensional and associative arrays, into a formatted string.\n- Handles various data types and nested arrays gracefully.\n\n    ```php\n    use \\Peterujah\\Strings\\Lists;\n    $array = [\n        'name' =\u003e 'Peter', \n        'age' =\u003e 33, \n        'address' =\u003e [\n            'country' =\u003e 'Nigeria', \n            'city' =\u003e 'EN'\n        ]\n    ];\n    $list = Lists::toList($array);\n    // Output: 'name=Peter,age=33,address=[country=Nigeria;city=EN]'\n    ```\n\n***\n\n## Available Methods\n\n### isList\n\nDetermines if a string is a valid list based on the expected list format.\n\n```php\npublic static isList(string $list): bool\n```\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `$list` | **string** | The string to check. |\n\n**Return Value:**\n\n`bool` - Return true if the string is a valid list; otherwise, false.\n\n***\n\n### toArray\n\nConverts a string list to its original array structure.\n\n```php\npublic static toArray(string $list): array\n```\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `$list` | **string** | The string list to convert. |\n\n**Return Value:**\n\n`array` - Return the extracted array.\n\n**Throws:**\n\n- `RuntimeException` - Throws if invalid list format is detected.\n\n***\n\n### toList\n\nBuilds a string representation of an array.\n\n```php\npublic static toList(array $array, string $delimiter = ','): string\n```\n\n\n\n**Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `$array` | **array** | The input array to convert. |\n| `$delimiter` | **string** | The delimiter to use between (default: ',').\u003cbr /\u003e- For none nested array use `,`.\u003cbr /\u003e- For nested array use `;`. |\n\n**Return Value:**\n\n`string` - Return the resulting string representation of the array.\n\n**Throws:**\n\n- `InvalidArgumentException` - Throws if invalid delimiter was passed.\n\n\u003e It's recommended to leave the default delimiter to automatically decide which one to use.\n\n***\n\n### More Usages Examples\n\nHere are some examples demonstrating the use of the `Lists` class methods:\n\n**Convert Array to List**:\n\n```php\n$array = ['foo', 'bar', 'baz'];\n$list = Lists::toList($array);\n// Output: 'foo,bar,baz'\n```\n\n**Convert List to Array**:\n\n```php\n$list = 'foo,bar,baz';\n$array = Lists::toArray($list);\n// Output: ['foo', 'bar', 'baz']\n```\n\n**Check Valid List**:\n\n```php\n$list = 'foo=bar,bar=2,baz=[1;2;3]';\n$isValid = Lists::isList($list);\n// Output: true\n```\n\n**Handle Nested Arrays**:\n\n```php\n$list = 'foo=bar,[address=[New York;city=NY]]';\n$array = Lists::toArray($list);\n// Output: ['foo' =\u003e 'bar', 'address' =\u003e ['New York', 'city' =\u003e 'NY']]\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterujah%2Fphp-string-list","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpeterujah%2Fphp-string-list","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpeterujah%2Fphp-string-list/lists"}