Finder 类別
Finder 类別能透過搜尋路徑尋找所給的档案，以及載入所給的档案。
搜尋順序
Finder 使用下列搜尋邏輯來定位档案：
- 如果有定義任何快閃路徑，这些会依定義順序先被搜尋
- 如果目前請求情境是模組，該模組将接著被搜尋
- 如果有定義任何請求路徑，这些会依定義順序接著搜尋
- 接著，搜尋 APPPATH
- 所有載入的套件会被搜尋
- 以及最後，COREPATH 会被搜尋
如果你在你的 app/config.php 啟用 'caching'，而且你已定義有效的快取路徑，
Finder 会快取所有找到的档案，如此一來，下次尋找档案時就不必抓取硬碟。
你也可以在你的配置档案中指定快取生存時間。
forge($paths = array())
forge 回傳一个新的 Finder 物件。
| 靜態 |
是 |
| 參数 |
| 參数 |
預設 |
描述 |
| $paths |
array()
|
要給此 Finder 實例初始化的路徑陣列。 |
|
| 回傳 |
Finder 物件 |
| 範例 |
$array = array(APPPATH, COREPATH);
$finder = Finder::forge($array));
|
instance()
instance 方法回傳 Finder 物件的獨體。
这个實例也被 FuelPHP 核心类別用來尋找档案，并且在第一次呼叫時会初始化，
帶著 APPPATH 和 COREPATH 做为預設搜尋路徑。
| 靜態 |
是 |
| 參数 |
無
|
| 回傳 |
Finder 物件 |
| 範例 |
$finder = Finder::instance();
|
search($dir, $file, $ext = '.php', $multiple = false, $cache = true)
search 方法是在預設 Finder 實例上 locate() 的靜態別名。
| 靜態 |
是 |
| 參数 |
| 參数 |
預設 |
描述 |
| $dir |
字串 |
相對於要搜尋的目录。當试著要定位档案時，它被附加到所有定義的搜尋路徑。 |
| $file |
字串 |
要尋找档案的主档名。 |
| $ext |
'.php'
|
要尋找档案的副档名。这必須包含開頭的點。 |
| $multiple |
false
|
如果为 false，在第一个档案找到時停止搜尋。如果为 true，搜尋所有路徑，并回傳所有找到的档案做为一个陣列。 |
| $cache |
true
|
如果为 true，为隨後的請求快取結果，來避免不必要的硬碟存取。 |
|
| 混合 |
找到档案的完整路徑，或 false 如果沒找到档案。
在一个多重搜尋的情況下，一个找到路徑的陣列会被回傳，或當沒有档案被找到時是一个空陣列。 |
| 範例 |
// 将回傳 APPPATH/views/welcome/index.php
$viewfile = Finder::search('views', 'welcome/index');
|
add_path($paths, $pos = null)
add_path 方法添加一个新搜尋路徑到 Finder 實例，在所給的位置。
| 靜態 |
否 |
| 參数 |
| 參数 |
預設 |
描述 |
| $paths |
混合 |
要添加給 Finder 實例搜尋路徑的路徑或路徑陣列。 |
| $pos |
null
|
路徑應該被添加到列表的位置。
可能的選項有：
null 以附加到列表結尾，
-1 以附加在列表開頭，或
index 以在列表中所給索引之後插入該路徑。
|
|
| 回傳 |
用來鍊結的目前物件 |
| 拋出 |
OutOfBoundsException，當所給的索引位置超出範圍。 |
| 範例 |
// 確保 Finder 最先搜尋 'mypackage'
Finder::instance()->add_path(PKGPATH.'mypackage', -1);
|
remove_path($path)
remove_path 方法從 Finder 實例搜尋列表移除所給的路徑。
| 靜態 |
否 |
| 參数 |
| 參数 |
預設 |
描述 |
| $path |
字串 |
要移除的路徑。 |
|
| 回傳 |
用來鍊結的目前物件 |
| 範例 |
// 從搜尋路徑列表移除 'mypackage'
Finder::instance()->remove_path(PKGPATH.'mypackage');
|
paths()
paths 方法回傳定義的搜尋路徑列表。
| 靜態 |
否 |
| 參数 |
無
|
| 回傳 |
路徑陣列 |
| 範例 |
// 取回給預設實例的定義路徑。
$paths = Finder::instance()->paths();
print_r($paths);
|
list_files($directory = null, $filter = '*.php')
list_files 方法取得一个在所給目录中所有已載入的搜尋路徑裡的所有档案的列表
（例如級聯式的档案系统）。
这在像從所有搜尋路徑中尋找所有配置是非常有用的。
| 靜態 |
否 |
| 參数 |
| 參数 |
預設 |
描述 |
| $directory |
null
|
對要列出档案目录的相對路徑。該路徑将被附加到所有定義的搜尋路徑。 |
| $filter |
'*.php'
|
要尋找的档案类型。 |
|
| 回傳 |
陣列，所有找到档案的完整路徑列表 |
| 範例 |
// 尋找所有資料庫配置档案
$dbcfg = Finder::instance()->list_files('config', 'db.php');
|
这个方法会了解目前請求的情境。这意味著當活躍的請求是一个 HMVC 呼叫到一个模組控制器時，
模組路徑会动態添加到要搜尋的路徑列表。
locate($dir, $file, $ext = '.php', $multiple = false, $cache = true)
locate 方法在定義搜尋路徑中定位档案。
| 靜態 |
否 |
| 參数 |
| 參数 |
預設 |
描述 |
| $dir |
字串 |
相對於要搜尋的目录。當试著要定位档案時，它被附加到所有定義的搜尋路徑。 |
| $file |
字串 |
要尋找档案的主档名。 |
| $ext |
'.php'
|
要尋找档案的副档名。这必須包含開頭的點。 |
| $multiple |
false
|
如果为 false，在第一个档案找到時停止搜尋。如果为 true，搜尋所有路徑，并回傳所有找到的档案做为一个陣列。 |
| $cache |
true
|
如果为 true，为隨後的請求快取結果，來避免不必要的硬碟存取。 |
|
| 混合 |
找到档案的完整路徑，或 false 如果沒找到档案。
在一个多重搜尋的情況下，一个找到路徑的陣列会被回傳，或當沒有档案被找到時是一个空陣列。 |
| 範例 |
// 将回傳 APPPATH/views/welcome/index.php
$viewfile = Finder::instance()->locate('views', 'welcome/index');
|