YiiBase.php 20.9 KB
Newer Older
Qiang Xue committed
1
<?php
w  
Qiang Xue committed
2 3
/**
 * @link http://www.yiiframework.com/
Qiang Xue committed
4
 * @copyright Copyright (c) 2008 Yii Software LLC
w  
Qiang Xue committed
5 6
 * @license http://www.yiiframework.com/license/
 */
Qiang Xue committed
7
use yii\base\Exception;
Qiang Xue committed
8
use yii\base\InvalidConfigException;
Qiang Xue committed
9
use yii\base\InvalidParamException;
Qiang Xue committed
10
use yii\base\UnknownClassException;
Qiang Xue committed
11
use yii\logging\Logger;
Qiang Xue committed
12

Qiang Xue committed
13
/**
w  
Qiang Xue committed
14
 * Gets the application start timestamp.
Qiang Xue committed
15
 */
w  
Qiang Xue committed
16
defined('YII_BEGIN_TIME') or define('YII_BEGIN_TIME', microtime(true));
Qiang Xue committed
17 18 19
/**
 * This constant defines whether the application should be in debug mode or not. Defaults to false.
 */
w  
Qiang Xue committed
20
defined('YII_DEBUG') or define('YII_DEBUG', false);
Qiang Xue committed
21 22 23 24 25
/**
 * This constant defines how much call stack information (file name and line number) should be logged by Yii::trace().
 * Defaults to 0, meaning no backtrace information. If it is greater than 0,
 * at most that number of call stacks will be logged. Note, only user application call stacks are considered.
 */
w  
Qiang Xue committed
26
defined('YII_TRACE_LEVEL') or define('YII_TRACE_LEVEL', 0);
Qiang Xue committed
27
/**
w  
Qiang Xue committed
28
 * This constant defines the framework installation directory.
Qiang Xue committed
29
 */
w  
Qiang Xue committed
30
defined('YII_PATH') or define('YII_PATH', __DIR__);
Qiang Xue committed
31 32 33 34 35
/**
 * This constant defines whether error handling should be enabled. Defaults to true.
 */
defined('YII_ENABLE_ERROR_HANDLER') or define('YII_ENABLE_ERROR_HANDLER', true);

w  
Qiang Xue committed
36

Qiang Xue committed
37
/**
w  
Qiang Xue committed
38
 * YiiBase is the core helper class for the Yii framework.
Qiang Xue committed
39
 *
w  
Qiang Xue committed
40
 * Do not use YiiBase directly. Instead, use its child class [[Yii]] where
Qiang Xue committed
41 42 43
 * you can customize methods of YiiBase.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
w  
Qiang Xue committed
44
 * @since 2.0
Qiang Xue committed
45 46 47 48 49
 */
class YiiBase
{
	/**
	 * @var array class map used by the Yii autoloading mechanism.
50
	 * The array keys are the class names (without leading backslashes), and the array values
Qiang Xue committed
51 52
	 * are the corresponding class file paths (or path aliases). This property mainly affects
	 * how [[autoload()]] works.
Qiang Xue committed
53 54
	 * @see import
	 * @see autoload
w  
Qiang Xue committed
55 56 57
	 */
	public static $classMap = array();
	/**
Qiang Xue committed
58 59
	 * @var boolean whether to search PHP include_path when autoloading unknown classes.
	 * You may want to turn this off if you are also using autoloaders from other libraries.
w  
Qiang Xue committed
60
	 */
Qiang Xue committed
61
	public static $enableIncludePath = true;
w  
Qiang Xue committed
62
	/**
Qiang Xue committed
63
	 * @var yii\console\Application|yii\web\Application the application instance
Qiang Xue committed
64
	 */
Qiang Xue committed
65
	public static $app;
w  
Qiang Xue committed
66 67
	/**
	 * @var array registered path aliases
Qiang Xue committed
68 69
	 * @see getAlias
	 * @see setAlias
w  
Qiang Xue committed
70 71
	 */
	public static $aliases = array(
w  
Qiang Xue committed
72
		'@yii' => __DIR__,
w  
Qiang Xue committed
73
	);
Qiang Xue committed
74 75
	/**
	 * @var array initial property values that will be applied to objects newly created via [[createObject]].
Qiang Xue committed
76 77
	 * The array keys are class names without leading backslashes "\", and the array values are the corresponding
	 * name-value pairs for initializing the created class instances. For example,
Qiang Xue committed
78 79 80
	 *
	 * ~~~
	 * array(
Qiang Xue committed
81
	 *     'Bar' => array(
Qiang Xue committed
82 83 84
	 *         'prop1' => 'value1',
	 *         'prop2' => 'value2',
	 *     ),
Qiang Xue committed
85
	 *     'mycompany\foo\Car' => array(
Qiang Xue committed
86 87 88 89 90 91 92 93 94
	 *         'prop1' => 'value1',
	 *         'prop2' => 'value2',
	 *     ),
	 * )
	 * ~~~
	 *
	 * @see createObject
	 */
	public static $objectConfig = array();
Qiang Xue committed
95

Qiang Xue committed
96
	private static $_imported = array(); // alias => class name or directory
w  
Qiang Xue committed
97
	private static $_logger;
Qiang Xue committed
98 99 100 101 102 103

