structure-entry-scripts.md 4.1 KB
Newer Older
1 2 3
Entry Scripts
=============

Qiang Xue committed
4 5
Entry scripts are the first chain in the application bootstrapping process. An application (either
Web application or console application) has a single entry script. End users make requests to
Qiang Xue committed
6
entry scripts which instantiate application instances and forward the requests to them.
Qiang Xue committed
7 8

Entry scripts for Web applications must be stored under Web accessible directories so that they
Qiang Xue committed
9 10
can be accessed by end users. They are often named as `index.php`, but can also use any other names,
provided Web servers can locate them.
Qiang Xue committed
11 12

Entry scripts for console applications are usually stored under the [base path](structure-applications.md)
Qiang Xue committed
13 14
of applications and are named as `yii` (with the `.php` suffix). They should be made executable
so that users can run console applications through the command `./yii <route> [arguments] [options]`.
Qiang Xue committed
15 16 17 18 19 20 21 22 23 24

Entry scripts mainly do the following work:

* Define global constants;
* Register [Composer autoloader](http://getcomposer.org/doc/01-basic-usage.md#autoloading);
* Include the [[Yii]] class file;
* Load application configuration;
* Create and configure an [application](structure-applications.md) instance;
* Call [[yii\base\Application::run()]] to process the incoming request.

Qiang Xue committed
25 26 27

## Web Applications <a name="web-applications"></a>

Qiang Xue committed
28 29 30
The following is the code in the entry script for the [Basic Web Application Template](start-installation.md).

```php
Qiang Xue committed
31 32
<?php

Qiang Xue committed
33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48
defined('YII_DEBUG') or define('YII_DEBUG', true);
defined('YII_ENV') or define('YII_ENV', 'dev');

// register Composer autoloader
require(__DIR__ . '/../vendor/autoload.php');

// include Yii class file
require(__DIR__ . '/../vendor/yiisoft/yii2/Yii.php');

// load application configuration
$config = require(__DIR__ . '/../config/web.php');

// create, configure and run application
(new yii\web\Application($config))->run();
```

49

Qiang Xue committed
50 51 52 53 54 55 56 57 58 59 60 61 62 63
## Console Applications <a name="console-applications"></a>

Similarly, the following is the code for the entry script of a console application:

```php
#!/usr/bin/env php
<?php
/**
 * Yii console bootstrap file.
 *
 * @link http://www.yiiframework.com/
 * @copyright Copyright (c) 2008 Yii Software LLC
 * @license http://www.yiiframework.com/license/
 */
64

Qiang Xue committed
65
defined('YII_DEBUG') or define('YII_DEBUG', true);
66

Qiang Xue committed
67 68 69
// fcgi doesn't have STDIN and STDOUT defined by default
defined('STDIN') or define('STDIN', fopen('php://stdin', 'r'));
defined('STDOUT') or define('STDOUT', fopen('php://stdout', 'w'));
70

Qiang Xue committed
71 72
// register Composer autoloader
require(__DIR__ . '/vendor/autoload.php');
73

74
// include Yii class file
Qiang Xue committed
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99
require(__DIR__ . '/vendor/yiisoft/yii2/Yii.php');

// load application configuration
$config = require(__DIR__ . '/config/console.php');

$application = new yii\console\Application($config);
$exitCode = $application->run();
exit($exitCode);
```


## Defining Constants <a name="defining-constants"></a>

Entry scripts are the best place for defining global constants. Yii supports the following three constants:

* `YII_DEBUG`: specifies whether the application is running in debug mode. When in debug mode, an application
  will keep more log information, and will reveal detailed error call stacks if exceptions are thrown. For this
  reason, debug mode should be used mainly during development. The default value of `YII_DEBUG` is false.
* `YII_ENV`: specifies which environment the application is running in. This has been described in
  more detail in the [Configurations](concept-configurations.md#environment-constants) section.
  The default value of `YII_ENV` is `'prod'`, meaning the application is running in production environment.
* `YII_ENABLE_ERROR_HANDLER`: specifies whether to enable the error handler provided by Yii. The default
  value of this constant is true.

When defining a constant, we often use the code like the following:
100 101

```php
Qiang Xue committed
102
defined('YII_DEBUG') or define('YII_DEBUG', true);
103 104
```

Qiang Xue committed
105
which is equivalent to the following code:
106 107

```php
Qiang Xue committed
108 109 110
if (!defined('YII_DEBUG')) {
    define('YII_DEBUG', true);
}
111
```
Qiang Xue committed
112

Qiang Xue committed
113
Clearly the former is more succinct and easier to understand.
Qiang Xue committed
114

Qiang Xue committed
115 116
Constant definitions should be done at the very beginning of an entry script so that they can take effect
when other PHP files are being included.