Finder Class

The Finder class allows for searching through a search path for a given file, as well as loading a given file.

Search order

The finder uses the following search logic to locale files:

If you have enabled 'caching' in your app/config.php, and you have defined a valid cache path, the finder will cache all files found, so it doesn't have to crawl the disk the next time a file is looked for. You can also specify the cache lifetime in your config file.

forge($paths = array())

The forge method returns a new finder object.

Static Yes
Parameters
Param Default Description
$paths 
array()
 Array of paths to initialise this finder instance with.
Returns Finder Object
Example 
$array = array(APPPATH, COREPATH);
$finder = Finder::forge($array));

instance()

The instance method returns the singleton object of the Finder. This instance is also used by the FuelPHP core classes to find files, and is instantiated when first called with the APPPATH and COREPATH as default search paths.

Static Yes
Parameters None
Returns Finder Object
Example 
$finder = Finder::instance();

The search method is a static alias for locate() on the default finder instance.

Static Yes
Parameters
Param Default Description
$dir string Relative directory to search in. It is appended to all search paths defined when trying to locate the file.
$file string Basename of the file to find.
$ext 
'.php'
 Extension of the file to find. This MUST include the leading dot.
$multiple 
false
 If false, stop searching at the first file found. If true, search all paths, and return all files found as an array.
$cache 
true
 If true, cache the results for subsequent requests to prevent unnecessary disk access.
Mixed The fully qualified path of the file found, or false if no file was found. In case of a multiple search, an array of paths found is returned, or an empty array if no files were found.
Example 
// will return APPPATH/views/welcome/index.php
$viewfile = Finder::search('views', 'welcome/index');

// assuming we're in active module called "test", and requested all files, this could
// return array("MODULEPATH/test/lang/en/welcome.php", "APPPATH/lang/en/welcome.php")
$lang = Finder::search('lang/en', 'welcome');

// searching explicitly in the module, this would return
// array("MODULEPATH/test/lang/en/welcome.php")
$lang = Finder::search('test::lang/en', 'welcome', '.php', true);

// searching explicitly in the app, this would return
// array("APPPATH/lang/en/welcome.php")
$lang = Finder::search('::lang/en', 'welcome', '.php', true);

add_path($paths, $pos = null)

The add_path method adds a new search path to the Finder instance, at the given position.

Static No
Parameters
Param Default Description
$paths mixed Path or array of paths to add to the Finder's instance search paths.
$pos 
null
 The position at which the path should be added to the list. Possible options are: null to append at the end of the list, -1 to prepend at the start of the list, or index to insert the path AFTER in the list after the given index number.
Returns The current object for chaining
Thows OutOfBoundsException, when the given index position is out of range.
Example 
// make sure the finder searches 'mypackage' first
Finder::instance()->add_path(PKGPATH.'mypackage', -1);

remove_path($path)

The remove_path method removes the given path from the Finder instance search list.

Static No
Parameters
Param Default Description
$path string Path to remove.
Returns The current object for chaining
Example 
// remove 'mypackage' from the search path list
Finder::instance()->remove_path(PKGPATH.'mypackage');

paths()

The paths method returns the list of defined search paths.

Static No
Parameters None
Returns array of paths
Example 
// fetch the defined paths for the default instance.
$paths = Finder::instance()->paths();
print_r($paths);

list_files($directory = null, $filter = '*.php')

The list_files method gets a list of all the files in a given directory inside all of the loaded search paths (e.g. the cascading file system). This is useful for things like finding all the config files in all the search paths.

Static No
Parameters
Param Default Description
$directory 
null
 Relative path from which to list the files. The path will be appended to all defined search paths.
$filter 
'*.php'
 Type of files to look for.
Returns array, list of fully qualified filenames of all files found
Example 
// find all database config files
$dbcfg = Finder::instance()->list_files('config', 'db.php');

This method is aware of the current request context. This means that when the active request is an HMVC call to a module controller, the module paths is dynamically added to the list of paths to search.

locate($dir, $file, $ext = '.php', $multiple = false, $cache = true)

The locate method locates files in the defined search paths.

Static No
Parameters
Param Default Description
$dir string Relative directory to search in. It is appended to all search paths defined when trying to locate the file.
$file string Basename of the file to find.
$ext 
'.php'
 Extension of the file to find. This MUST include the leading dot.
$multiple 
false
 If false, stop searching at the first file found. If true, search all paths, and return all files found as an array.
$cache 
true
 If true, cache the results for subsequent requests to prevent unnecessary disk access.
Mixed The fully qualified path of the file found, or false if no file was found. In case of a multiple search, an array of paths found is returned, or an empty array if no files were found.
Example 
// will return APPPATH/views/welcome/index.php
$viewfile = Finder::instance()->locate('views', 'welcome/index');

// assuming we're in active module called "test", and requested all files, this could
// return array("MODULEPATH/test/lang/en/welcome.php", "APPPATH/lang/en/welcome.php")
$lang = Finder::instance()->locate('lang/en', 'welcome');

// searching explicitly in the module, this would return
// array("MODULEPATH/test/lang/en/welcome.php")
$lang = Finder::instance()->locate('test::lang/en', 'welcome', '.php', true);

// searching explicitly in the app, this would return
// array("APPPATH/lang/en/welcome.php")
$lang = Finder::instance()->locate('::lang/en', 'welcome', '.php', true);