	/**
	 * @return string the version of Yii framework
	 */
	public static function getVersion()
	{
w  
Qiang Xue committed
104
		return '2.0-dev';
Qiang Xue committed
105 106 107
	}

	/**
Qiang Xue committed
108
	 * Imports a class by its alias.
Qiang Xue committed
109
	 *
Qiang Xue committed
110 111 112
	 * This method is provided to support autoloading of non-namespaced classes.
	 * Such a class can be specified in terms of an alias. For example, the alias `@old/code/Sample`
	 * may represent the `Sample` class under the directory `@old/code` (a path alias).
Qiang Xue committed
113
	 *
Qiang Xue committed
114 115 116 117
	 * By importing a class, the class is put in an internal storage such that when
	 * the class is used for the first time, the class autoloader will be able to
	 * find the corresponding class file and include it. For this reason, this method
	 * is much lighter than `include()`.
Qiang Xue committed
118
	 *
Qiang Xue committed
119
	 * You may import the same class multiple times. Only the first importing will count.
Qiang Xue committed
120
	 *
Qiang Xue committed
121 122 123 124
	 * @param string $alias the class to be imported. This may be either a class alias or a fully-qualified class name.
	 * If the latter, it will be returned back without change.
	 * @return string the actual class name that `$alias` refers to
	 * @throws Exception if the alias is invalid
Qiang Xue committed
125
	 */
Qiang Xue committed
126
	public static function import($alias)
Qiang Xue committed
127
	{
Qiang Xue committed
128
		if (strncmp($alias, '@', 1)) {
Qiang Xue committed
129
			return $alias;
Qiang Xue committed
130 131 132 133
		} else {
			$alias = static::getAlias($alias);
			if (!isset(self::$_imported[$alias])) {
				$className = basename($alias);
w  
Qiang Xue committed
134
				self::$_imported[$alias] = $className;
Qiang Xue committed
135
				self::$classMap[$className] = $alias . '.php';
w  
Qiang Xue committed
136
			}
Qiang Xue committed
137
			return self::$_imported[$alias];
Qiang Xue committed
138 139 140
		}
	}

141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164
	/**
	 * Imports a set of namespaces.
	 *
	 * By importing a namespace, the method will create an alias for the directory corresponding
	 * to the namespace. For example, if "foo\bar" is a namespace associated with the directory
	 * "path/to/foo/bar", then an alias "@foo/bar" will be created for this directory.
	 *
	 * This method is typically invoked in the bootstrap file to import the namespaces of
	 * the installed extensions. By default, Composer, when installing new extensions, will
	 * generate such a mapping file which can be loaded and passed to this method.
	 *
	 * @param array $namespaces the namespaces to be imported. The keys are the namespaces,
	 * and the values are the corresponding directories.
	 */
	public static function importNamespaces($namespaces)
	{
		foreach ($namespaces as $name => $path) {
			if ($name !== '') {
				$name = '@' . str_replace('\\', '/', $name);
				static::setAlias($name, $path);
			}
		}
	}

Qiang Xue committed
165
	/**
w  
Qiang Xue committed
166
	 * Translates a path alias into an actual path.
m  
Qiang Xue committed
167
	 *
168
	 * The translation is done according to the following procedure:
m  
Qiang Xue committed
169
	 *
170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186
	 * 1. If the given alias does not start with '@', it is returned back without change;
	 * 2. Otherwise, look for the longest registered alias that matches the beginning part
	 *    of the given alias. If it exists, replace the matching part of the given alias with
	 *    the corresponding registered path.
	 * 3. Throw an exception or return false, depending on the `$throwException` parameter.
	 *
	 * For example, by default '@yii' is registered as the alias to the Yii framework directory,
	 * say '/path/to/yii'. The alias '@yii/web' would then be translated into '/path/to/yii/web'.
	 *
	 * If you have registered two aliases '@foo' and '@foo/bar'. Then translating '@foo/bar/config'
	 * would replace the part '@foo/bar' (instead of '@foo') with the corresponding registered path.
	 * This is because the longest alias takes precedence.
	 *
	 * However, if the alias to be translated is '@foo/barbar/config', then '@foo' will be replaced
	 * instead of '@foo/bar', because '/' serves as the boundary character.
	 *
	 * Note, this method does not check if the returned path exists or not.
w  
Qiang Xue committed
187
	 *
Qiang Xue committed
188
	 * @param string $alias the alias to be translated.
Qiang Xue committed
189 190
	 * @param boolean $throwException whether to throw an exception if the given alias is invalid.
	 * If this is false and an invalid alias is given, false will be returned by this method.
Qiang Xue committed
191
	 * @return string|boolean the path corresponding to the alias, false if the root alias is not previously registered.
Qiang Xue committed
192
	 * @throws InvalidParamException if the alias is invalid while $throwException is true.
w  
Qiang Xue committed
193
	 * @see setAlias
Qiang Xue committed
194
	 */
Qiang Xue committed
195
	public static function getAlias($alias, $throwException = true)
Qiang Xue committed
196
	{
197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212
		if (strncmp($alias, '@', 1)) {
			// not an alias
			return $alias;
		}

		$pos = strpos($alias, '/');
		$root = $pos === false ? $alias : substr($alias, 0, $pos);

		if (isset(self::$aliases[$root])) {
			if (is_string(self::$aliases[$root])) {
				return $pos === false ? self::$aliases[$root] : self::$aliases[$root] . substr($alias, $pos);
			} else {
				foreach (self::$aliases[$root] as $name => $path) {
					if (strpos($alias . '/', $name . '/') === 0) {
						return $path . substr($alias, strlen($name));
					}
Qiang Xue committed
213
				}
Qiang Xue committed
214 215
			}
		}
216

Qiang Xue committed
217 218 219 220 221
		if ($throwException) {
			throw new InvalidParamException("Invalid path alias: $alias");
		} else {
			return false;
		}
Qiang Xue committed
222 223
	}

Qiang Xue committed
224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249
	/**
	 * Returns the root alias part of a given alias.
	 * A root alias is an alias that has been registered via [[setAlias()]] previously.
	 * If a given alias matches multiple root aliases, the longest one will be returned.
	 * @param string $alias the alias
	 * @return string|boolean the root alias, or false if no root alias is found
	 */
	public static function getRootAlias($alias)
	{
		$pos = strpos($alias, '/');
		$root = $pos === false ? $alias : substr($alias, 0, $pos);

		if (isset(self::$aliases[$root])) {
			if (is_string(self::$aliases[$root])) {
				return $root;
			} else {
				foreach (self::$aliases[$root] as $name => $path) {
					if (strpos($alias . '/', $name . '/') === 0) {
						return $name;
					}
				}
			}
		}
		return false;
	}

Qiang Xue committed
250
	/**
w  
Qiang Xue committed
251
	 * Registers a path alias.
m  
Qiang Xue committed
252
	 *
253 254
	 * A path alias is a short name representing a long path (a file path, a URL, etc.)
	 * For example, we use '@yii' as the alias of the path to the Yii framework directory.
m  
Qiang Xue committed
255
	 *
256 257
	 * A path alias must start with the character '@' so that it can be easily differentiated
	 * from non-alias paths.
m  
Qiang Xue committed
258
	 *
259 260 261 262 263 264 265 266 267 268
	 * Note that this method does not check if the given path exists or not. All it does is
	 * to associate the alias with the path.
	 *
	 * Any trailing '/' and '\' characters in the given path will be trimmed.
	 *
	 * @param string $alias the alias name (e.g. "@yii"). It must start with a '@' character.
	 * It may contain the forward slash '/' which serves as boundary character when performing
	 * alias translation by [[getAlias()]].
	 * @param string $path the path corresponding to the alias. Trailing '/' and '\' characters
	 * will be trimmed. This can be
m  
Qiang Xue committed
269 270 271 272
	 *
	 * - a directory or a file path (e.g. `/tmp`, `/tmp/main.txt`)
	 * - a URL (e.g. `http://www.yiiframework.com`)
	 * - a path alias (e.g. `@yii/base`). In this case, the path alias will be converted into the
Qiang Xue committed
273
	 *   actual path first by calling [[getAlias()]].
Qiang Xue committed
274
	 *
Qiang Xue committed
275
	 * @throws InvalidParamException if $path is an invalid alias.
w  
Qiang Xue committed
276
	 * @see getAlias
Qiang Xue committed
277
	 */
w  
Qiang Xue committed
278
	public static function setAlias($alias, $path)
Qiang Xue committed
279
	{
280
		if (strncmp($alias, '@', 1)) {
Qiang Xue committed
281
			$alias = '@' . $alias;
282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307
		}
		$pos = strpos($alias, '/');
		$root = $pos === false ? $alias : substr($alias, 0, $pos);
		if ($path !== null) {
			$path = strncmp($path, '@', 1) ? rtrim($path, '\\/') : static::getAlias($path);
			if (!isset(self::$aliases[$root])) {
				self::$aliases[$root] = $path;
			} elseif (is_string(self::$aliases[$root])) {
				if ($pos === false) {
					self::$aliases[$root] = $path;
				} else {
					self::$aliases[$root] = array(
						$alias => $path,
						$root => self::$aliases[$root],
					);
				}
			} else {
				self::$aliases[$root][$alias] = $path;
				krsort(self::$aliases[$root]);
			}
		} elseif (isset(self::$aliases[$root])) {
			if (is_array(self::$aliases[$root])) {
				unset(self::$aliases[$root][$alias]);
			} elseif ($pos === false) {
				unset(self::$aliases[$root]);
			}
m  
Qiang Xue committed
308
		}
Qiang Xue committed
309 310 311 312
	}

