Class: I2CE FileSearch

This article desrcibes the class I2CE_FileSearch It is contained in the module I2CE in the package I2CE

The class is defined in the file: lib/I2CE_FileSearch.php

Class to handle file searching.

@package I2CE

Variables

$found_locales

The found locale(s)

. One of: FALSE, a string, or an array. The former two in the case of a single serach, the later in case of a $find_all search

• Type: protected mixed $found_locales

$preferred_locales

. Keys are categories. Values are arrrays of string, the preferred locales.

• Type: protected y $preferred_locales

$ordered_paths

• Type: protected $ordered_paths

$absolut

protected $var boolean $absolut -- wheter or not to make relative paths absolut based on the directory of the calling file

• Type: protected $absolut

$search_hidden

protected $var boolean $search_hidden. Whether or not to search hidden sub-directories

• Type: protected $search_hidden

$search_cwd

protected @var boolean $search_cwd. Whether or not to seach the current working directory

• Type: protected $search_cwd

$last_order

protected @var array $last_order values are the order of the last thing added to the category keys are the classes.

• Type: protected $last_order

$checked_directories

protected @var array $checked_directories array with keys directories and values boolean It is true if the directory has already been checked. Used to avoid recursion,

• Type: protected $checked_directories

Methods

__construct()

Constructor for the FileSearch class hidden sub-directories. At the moment it does not have meaning on non unix like platforms. search the current working directory for the file. If so, it checks there first, before the other paths. or not to make a relative path absolute when adding it.

• Signature: public function __construct($hidden,$current_working,$make_absolut)

Parameters:

• boolean $hidden
  Defaults to false. Whether or not to search
  • Default Value: false
• boolean $current_working
  Defaults to false. Whether or not to
  • Default Value: false
• boolean $make_absolut
  Defaults to false. Whether
  • Default Value: false

_resolve()

Function to search through a list of paths to find a specified file.

$regExp is a list of regular expression to match file names on.

want to search, the values are the locale they are in

otherwise we return on the first match

onto the file name.

• Signature: protected function _resolve($regExps,$paths,$find_all,$dir_prefix,$reset_found_locales)

Parameters:

• array $regExps
  If desired_file is null then, then
• array $paths
  of string. The keys are the paths we
• boolean $find_all
  If true we find all files,
• string $dir_prefix
  any directory we want to prepend
  • Default Value:
• boolean $reset_found_locales
  Defualts to false
  • Default Value: false

absolut()

Makes a relative file path or file url absolute relative to the directory that the function was called in.

consider the calling file defaults to 0 which is the file that is calling this.

• Signature: static public function absolut($path,$indx)
• Returns: string the absolute path or URL

Parameters:

• string $path
  a path or URL
• int $indx
  the index, from the top level, to
  • Default Value: 0

addPath()

A path to search for a category of files. A trailing '**' means that the paths should be added recursivley Paths are automatically checked for localized version by the presence of a 'en_US' subdirectory. specifically, if a path is added such as /my/path and there is a subdir called /my/path/en_US then all subdirectories which are in the preffered locales (or $locales below) are added.

