PHPackages                             loilo/x-filesystem - 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. [File & Storage](/categories/file-storage)
4. /
5. loilo/x-filesystem

ActiveLibrary[File & Storage](/categories/file-storage)

loilo/x-filesystem
==================

An extension to Symfony's Filesystem Component, able to read and write PHP/YAML/JSON/CSV files

2.0.2(1mo ago)16521MITPHPPHP >= 8.0CI failing

Since Jul 17Pushed 1mo agoCompare

[ Source](https://github.com/loilo/x-filesystem)[ Packagist](https://packagist.org/packages/loilo/x-filesystem)[ RSS](/packages/loilo-x-filesystem/feed)WikiDiscussions master Synced 3d ago

READMEChangelogDependencies (10)Versions (12)Used By (1)

 [![eXtended Filesystem logo: a document with a big "x" printed on it](x.svg)](x.svg)

eXtended Filesystem
===================

[](#extended-filesystem)

[![Tests](https://camo.githubusercontent.com/11aab5e2339321662be9f838784ad82252771a148b968cf8933649492b22d9b6/68747470733a2f2f62616467656e2e6e65742f6769746875622f636865636b732f6c6f696c6f2f782d66696c6573797374656d2f6d6173746572)](https://github.com/loilo/x-filesystem/actions)[![Version on packagist.org](https://camo.githubusercontent.com/0f591c31dba53512f259f88f2fdd0a502b08949c46740bba68b54789072ebeb3/68747470733a2f2f62616467656e2e6e65742f7061636b61676973742f762f6c6f696c6f2f782d66696c6573797374656d)](https://packagist.org/packages/loilo/x-filesystem)

An extension to Symfony's [Filesystem Component](https://symfony.com/doc/current/components/filesystem.html) with

- recursive globbing support
- methods for reading and writing some popular data exchange formats (PHP, JSON, YAML, CSV)

Installation
------------

[](#installation)

```
composer require loilo/x-filesystem
```

Usage
-----

[](#usage)

`XFilesystem` is instantiated exactly like `Filesystem`:

```
$fs = new Loilo\XFilesystem\XFilesystem();
```

No existing behavior is modified, every method available in `Filesystem` works exactly as expected.

### Find Files through Globs

[](#find-files-through-globs)

This 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 `/**/`:

#### Signature

[](#signature)

```
/**
 * Find files by a glob. As opposed to PHP's built-in "glob" function, this method supports the ** wildcard.
 * @see https://www.php.net/manual/en/function.glob.php#refsect1-function.glob-parameters
 *
 * @param string  $pattern The pattern. No tilde expansion or parameter substitution is done.
 * @param int     $flags   Flags to apply
 * @return array
 */
public function glob($pattern, $flags = 0)
```

#### Example

[](#example)

```
$fs->glob('src/**/*.php');
```

### Read Plain Files

[](#read-plain-files)

`Filesystem` has no built-in way to read plain files, so here we go:

#### Signature

[](#signature-1)

```
/**
 * Read the contents of a file
 *
 * @param string $filename    The file to read from
 * @return string The contents from the file
 *
 * @throws FileNotFoundException When the path does not exist or is not a file
 * @throws IOException           When the file exists but is not readable
 */
function readFile($filename)
```

#### Example

[](#example-1)

```
$fs->readFile('plain.txt');
```

### Read Files from URLs

[](#read-files-from-urls)

By default, HTTP(S) URLs are not allowed as filenames when reading a file. This can however be adjusted through setting the `remoteAllowed` flag:

```
// Allow the $fs instance to read from HTTP(S) URLs
$fs->setRemoteAllowed(true);
```

Inversely, you can check whether remote access is enabled via `$fs->isRemoteAllowed()`.

### Read JSON Files

[](#read-json-files)

### Signature

[](#signature-2)

```
/**
 * Read the contents of a file and parse them as JSON
 *
 * @param string $filename The file to read from
 * @param int    $mode     The parse mode:
 *                         `PARSE_ASSOC` to return an associative array
 *                         `PARSE_OBJECT` to return a \stdClass object
 * @return mixed The parsed JSON data
 *
 * @throws FileNotFoundException    When the path does not exist or is not a file
 * @throws IOException              When the file exists but is not readable
 * @throws UnexpectedValueException When parsing the JSON fails
 */
function readJsonFile($filename, $mode = self::PARSE_OBJECT)
```

#### Example

[](#example-2)

**`data.json`**

```
{ "a": 1, "b": 2, "c": 3 }
```

**`read-json.php`**

```
$fs->readJsonFile('data.json')
```

**`>>>`**

```
stdClass Object
(
    [a] => 1
    [b] => 2
    [c] => 3
)

```

### Write JSON Files

[](#write-json-files)

#### Signature

[](#signature-3)

```
/**
 * Dump data into a file as JSON
 *
 * @param string $filename The file to be written to
 * @param mixed  $data     The data to write to the file
 * @param int    $flags    The json_encode() flags to utilize
 *
 * @throws IOException              When the file cannot be written to
 * @throws UnexpectedValueException When encoding the JSON fails
 */
function dumpJsonFile(
    $filename,
    $data,
    $flags = JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
)
```

#### Example

[](#example-3)

**`write-json.php`**

```
$fs->dumpJsonFile('data.json', [
  'a' => 1,
  'b' => 2,
  'c' => 3
]);
```

**`>>>`**

```
{
    "a": 1,
    "b": 2,
    "c": 3
}
```

### Read YAML Files

[](#read-yaml-files)

#### Signature

[](#signature-4)

```
/**
 * Read the contents of a file and parses them as YAML
 *
 * @param string $filename The file to read from
 * @param int    $mode     The parse mode:
 *                         `PARSE_ASSOC` to return an associative array
 *                         `PARSE_OBJECT` to return a \stdClass object
 * @return mixed The parsed YAML data
 *
 * @throws FileNotFoundException When the path does not exist or is not a file
 * @throws IOException           When the file exists but is not readable
 * @throws ParseException        When the file could not be read or the YAML is not valid
 */
function readYamlFile($filename, $mode = self::PARSE_OBJECT)
```

#### Example

[](#example-4)

**`data.yaml`**

```
a: 1
b: 2
c: 3
```

**`read-yaml.php`**

```
$fs->readYamlFile('data.yml')
```

**`>>>`**

```
stdClass Object
(
    [a] => 1
    [b] => 2
    [c] => 3
)

```

### Write YAML Files

[](#write-yaml-files)

#### Signature

[](#signature-5)

```
/**
 * Dump content into a file as YAML
 *
 * @param string $filename The file to be written to
 * @param mixed  $data     The data to write into the file
 * @param int    $inline   The level where to switch to inline YAML
 * @param int    $indent   The amount of spaces to use for indentation of nested nodes
 *
 * @throws IOException When the file cannot be written to
 */
function dumpYamlFile($filename, $data, $inline = 2, $indent = 4)
```

#### Example

[](#example-5)

**`write-yaml.php`**

```
$fs->dumpYamlFile('data.yml', [
  'a' => 1,
  'b' => 2,
  'c' => 3
]);
```

**`>>>`**

```
a: 1
b: 2
c: 3
```

### Read CSV Files

[](#read-csv-files)

#### Signature

[](#signature-6)

```
/**
 * Read the contents of a file and parses them as CSV
 *
 * @param string $filename   The file to read from
 * @param int    $mode       The parse mode:
 *                           `PARSE_ARRAY` returns each row as an array
 *                           `PARSE_ASSOC` takes the first row as headers and returns associative arrays
 *                           `PARSE_OBJECT` takes the first row as headers and returns \stdClass objects
 * @param string $delimiter  The field delimiter (one character only)
 * @param string $charset    The charset the CSV file is encoded in
 * @param string $enclosure  The field enclosure (one character only)
 * @param string $escapeChar The escape character (one character only)
 * @return mixed The parsed CSV data
 *
 * @throws FileNotFoundException    When the path does not exist or is not a file
 * @throws IOException              When the file exists but is not readable
 * @throws UnexpectedValueException When the column count is inconsistent
 */
function readCsvFile(
    $filename,
    $mode       = self::PARSE_OBJECT,
    $delimiter  = ',',
    $charset    = 'UTF-8',
    $enclosure  = '"',
    $escapeChar = '\\'
)
```

#### Example

[](#example-6)

**`data.csv`**

```
a,b,c
1,2,3
4,5,6
7,8,9
```

**`read-csv.php`**

```
$fs->readCsvFile('data.csv')
```

**`>>>`**

```
Array
(
    [0] => stdClass Object
        (
            [a] => 1
            [b] => 2
            [c] => 3
        )

    [1] => stdClass Object
        (
            [a] => 4
            [b] => 5
            [c] => 6
        )

    [2] => stdClass Object
        (
            [a] => 7
            [b] => 8
            [c] => 9
        )

)

```

### Write CSV Files

[](#write-csv-files)

#### Signature

[](#signature-7)

```
/**
 * Dump content into a file as CSV
 *
 * @param string $filename   The file to be written to
 * @param mixed  $data       The data to write into the file
 * @param string $delimiter  The field delimiter (one character only)
 * @param string $enclosure  The field enclosure (one character only)
 * @param string $escapeChar The escape character (one character only)
 * @param int    $dumpMode   How to interpret passed data (CSV_DUMP_PLAIN or CSV_DUMP_STRUCTURED)
 *
 * @throws IOException When the file cannot be written to
 */
function dumpCsvFile(
    $filename,
    $data,
    $delimiter  = ',',
    $enclosure  = '"',
    $escapeChar = '\\',
    $dumpMode   = self::CSV_DUMP_DETECT
)
```

#### Example

[](#example-7)

**`write-csv.php`**

```
$fs->dumpCsvFile('data.csv', [
    [ 'a', 'b', 'c' ],
    [  1,   2,   3  ],
    [  4,   5,   6  ],
    [  7,   8,   9  ]
]);
```

**`>>>`**

```
a,b,c
1,2,3
4,5,6
7,8,9
```

### Read PHP Files

[](#read-php-files)

Read PHP files that [`return` data](https://secure.php.net/manual/en/function.include.php#example-126).

> **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!

#### Signature

[](#signature-8)

```
/**
 * Read and return the contents of a PHP file
 *
 * @param string $filename The PHP file to include
 * @param int    $caching  The caching behaviour:
 *                         `PHP_ALLOW_CACHED` will evaluate the file only once
 *                         `PHP_INVALIDATE_CACHE` will re-evaluate it if it changed
 *                         `PHP_FORCE_INVALIDATE_CACHE` will re-evaluate it anyway
 *                          Note that only OPCache is utilized which usually is turned off in PHP CLI
 * @return mixed The data returned from the file
 *
 * @throws FileNotFoundException When the path does not exist or is not a file
 * @throws IOException           When the file exists but is not readable
 */
function readPhpFile($filename, $caching = self::PHP_ALLOW_CACHED)
```

#### Example

[](#example-8)

**`data.php`**

```