	/**
	 * Class autoload loader.
Qiang Xue committed
313 314
	 * This method is invoked automatically when PHP sees an unknown class.
	 * The method will attempt to include the class file according to the following procedure:
w  
Qiang Xue committed
315 316 317 318 319 320 321 322
	 *
	 * 1. Search in [[classMap]];
	 * 2. If the class is namespaced (e.g. `yii\base\Component`), it will attempt
	 *    to include the file associated with the corresponding path alias
	 *    (e.g. `@yii/base/Component.php`);
	 * 3. If the class is named in PEAR style (e.g. `PHPUnit_Framework_TestCase`),
	 *    it will attempt to include the file associated with the corresponding path alias
	 *    (e.g. `@PHPUnit/Framework/TestCase.php`);
Qiang Xue committed
323
	 * 4. Search PHP include_path for the actual class file if [[enableIncludePath]] is true;
w  
Qiang Xue committed
324 325
	 * 5. Return false so that other autoloaders have chance to include the class file.
	 *
Qiang Xue committed
326 327
	 * @param string $className class name
	 * @return boolean whether the class has been loaded successfully
Qiang Xue committed
328 329
	 * @throws InvalidConfigException if the class file does not exist
	 * @throws UnknownClassException if the class does not exist in the class file
Qiang Xue committed
330 331 332
	 */
	public static function autoload($className)
	{
Qiang Xue committed
333
		$className = ltrim($className, '\\');
w  
Qiang Xue committed
334

Qiang Xue committed
335
		if (isset(self::$classMap[$className])) {
Qiang Xue committed
336 337 338 339
			$classFile = static::getAlias(self::$classMap[$className]);
			if (!is_file($classFile)) {
				throw new InvalidConfigException("Class file does not exist: $classFile");
			}
Qiang Xue committed
340
		} else {
Qiang Xue committed
341
			// follow PSR-0 to determine the class file
Qiang Xue committed
342 343
			if (($pos = strrpos($className, '\\')) !== false) {
				// namespaced class, e.g. yii\base\Component
Qiang Xue committed
344
				$path = str_replace('\\', '/', substr($className, 0, $pos + 1))
Qiang Xue committed
345 346
					. str_replace('_', '/', substr($className, $pos + 1)) . '.php';
			} else {
Qiang Xue committed
347
				$path = str_replace('_', '/', $className) . '.php';
w  
Qiang Xue committed
348
			}
Qiang Xue committed
349 350 351 352 353 354 355

			// try via path alias first
			if (strpos($path, '/') !== false) {
				$fullPath = static::getAlias('@' . $path, false);
				if ($fullPath !== false && is_file($fullPath)) {
					$classFile = $fullPath;
				}
Qiang Xue committed
356 357
			}

Qiang Xue committed
358
			// search include_path
359 360
			if (!isset($classFile) && self::$enableIncludePath && ($fullPath = stream_resolve_include_path($path)) !== false) {
				$classFile = $fullPath;
Qiang Xue committed
361 362 363 364 365
			}

			if (!isset($classFile)) {
				// return false to let other autoloaders to try loading the class
				return false;
w  
Qiang Xue committed
366
			}
Qiang Xue committed
367 368 369 370 371 372
		}

		include($classFile);

		if (class_exists($className, false) || interface_exists($className, false)) {
			return true;
Qiang Xue committed
373
		} else {
Qiang Xue committed
374
			throw new UnknownClassException("Unable to find '$className' in file: $classFile");
w  
Qiang Xue committed
375
		}
Qiang Xue committed
376 377
	}

w  
Qiang Xue committed
378
	/**
Qiang Xue committed
379
	 * Creates a new object using the given configuration.
w  
Qiang Xue committed
380
	 *
Qiang Xue committed
381
	 * The configuration can be either a string or an array.
Qiang Xue committed
382 383
	 * If a string, it is treated as the *object class*; if an array,
	 * it must contain a `class` element specifying the *object class*, and
w  
Qiang Xue committed
384 385 386
	 * the rest of the name-value pairs in the array will be used to initialize
	 * the corresponding object properties.
	 *
Qiang Xue committed
387
	 * The object type can be either a class name or the [[getAlias()|alias]] of
w  
Qiang Xue committed
388
	 * the class. For example,
w  
Qiang Xue committed
389
	 *
Qiang Xue committed
390 391
	 * - `app\components\GoogleMap`: fully-qualified namespaced class.
	 * - `@app/components/GoogleMap`: an alias, used for non-namespaced class.
Qiang Xue committed
392 393 394
	 *
	 * Below are some usage examples:
	 *
w  
Qiang Xue committed
395
	 * ~~~
Qiang Xue committed
396
	 * $object = \Yii::createObject('@app/components/GoogleMap');
Qiang Xue committed
397 398
	 * $object = \Yii::createObject(array(
	 *     'class' => '\app\components\GoogleMap',
w  
Qiang Xue committed
399 400 401 402
	 *     'apiKey' => 'xyz',
	 * ));
	 * ~~~
	 *
Qiang Xue committed
403 404 405 406 407 408 409 410 411 412
	 * This method can be used to create any object as long as the object's constructor is
	 * defined like the following:
	 *
	 * ~~~
	 * public function __construct(..., $config = array()) {
	 * }
	 * ~~~
	 *
	 * The method will pass the given configuration as the last parameter of the constructor,
	 * and any additional parameters to this method will be passed as the rest of the constructor parameters.
w  
Qiang Xue committed
413
	 *
Qiang Xue committed
414 415
	 * @param string|array $config the configuration. It can be either a string representing the class name
	 * or an array representing the object configuration.
w  
Qiang Xue committed
416
	 * @return mixed the created object
Qiang Xue committed
417
	 * @throws InvalidConfigException if the configuration is invalid.
w  
Qiang Xue committed
418
	 */
Qiang Xue committed
419
	public static function createObject($config)
w  
Qiang Xue committed
420
	{
Qiang Xue committed
421 422
		static $reflections = array();

w  
Qiang Xue committed
423
		if (is_string($config)) {
w  
Qiang Xue committed
424
			$class = $config;
w  
Qiang Xue committed
425
			$config = array();
Qiang Xue committed
426
		} elseif (isset($config['class'])) {
w  
Qiang Xue committed
427
			$class = $config['class'];
w  
Qiang Xue committed
428
			unset($config['class']);
Qiang Xue committed
429
		} else {
Qiang Xue committed
430
			throw new InvalidConfigException('Object configuration must be an array containing a "class" element.');
w  
Qiang Xue committed
431 432
		}

w  
Qiang Xue committed
433
		if (!class_exists($class, false)) {
Qiang Xue committed
434
			$class = static::import($class);
w  
Qiang Xue committed
435 436
		}

Qiang Xue committed
437 438 439 440
		$class = ltrim($class, '\\');

		if (isset(self::$objectConfig[$class])) {
			$config = array_merge(self::$objectConfig[$class], $config);
441 442
		}

Qiang Xue committed
443
		if (($n = func_num_args()) > 1) {
Qiang Xue committed
444 445 446
			/** @var $reflection \ReflectionClass */
			if (isset($reflections[$class])) {
				$reflection = $reflections[$class];
Qiang Xue committed
447
			} else {
Qiang Xue committed
448 449 450 451 452 453
				$reflection = $reflections[$class] = new \ReflectionClass($class);
			}
			$args = func_get_args();
			array_shift($args); // remove $config
			if ($config !== array()) {
				$args[] = $config;
Qiang Xue committed
454
			}
Qiang Xue committed
455
			return $reflection->newInstanceArgs($args);
Qiang Xue committed
456
		} else {
Qiang Xue committed
457
			return $config === array() ? new $class : new $class($config);
Qiang Xue committed
458
		}
w  
Qiang Xue committed
459 460
	}

Qiang Xue committed
461
	/**
w  
Qiang Xue committed
462 463 464 465 466
	 * Logs a trace message.
	 * Trace messages are logged mainly for development purpose to see
	 * the execution work flow of some code.
	 * @param string $message the message to be logged.
	 * @param string $category the category of the message.
Qiang Xue committed
467
	 */
w  
Qiang Xue committed
468
	public static function trace($message, $category = 'application')
Qiang Xue committed
469
	{
w  
Qiang Xue committed
470
		if (YII_DEBUG) {
Qiang Xue committed
471
			self::getLogger()->log($message, Logger::LEVEL_TRACE, $category);
w  
Qiang Xue committed
472
		}
Qiang Xue committed
473 474 475
	}

