README

eXtended Filesystem

An extension to Symfony's Filesystem Component with

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

Installation

composer require loilo/x-filesystem

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

This method matches the behavior of PHP's built-in glob function, but adds support for the recursive wildcard /**/:

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

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

Read Plain Files

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

Signature

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

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

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

Signature

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

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

Signature

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

write-json.php

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

>>>

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

Read YAML Files

Signature

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

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

Signature

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

write-yaml.php

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

>>>

a: 1
b: 2
c: 3

Read CSV Files

Signature

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

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

Signature

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

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 that return data.

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

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

data.php

<?php return [
  'a' => 1,
  'b' => 2,
  'c' => 3
]

read-php.php

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

Write PHP Files

Signature

/**
 * Dump data into a file as PHP
 *
 * @param string $filename The file to be written to
 * @param string $data     The data to write into the file
 *
 * @throws IOException When the file cannot be written to
 */
function dumpPhpFile($filename, $data)

Example

write-php.php

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

>>>

<?php return array(
  'a' => 1,
  'b' => 2,
  'c' => 3
);