{"id":18879737,"url":"https://github.com/loilo/x-filesystem","last_synced_at":"2025-07-04T04:39:55.006Z","repository":{"id":62518877,"uuid":"197382355","full_name":"loilo/x-filesystem","owner":"loilo","description":"📄 An extension to Symfony's Filesystem Component, able to read and write PHP/YAML/JSON/CSV files","archived":false,"fork":false,"pushed_at":"2023-09-30T21:02:25.000Z","size":34,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-12-31T03:12:38.253Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","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/loilo.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":"2019-07-17T12:11:51.000Z","updated_at":"2023-07-29T01:21:53.000Z","dependencies_parsed_at":"2024-11-08T06:39:11.496Z","dependency_job_id":"45d1af0a-88a0-4fe3-a1cb-4cd3336016f8","html_url":"https://github.com/loilo/x-filesystem","commit_stats":{"total_commits":24,"total_committers":2,"mean_commits":12.0,"dds":"0.20833333333333337","last_synced_commit":"bd6c6b3e8c2462a475e2dda670432d20dbb7d454"},"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loilo%2Fx-filesystem","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loilo%2Fx-filesystem/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loilo%2Fx-filesystem/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/loilo%2Fx-filesystem/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/loilo","download_url":"https://codeload.github.com/loilo/x-filesystem/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239841742,"owners_count":19705981,"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":"2024-11-08T06:39:05.894Z","updated_at":"2025-02-20T13:07:28.967Z","avatar_url":"https://github.com/loilo.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cbr\u003e\n  \u003cimg width=\"200\" height=\"250\" src=\"x.svg\" alt=\"eXtended Filesystem logo: a document with a big \u0026quot;x\u0026quot; printed on it\"\u003e\n  \u003cbr\u003e\n  \u003cbr\u003e\n\n  # eXtended Filesystem\n\u003c/div\u003e\n\n[![Tests](https://badgen.net/github/checks/loilo/x-filesystem/master)](https://github.com/loilo/x-filesystem/actions)\n[![Version on packagist.org](https://badgen.net/packagist/v/loilo/x-filesystem)](https://packagist.org/packages/loilo/x-filesystem)\n\nAn extension to Symfony's [Filesystem Component](https://symfony.com/doc/current/components/filesystem.html) with\n\n* recursive globbing support\n* methods for reading and writing some popular data exchange formats (PHP, JSON, YAML, CSV)\n\n## Installation\n```bash\ncomposer require loilo/x-filesystem\n```\n\n## Usage\n`XFilesystem` is instantiated exactly like `Filesystem`:\n\n```php\n$fs = new Loilo\\XFilesystem\\XFilesystem();\n```\n\nNo existing behavior is modified, every method available in `Filesystem` works exactly as expected.\n\n### Find Files through Globs\nThis method matches the behavior of [PHP's built-in `glob` function](https://secure.php.net/manual/function.glob.php), but adds support for the recursive wildcard `/**/`:\n\n#### Signature\n```php\n/**\n * Find files by a glob. As opposed to PHP's built-in \"glob\" function, this method supports the ** wildcard.\n * @see https://www.php.net/manual/en/function.glob.php#refsect1-function.glob-parameters\n *\n * @param string  $pattern The pattern. No tilde expansion or parameter substitution is done.\n * @param int     $flags   Flags to apply\n * @return array\n */\npublic function glob($pattern, $flags = 0)\n```\n\n#### Example\n```php\n$fs-\u003eglob('src/**/*.php');\n```\n\n### Read Plain Files\n`Filesystem` has no built-in way to read plain files, so here we go:\n\n#### Signature\n```php\n/**\n * Read the contents of a file\n *\n * @param string $filename    The file to read from\n * @return string The contents from the file\n *\n * @throws FileNotFoundException When the path does not exist or is not a file\n * @throws IOException           When the file exists but is not readable\n */\nfunction readFile($filename)\n```\n\n#### Example\n```php\n$fs-\u003ereadFile('plain.txt');\n```\n\n### Read Files from URLs\nBy default, HTTP(S) URLs are not allowed as filenames when reading a file. This can however be adjusted through setting the `remoteAllowed` flag:\n\n```php\n// Allow the $fs instance to read from HTTP(S) URLs\n$fs-\u003esetRemoteAllowed(true);\n```\n\nInversely, you can check whether remote access is enabled via `$fs-\u003eisRemoteAllowed()`.\n\n### Read JSON Files\n### Signature\n```php\n/**\n * Read the contents of a file and parse them as JSON\n *\n * @param string $filename The file to read from\n * @param int    $mode     The parse mode:\n *                         `PARSE_ASSOC` to return an associative array\n *                         `PARSE_OBJECT` to return a \\stdClass object\n * @return mixed The parsed JSON data\n *\n * @throws FileNotFoundException    When the path does not exist or is not a file\n * @throws IOException              When the file exists but is not readable\n * @throws UnexpectedValueException When parsing the JSON fails\n */\nfunction readJsonFile($filename, $mode = self::PARSE_OBJECT)\n```\n\n#### Example\n**`data.json`**\n```json\n{ \"a\": 1, \"b\": 2, \"c\": 3 }\n```\n\n**`read-json.php`**\n```php\n$fs-\u003ereadJsonFile('data.json')\n```\n\n**`\u003e\u003e\u003e`**\n```\nstdClass Object\n(\n    [a] =\u003e 1\n    [b] =\u003e 2\n    [c] =\u003e 3\n)\n```\n\n### Write JSON Files\n#### Signature\n```php\n/**\n * Dump data into a file as JSON\n *\n * @param string $filename The file to be written to\n * @param mixed  $data     The data to write to the file\n * @param int    $flags    The json_encode() flags to utilize\n *\n * @throws IOException              When the file cannot be written to\n * @throws UnexpectedValueException When encoding the JSON fails\n */\nfunction dumpJsonFile(\n    $filename,\n    $data,\n    $flags = JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE\n)\n```\n\n#### Example\n**`write-json.php`**\n```php\n$fs-\u003edumpJsonFile('data.json', [\n  'a' =\u003e 1,\n  'b' =\u003e 2,\n  'c' =\u003e 3\n]);\n```\n\n**`\u003e\u003e\u003e`**\n```json\n{\n    \"a\": 1,\n    \"b\": 2,\n    \"c\": 3\n}\n```\n\n\n### Read YAML Files\n#### Signature\n```php\n/**\n * Read the contents of a file and parses them as YAML\n *\n * @param string $filename The file to read from\n * @param int    $mode     The parse mode:\n *                         `PARSE_ASSOC` to return an associative array\n *                         `PARSE_OBJECT` to return a \\stdClass object\n * @return mixed The parsed YAML data\n *\n * @throws FileNotFoundException When the path does not exist or is not a file\n * @throws IOException           When the file exists but is not readable\n * @throws ParseException        When the file could not be read or the YAML is not valid\n */\nfunction readYamlFile($filename, $mode = self::PARSE_OBJECT)\n```\n\n#### Example\n**`data.yaml`**\n```yaml\na: 1\nb: 2\nc: 3\n```\n\n**`read-yaml.php`**\n```php\n$fs-\u003ereadYamlFile('data.yml')\n```\n\n**`\u003e\u003e\u003e`**\n```\nstdClass Object\n(\n    [a] =\u003e 1\n    [b] =\u003e 2\n    [c] =\u003e 3\n)\n```\n\n### Write YAML Files\n#### Signature\n```php\n/**\n * Dump content into a file as YAML\n *\n * @param string $filename The file to be written to\n * @param mixed  $data     The data to write into the file\n * @param int    $inline   The level where to switch to inline YAML\n * @param int    $indent   The amount of spaces to use for indentation of nested nodes\n *\n * @throws IOException When the file cannot be written to\n */\nfunction dumpYamlFile($filename, $data, $inline = 2, $indent = 4)\n```\n\n#### Example\n**`write-yaml.php`**\n```php\n$fs-\u003edumpYamlFile('data.yml', [\n  'a' =\u003e 1,\n  'b' =\u003e 2,\n  'c' =\u003e 3\n]);\n```\n\n**`\u003e\u003e\u003e`**\n```yaml\na: 1\nb: 2\nc: 3\n```\n\n\n### Read CSV Files\n#### Signature\n```php\n/**\n * Read the contents of a file and parses them as CSV\n *\n * @param string $filename   The file to read from\n * @param int    $mode       The parse mode:\n *                           `PARSE_ARRAY` returns each row as an array\n *                           `PARSE_ASSOC` takes the first row as headers and returns associative arrays\n *                           `PARSE_OBJECT` takes the first row as headers and returns \\stdClass objects\n * @param string $delimiter  The field delimiter (one character only)\n * @param string $charset    The charset the CSV file is encoded in\n * @param string $enclosure  The field enclosure (one character only)\n * @param string $escapeChar The escape character (one character only)\n * @return mixed The parsed CSV data\n *\n * @throws FileNotFoundException    When the path does not exist or is not a file\n * @throws IOException              When the file exists but is not readable\n * @throws UnexpectedValueException When the column count is inconsistent\n */\nfunction readCsvFile(\n    $filename,\n    $mode       = self::PARSE_OBJECT,\n    $delimiter  = ',',\n    $charset    = 'UTF-8',\n    $enclosure  = '\"',\n    $escapeChar = '\\\\'\n)\n```\n\n#### Example\n**`data.csv`**\n```csv\na,b,c\n1,2,3\n4,5,6\n7,8,9\n```\n\n**`read-csv.php`**\n```php\n$fs-\u003ereadCsvFile('data.csv')\n```\n\n**`\u003e\u003e\u003e`**\n```\nArray\n(\n    [0] =\u003e stdClass Object\n        (\n            [a] =\u003e 1\n            [b] =\u003e 2\n            [c] =\u003e 3\n        )\n\n    [1] =\u003e stdClass Object\n        (\n            [a] =\u003e 4\n            [b] =\u003e 5\n            [c] =\u003e 6\n        )\n\n    [2] =\u003e stdClass Object\n        (\n            [a] =\u003e 7\n            [b] =\u003e 8\n            [c] =\u003e 9\n        )\n\n)\n```\n\n### Write CSV Files\n#### Signature\n```php\n/**\n * Dump content into a file as CSV\n *\n * @param string $filename   The file to be written to\n * @param mixed  $data       The data to write into the file\n * @param string $delimiter  The field delimiter (one character only)\n * @param string $enclosure  The field enclosure (one character only)\n * @param string $escapeChar The escape character (one character only)\n * @param int    $dumpMode   How to interpret passed data (CSV_DUMP_PLAIN or CSV_DUMP_STRUCTURED)\n *\n * @throws IOException When the file cannot be written to\n */\nfunction dumpCsvFile(\n    $filename,\n    $data,\n    $delimiter  = ',',\n    $enclosure  = '\"',\n    $escapeChar = '\\\\',\n    $dumpMode   = self::CSV_DUMP_DETECT\n)\n```\n\n#### Example\n**`write-csv.php`**\n```php\n$fs-\u003edumpCsvFile('data.csv', [\n    [ 'a', 'b', 'c' ],\n    [  1,   2,   3  ],\n    [  4,   5,   6  ],\n    [  7,   8,   9  ]\n]);\n```\n\n**`\u003e\u003e\u003e`**\n```csv\na,b,c\n1,2,3\n4,5,6\n7,8,9\n```\n\n\n### Read PHP Files\nRead PHP files that [`return` data](https://secure.php.net/manual/en/function.include.php#example-126).\n\n\u003e **WARNING!** This method utilizes PHP's `include` statement and has no safety nets against possible side effects and abuse through arbitrary code execution. Only ever use this with trusted files!\n\n#### Signature\n```php\n/**\n * Read and return the contents of a PHP file\n *\n * @param string $filename The PHP file to include\n * @param int    $caching  The caching behaviour:\n *                         `PHP_ALLOW_CACHED` will evaluate the file only once\n *                         `PHP_INVALIDATE_CACHE` will re-evaluate it if it changed\n *                         `PHP_FORCE_INVALIDATE_CACHE` will re-evaluate it anyway\n *                          Note that only OPCache is utilized which usually is turned off in PHP CLI\n * @return mixed The data returned from the file\n *\n * @throws FileNotFoundException When the path does not exist or is not a file\n * @throws IOException           When the file exists but is not readable\n */\nfunction readPhpFile($filename, $caching = self::PHP_ALLOW_CACHED)\n```\n\n#### Example\n**`data.php`**\n```php\n\u003c?php return [\n  'a' =\u003e 1,\n  'b' =\u003e 2,\n  'c' =\u003e 3\n]\n```\n\n**`read-php.php`**\n```php\n$fs-\u003ereadPhpFile('data.php') === [\n  'a' =\u003e 1,\n  'b' =\u003e 2,\n  'c' =\u003e 3\n];\n```\n\n### Write PHP Files\n#### Signature\n```php\n/**\n * Dump data into a file as PHP\n *\n * @param string $filename The file to be written to\n * @param string $data     The data to write into the file\n *\n * @throws IOException When the file cannot be written to\n */\nfunction dumpPhpFile($filename, $data)\n```\n\n#### Example\n**`write-php.php`**\n```php\n$fs-\u003edumpPhpFile('data.php', [\n  'a' =\u003e 1,\n  'b' =\u003e 2,\n  'c' =\u003e 3\n]);\n```\n\n**`\u003e\u003e\u003e`**\n```\n\u003c?php return array(\n  'a' =\u003e 1,\n  'b' =\u003e 2,\n  'c' =\u003e 3\n);\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floilo%2Fx-filesystem","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Floilo%2Fx-filesystem","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Floilo%2Fx-filesystem/lists"}