	/**
w  
Qiang Xue committed
476 477 478 479 480
	 * Logs an error message.
	 * An error message is typically logged when an unrecoverable error occurs
	 * during the execution of an application.
	 * @param string $message the message to be logged.
	 * @param string $category the category of the message.
Qiang Xue committed
481
	 */
Qiang Xue committed
482
	public static function error($message, $category = 'application')
Qiang Xue committed
483
	{
Qiang Xue committed
484
		self::getLogger()->log($message, Logger::LEVEL_ERROR, $category);
w  
Qiang Xue committed
485 486 487 488 489 490 491 492 493
	}

	/**
	 * Logs a warning message.
	 * A warning message is typically logged when an error occurs while the execution
	 * can still continue.
	 * @param string $message the message to be logged.
	 * @param string $category the category of the message.
	 */
Qiang Xue committed
494
	public static function warning($message, $category = 'application')
w  
Qiang Xue committed
495
	{
Qiang Xue committed
496
		self::getLogger()->log($message, Logger::LEVEL_WARNING, $category);
Qiang Xue committed
497 498 499
	}

	/**
w  
Qiang Xue committed
500 501 502 503 504 505
	 * Logs an informative message.
	 * An informative message is typically logged by an application to keep record of
	 * something important (e.g. an administrator logs in).
	 * @param string $message the message to be logged.
	 * @param string $category the category of the message.
	 */
Qiang Xue committed
506
	public static function info($message, $category = 'application')
w  
Qiang Xue committed
507
	{
Qiang Xue committed
508
		self::getLogger()->log($message, Logger::LEVEL_INFO, $category);
w  
Qiang Xue committed
509 510 511 512 513 514 515 516 517
	}