Examples: /usr/share/fonts/ adds in this directory to the search paths /usr/share/fonts/* adds in all subdirectories /usr/share/fonts/** recusively adds in all subdirecties /usr/share/fonts/truetype/ttf* adds in all directories begining with ttf The lower the number, the higher the priority. If multiple paths share the same order, the order in which they are searched is not specfied The are also special string values of $order (all are relative to the category specified):

• 'LAST' -- add at the last added order
• 'LOWEST' -- add so it has the lowest order thus far
• 'HIGHEST' -- add so it has the highest order thus far
• 'EVEN_LOWER' -- add so it has lower order than anything thus far. This is the default behavior
• 'EVEN_HIGHER' -- add so it has higher order than anything thus far

overide (but not change) the global behaviour of this instance. It is the list of localized sub-directories to search for, if the given glob is a subdirectory.

• Signature: public function addPath($category,$path,$order,$absolut,$path_prefix,$locales)

Parameters:

• string $category
  the category of files.
• string $path
  the parh (or glob pattern for a path) to add. There a a few modifications to the globbing...
• mixed $order
  If it is a number, then it indicates the order in which this path is searched.
  • Default Value: 'EVEN_LOWER'
• boolean $absolut
  whether or not to try to make a relative path absolut. It will
  • Default Value: null
• string $path_prefix
  Defaults to null. Any prefix to add to a relative class path (if we do make absolute)
  • Default Value: null
• mixed $locales
  null(default) , string or array of string. Used to override the default locale settings when not the defaults of null.
  • Default Value: null

changeRelativeToAbsolut()

Set whether or not to make relative paths absolute

• Signature: public function changeRelativeToAbsolut($absolut)

Parameters:

• boolean $absolut

convertUnixToWin()

Convert a relative windows path with / to one with \ returns $string

• Signature: static public function convertUnixToWin($path)

Parameters:

• string $path

findByRegularExpression()

Finds all files with a given extension in the category

it is a regular expression to match file names on. It may be an array of strings, them we attempt a match against each of the regular expressions specified by the strings.

otherwise we return on the first match

onto the file name.

• Signature: public function findByRegularExpression($category,$regExps,$find_all,$dir_prefix)
• Returns: array of string

Parameters:

• string $category
• mixed $regExps
  It may be a string, in which case
• boolean $find_all
  If true we find all files,
• string $dir_prefix
  any directory we want to prepend
  • Default Value:

findWinShortFileName()

On windows, convert a given file in a given directory to a 8.3 filename

• Signature: static protected function findWinShortFileName($file,$dir)
• Returns: string

Parameters:

• string $file
• $dir

findWinShortPathName()

Attempt to convert a windows long path name to its 8.3 version

• Signature: static public function findWinShortPathName($file)
• Returns: @string

Example: C:\Program Files\my_long_dir becomes c:\program~1\my_lon~1 Parameters:

• string $file
  The absoluate path to a file/directory

getCategories()

Get the categories specified

• Signature: public function getCategories()
• Returns: array of string

getLastOrder()

Get the last order set for the specified category.

• Signature: public function getLastOrder($category)
• Returns: int

Parameters:

• string $category

getLocaleOfLastSearch()

Get the locale(s) of the results of the last search.

• Signature: public function getLocaleOfLastSearch()
• Returns: mixed. If the last search has $find_all = false then either false if no file was found or a string, the locale in which the

the results was found. If the $find_all was true, then it is an array of string, the locales of the files found.

getSearchPath()

Gets the search path for the specified catgegory

• Signature: public function getSearchPath($category,$localized)
• Returns: array. If not localized with keys integers, the

orders, and values an array of strings, the paths for that order, if $localized is TRUE, and keys are paths values are locales. Parameters:

• string $category
• boolean $localized
  (FALSE)
  • Default Value: FALSE

isAbsolut()

Checks to see if a path is absolute. All files identified by a URI/L are considered to be absolute

• Signature: static public function isAbsolut($path)
• Returns: boolean

Parameters:

• $path

limitToSubdir()

Remove sub-directories from a category

• Signature: public function limitToSubdir($category,$limit)
• Returns: array List of directories

Parameters:

• string $category
• string $limit
  The subdirectory to limit to.
  • Default Value: ""

removePath()

Remove a path in a category

relative path absolut. It will overide (but not change) the global behaviour of this instance. to add to a relative class path (if we do make absolute)

• Signature: public function removePath($category,$path,$absolut,$path_prefix)

Parameters:

• string $category
• string $path
• boolean $absolut
  whether or not to try to make a
  • Default Value: FALSE
• string $path_prefix
  Defaults to null. Any prefix
  • Default Value: NULL

removePaths()

Remove a list of paths from the category path list.

• Signature: public function removePaths($category,$path_list)
• Returns: array List of directories

Parameters:

• string $category
• array $path_list
  The subdirectory to limit to.

reset()

• Signature: public function reset()

resetFoundLocales()

Reset the found locales

• Signature: protected function resetFoundLocales($multiple)

Parameters:

• boolean $multiple
  If true setup so we are returning multiple resutls. otherwise we return a single result

resolve()

Function to search through a list of paths to find a specified file.

$regExp is a list of regular expression to match file names on.

want to search, the values are the locale they are in

otherwise we return on the first match

onto the file name.

• Signature: public function resolve($regExps,$paths,$find_all,$dir_prefix,$reset_found_locales)

Parameters:

• array $regExps
  If desired_file is null then, then
• array $paths
  of string. The keys are the paths we
• boolean $find_all
  If true we find all files,
• string $dir_prefix
  any directory we want to prepend
  • Default Value:
• boolean $reset_found_locales
  Defualts to false
  • Default Value: false

search()

Find a file (or directory) of a certain category

• Signature: public function search($category,$filename,$find_all)
• Returns: mixed. Returns either a string which is the path

and file name of the file we found, or null if we did not find the file, or an array of file names if $find_all was set to true Parameters:

• string $category
  the category of the file
• string $filename
  the file name of the file we wish to find
• boolean $find_all
  Defaults to false
  • Default Value: FALSE

searchCurrentWorkingDirectory()

• Signature: public function searchCurrentWorkingDirectory($search)

Parameters:

• $search

searchHiddenSubdirectories()

• Signature: public function searchHiddenSubdirectories($search)

Parameters:

• $search

searchPaths()

Search paths for matches to the regular expression

• Signature: public function searchPaths($find_all,$regExps,$paths,$prefix)
• Returns: array List of directories

Parameters:

• boolean $find_all
  FALSE = return only the first hit.
• array $regExps
  Regular expressions to match
• array $paths
  Paths to look in
• string $prefix
  Directory prefix

setPreferredLocales()

Set the preferred locale(s) for a category. If not set, defaults the locales default to I2CE::DEFAULT_LOCALE

• Signature: public function setPreferredLocales($category,$locales,$validate)

Parameters:

• string $category
• mixed $locales
  string or array of string. The locales.
• boolean $validate
  Defaults to true.
  • Default Value: true