README

扩展文件系统

Symfony 的 文件系统组件 的扩展，具有以下功能：

• 递归 glob 查找支持
• 读取和写入一些流行的数据交换格式（PHP、JSON、YAML、CSV）的方法

安装

composer require loilo/x-filesystem

用法

XFilesystem 的实例化方式与 Filesystem 完全相同

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

不会修改现有的行为，Filesystem 中可用的每个方法都按预期工作。

通过 Globs 查找文件

此方法与 PHP 内置的 glob 函数 的行为相匹配，但增加了对递归通配符 /**/ 的支持

签名

/**
 * Find files by a glob. As opposed to PHP's built-in "glob" function, this method supports the ** wildcard.
 * @see https://php.ac.cn/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)

示例

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

读取普通文件

Filesystem 没有内置的读取普通文件的方法，所以在这里我们提供

签名

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

示例

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

从 URL 读取文件

默认情况下，当读取文件时，不允许使用 HTTP(S) URL 作为文件名。但是，可以通过设置 remoteAllowed 标志进行调整

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

相反，您可以通过 $fs->isRemoteAllowed() 检查远程访问是否启用。

读取 JSON 文件

签名

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

示例

data.json

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

read-json.php

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

>>>

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

写入 JSON 文件

签名

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

示例

write-json.php

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

>>>

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

读取 YAML 文件

签名

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

示例

data.yaml

a: 1
b: 2
c: 3

read-yaml.php

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

>>>

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

写入 YAML 文件

签名

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

示例

write-yaml.php

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

>>>

a: 1
b: 2
c: 3

读取 CSV 文件

签名

/**
 * 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 = '\\'
)

示例

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
        )

)

写入 CSV 文件

签名

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

示例

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

读取 PHP 文件

读取 return 数据 的 PHP 文件。

警告！ 此方法利用 PHP 的 include 语句，并且没有通过任意代码执行来防止可能的副作用和滥用。仅使用受信任的文件！

签名

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

示例

data.php

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

read-php.php

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

写入 PHP 文件

签名

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

示例

write-php.php

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

>>>

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