	/**
	 * Marks the beginning of a code block for profiling.
	 * This has to be matched with a call to [[endProfile]] with the same category name.
	 * The begin- and end- calls must also be properly nested. For example,
	 *
	 * ~~~
	 * \Yii::beginProfile('block1');
Qiang Xue committed
518 519 520 521
	 * // some code to be profiled
	 *     \Yii::beginProfile('block2');
	 *     // some other code to be profiled
	 *     \Yii::endProfile('block2');
w  
Qiang Xue committed
522 523
	 * \Yii::endProfile('block1');
	 * ~~~
Qiang Xue committed
524 525
	 * @param string $token token for the code block
	 * @param string $category the category of this log message
Qiang Xue committed
526 527
	 * @see endProfile
	 */
Qiang Xue committed
528
	public static function beginProfile($token, $category = 'application')
Qiang Xue committed
529
	{
Qiang Xue committed
530
		self::getLogger()->log($token, Logger::LEVEL_PROFILE_BEGIN, $category);
Qiang Xue committed
531 532 533 534
	}

	/**
	 * Marks the end of a code block for profiling.
w  
Qiang Xue committed
535
	 * This has to be matched with a previous call to [[beginProfile]] with the same category name.
Qiang Xue committed
536 537
	 * @param string $token token for the code block
	 * @param string $category the category of this log message
Qiang Xue committed
538 539
	 * @see beginProfile
	 */
Qiang Xue committed
540
	public static function endProfile($token, $category = 'application')
Qiang Xue committed
541
	{
Qiang Xue committed
542
		self::getLogger()->log($token, Logger::LEVEL_PROFILE_END, $category);
Qiang Xue committed
543 544 545
	}

