/** * 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))); } }