/**
* Imports a class or a directory.
*
* Importing a class is like including the corresponding class file.
* The main difference is that importing a class is much lighter because it only
* includes the class file when the class is referenced the first time.
*
* Importing a directory is equivalent to adding a directory into the PHP include path.
* If multiple directories are imported, the directories imported later will take
* precedence in class file searching (i.e., they are added to the front of the PHP include path).
*
* Path aliases are used to import a class or directory. For example,
* <ul>
* <li><code>application.components.GoogleMap</code>: import the <code>GoogleMap</code> class.</li>
* <li><code>application.components.*</code>: import the <code>components</code> directory.</li>
* </ul>
*
* The same path alias can be imported multiple times, but only the first time is effective.
* Importing a directory does not import any of its subdirectories.
*
* Starting from version 1.1.5, this method can also be used to import a class in namespace format
* (available for PHP 5.3 or above only). It is similar to importing a class in path alias format,
* except that the dot separator is replaced by the backslash separator. For example, importing
* <code>application\components\GoogleMap</code> is similar to importing <code>application.components.GoogleMap</code>.
* The difference is that the former class is using qualified name, while the latter unqualified.
*
* Note, importing a class in namespace format requires that the namespace corresponds to
* a valid path alias once backslash characters are replaced with dot characters.
* For example, the namespace <code>application\components</code> must correspond to a valid
* path alias <code>application.components</code>.
*
* @param string $alias path alias to be imported
* @param boolean $forceInclude whether to include the class file immediately. If false, the class file
* will be included only when the class is being used. This parameter is used only when
* the path alias refers to a class.
* @return string the class name or the directory that this alias refers to
* @throws CException if the alias is invalid
*/
public static function import($alias, $forceInclude = false)
{
if (isset(self::$_imports[$alias])) {
// previously imported
return self::$_imports[$alias];
}
if (class_exists($alias, false) || interface_exists($alias, false)) {
return self::$_imports[$alias] = $alias;
}
if (($pos = strrpos($alias, '\\')) !== false) {
$namespace = str_replace('\\', '.', ltrim(substr($alias, 0, $pos), '\\'));
if (($path = self::getPathOfAlias($namespace)) !== false) {
$classFile = $path . DIRECTORY_SEPARATOR . substr($alias, $pos + 1) . '.php';
if ($forceInclude) {
if (is_file($classFile)) {
require $classFile;
} else {
throw new CException(Yii::t('yii', 'Alias "{alias}" is invalid. Make sure it points to an existing PHP file and the file is readable.', array('{alias}' => $alias)));
}
self::$_imports[$alias] = $alias;
} else {
self::$classMap[$alias] = $classFile;
}
return $alias;
} else {
// try to autoload the class with an autoloader
if (class_exists($alias, true)) {
return self::$_imports[$alias] = $alias;
} else {
throw new CException(Yii::t('yii', 'Alias "{alias}" is invalid. Make sure it points to an existing directory or file.', array('{alias}' => $namespace)));
}
}
}
if (($pos = strrpos($alias, '.')) === false) {
// try to autoload the class with an autoloader if $forceInclude is true
if ($forceInclude && (Yii::autoload_1($alias, true) || class_exists($alias, true))) {
self::$_imports[$alias] = $alias;
}
return $alias;
}
$className = (string) substr($alias, $pos + 1);
$isClass = $className !== '*';
if ($isClass && (class_exists($className, false) || interface_exists($className, false))) {
return self::$_imports[$alias] = $className;
}
if (($path = self::getPathOfAlias($alias)) !== false) {
if ($isClass) {
if ($forceInclude) {
if (is_file($path . '.php')) {
require $path . '.php';
} else {
throw new CException(Yii::t('yii', 'Alias "{alias}" is invalid. Make sure it points to an existing PHP file and the file is readable.', array('{alias}' => $alias)));
}
self::$_imports[$alias] = $className;
} else {
self::$classMap[$className] = $path . '.php';
}
return $className;
} else {
if (self::$_includePaths === null) {
self::$_includePaths = array_unique(explode(PATH_SEPARATOR, get_include_path()));
if (($pos = array_search('.', self::$_includePaths, true)) !== false) {
unset(self::$_includePaths[$pos]);
}
}
array_unshift(self::$_includePaths, $path);
if (self::$enableIncludePath && set_include_path('.' . PATH_SEPARATOR . implode(PATH_SEPARATOR, self::$_includePaths)) === false) {
self::$enableIncludePath = false;
}
return self::$_imports[$alias] = $path;
}
} else {
throw new CException(Yii::t('yii', 'Alias "{alias}" is invalid. Make sure it points to an existing directory or file.', array('{alias}' => $alias)));
}
}