	/**
w  
Qiang Xue committed
546 547
	 * Returns the message logger object.
	 * @return \yii\logging\Logger message logger
Qiang Xue committed
548 549 550
	 */
	public static function getLogger()
	{
w  
Qiang Xue committed
551
		if (self::$_logger !== null) {
Qiang Xue committed
552
			return self::$_logger;
Qiang Xue committed
553
		} else {
Qiang Xue committed
554
			return self::$_logger = new Logger;
w  
Qiang Xue committed
555
		}
w  
Qiang Xue committed
556 557 558 559
	}

	/**
	 * Sets the logger object.
Qiang Xue committed
560
	 * @param Logger $logger the logger object.
w  
Qiang Xue committed
561 562 563 564
	 */
	public static function setLogger($logger)
	{
		self::$_logger = $logger;
Qiang Xue committed
565 566 567
	}

	/**
w  
Qiang Xue committed
568 569
	 * Returns an HTML hyperlink that can be displayed on your Web page showing Powered by Yii" information.
	 * @return string an HTML hyperlink that can be displayed on your Web page showing Powered by Yii" information
Qiang Xue committed
570 571 572 573 574 575 576 577
	 */
	public static function powered()
	{
		return 'Powered by <a href="http://www.yiiframework.com/" rel="external">Yii Framework</a>.';
	}

