README

Boondoc/PathList 是一个特性，用于将经过验证的文件系统路径列表附加到类中以进行迭代。

包括静态和非静态方法，允许类的实例迭代私有路径列表、所有其他该类实例共享的列表或两者的组合。

替代方案

该项目具有故意狭窄的范围，可能不是你想要的内容。

• 如果你想要创建、删除或以其他方式操作文件或目录，你可能想要 symfony/filesystem（有关更多信息，请参阅 文件系统工具）。
• 如果你想要对路径字符串执行合理的字符串操作，例如在绝对和相对文件路径之间进行转换，但不关心这些路径是否是服务器上的真实文件系统位置，你 也 可能需要 symfony/filesystem（有关更多信息，请参阅 路径操作工具）。

安装

使用 Composer

composer require boondoc/path-list

手动安装

下载文件 path-list.php 并使用 require 语句将其包含在您的代码中。

用法

导入特性

use Boondoc\PathList;

将其添加到您的类中

class EG
{
	use PathList;
};

以下示例假设如下目录结构

/
+-- alpha
+-- bravo
|   +-- charlie
|   +-- delta		// Code is being executed here
+-- echo
+-- foxtrot
|   +-- golf
|   +-- hotel
|       +-- india
+-- juliet
    +-- kilo
        +-- lima.txt

静态路径收集

将路径数组静态传递以使其在所有类实例之间共享。

EG::pathsSet (['../charlie', '/xray', '/foxtrot/hotel/india']);
					// Two of three supplied paths actually exist
					// Non-existent path is discarded, others are canonicalised

EG::pathsGet ();			// Returns ['/bravo/charlie', '/foxtrot/hotel/india']

EG::pathsHas ('../charlie');		// Returns '/bravo/charlie'
EG::pathsHas ('/xray');			// Returns false
EG::pathsHas ('/alpha');		// Returns false

EG::pathsSet (['/xray']);		// Throws a Boondoc\PathList\NoRealPathsSupplied exception
EG::pathsSet ([]);			// Empty array clears collection, no exception thrown

EG::pathsHas ('../charlie');		// Returns false

所有路径字符串都会自动通过 realpath，那些返回 false 的将被丢弃。如果数组中的所有路径都无法解析，则抛出异常。

如果多个路径字符串解析到相同的绝对文件系统位置，则仅保留第一个，其余的将被丢弃。

非静态路径收集

将路径数组传递给类以使其对该类私有。

$a = new EG ();
$b = new EG ();

$a->pathsSetOwn (['../../alpha', '/september', '/foxtrot/hotel/india']);
$b->pathsSetOwn (['/echo', '/zulu', '/echo']);

$a->pathsGetOwn ();			// Returns ['/alpha', '/foxtrot/hotel/india']
$b->pathsGetOwn ();			// Returns ['/echo']

$a->pathsHasOwn ('../../alpha');	// Returns '/alpha'
$a->pathsHasOwn ('/echo');		// Returns false
$a->pathsHasOwn ('/bravo');		// Returns false
$b->pathsHasOwn ('../../alpha');	// Returns false
$b->pathsHasOwn ('/echo');		// Returns '/echo'
$b->pathsHasOwn ('/bravo');		// Returns false

传递给 ->pathsSetOwn 的数组与其他传递给 ::pathsSet 的数组处理方式相同。

组合路径收集

一旦定义了静态和/或非静态收集，就可以检索单个组合数组。非静态收集中的路径将首先出现在数组中，然后是静态收集中的路径。如果路径出现在两个收集中，则非静态出现将形成组合数组的一部分，而静态收集中的重复项将被省略。

$a = new EG ();
$b = new EG ();
$c = new EG ();

EG::pathsSet (['../charlie', '/xray', '/foxtrot/hotel/india']);
$a->pathsSetOwn (['../../alpha', '/september', '/foxtrot/hotel/india']);
$b->pathsSetOwn (['/echo', '/zulu', '/echo']);

$a->pathsGetAll ():			// Returns ['/alpha', '/foxtrot/hotel/india', '/bravo/charlie']
$b->pathsGetAll ();			// Returns ['/echo', '/bravo/charlie', '/foxtrot/hotel/india']
$c->pathsGetAll ();			// Returns ['/bravo/charlie', '/foxtrot/hotel/india']

$a->pathsHasAll ('../../alpha');	// Returns '/alpha'
$a->pathsHasAll ('../charlie');		// Returns '/bravo/charlie'
$a->pathsHasAll ('/echo');		// Returns false
$b->pathsHasAll ('../../alpha');	// Returns false
$a->pathsHasAll ('../charlie');		// Returns '/bravo/charlie'
$b->pathsHasAll ('/echo');		// Returns '/echo'
$c->pathsHasAll ('../../alpha');	// Returns false
$c->pathsHasAll ('../charlie');		// Returns '/bravo/charlie'
$c->pathsHasAll ('/echo');		// Returns false

文件查找

可以查询这些收集以查看给定的子路径字符串是否解析为任何路径中的真实文件名，如果是，则返回完全解析的文件系统位置。

$a = new EG ();

EG::pathsSet (['/juliet/kilo']);

$a->pathsFind ('lima.txt');		// Returns '/juliet/kilo/lima.txt'
$a->pathsFind ('kilo/lima.txt');	// Returns false

$a->pathsFindOwn ('lima.txt');		// Returns false
$a->pathsFindOwn ('kilo/lima.txt');	// Returns false

$a->pathsFindAll ('lima.txt');		// Returns '/juliet/kilo/lima.txt'
$a->pathsFindAll ('kilo/lima.txt');	// Returns false

EG::pathsSet ([]);
$a->pathsSetOwn (['/juliet']);

$a->pathsFind ('lima.txt');		// Returns false
$a->pathsFind ('kilo/lima.txt');	// Returns false

$a->pathsFindOwn ('lima.txt');		// Returns false
$a->pathsFindOwn ('kilo/lima.txt');	// Returns '/juliet/kilo/lima.txt'

$a->pathsFindAll ('lima.txt');		// Returns false
$a->pathsFindAll ('kilo/lima.txt');	// Returns '/juliet/kilo/lima.txt'

请注意，这并非完全递归的文件名搜索：提供的子路径字符串将直接附加到收集中的每个路径，并测试是否存在此类文件系统对象，返回第一个成功的结果作为字符串，如果找不到则返回 false。

异常

在正常操作期间，可能会抛出以下异常

• \Boondoc\PathList\NoRealPathsSupplied：传递给 ::pathsSet 或 ->pathsSetOwn 的路径中没有任何一个可以解析为真实的文件系统位置。
• \Boondoc\PathList\Exception：抽象类型，从不显式抛出；捕获以涵盖所有上述情况。

这些异常仅用于捕获，不应需要显式抛出。

上述所有异常都包含一个新方法 ->getValue ()，该方法返回错误值而不包括消息字符串的其余部分。