	/**
	 * Translates a message to the specified language.
Qiang Xue committed
578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599
	 *
	 * The translation will be conducted according to the message category and the target language.
	 * To specify the category of the message, prefix the message with the category name and separate it
	 * with "|". For example, "app|hello world". If the category is not specified, the default category "app"
	 * will be used. The actual message translation is done by a [[\yii\i18n\MessageSource|message source]].
	 *
	 * In case when a translated message has different plural forms (separated by "|"), this method
	 * will also attempt to choose an appropriate one according to a given numeric value which is
	 * specified as the first parameter (indexed by 0) in `$params`.
	 *
	 * For example, if a translated message is "I have an apple.|I have {n} apples.", and the first
	 * parameter is 2, the message returned will be "I have 2 apples.". Note that the placeholder "{n}"
	 * will be replaced with the given number.
	 *
	 * For more details on how plural rules are applied, please refer to:
	 * [[http://www.unicode.org/cldr/charts/supplemental/language_plural_rules.html]]
	 *
	 * @param string $message the message to be translated.
	 * @param array $params the parameters that will be used to replace the corresponding placeholders in the message.
	 * @param string $language the language code (e.g. `en_US`, `en`). If this is null, the current
	 * [[\yii\base\Application::language|application language]] will be used.
	 * @return string the translated message.
Qiang Xue committed
600
	 */
Qiang Xue committed
601
	public static function t($message, $params = array(), $language = null)
Qiang Xue committed
602
	{
603
		return self::$app->getI18N()->translate($message, $params, $language);
Qiang Xue committed
604 605
	}
}