start-installation.md 8.79 KB
Newer Older
1 2 3
Installing Yii
==============

Larry Ullman committed
4
You can install Yii in two ways, using [Composer](http://getcomposer.org/) or by downloading an archive file.
Kevin LEVRON committed
5
The former is the preferred way, as it allows you to install new [extensions](extend-creating-extensions.md) or update Yii by simply running a single command.
Larry Ullman committed
6 7

> Note: Unlike with Yii 1, standard installations of Yii 2 results in both the framework and an application skeleton being downloaded and installed.
8 9


Qiang Xue committed
10
Installing via Composer <a name="installing-via-composer"></a>
11 12
-----------------------

Larry Ullman committed
13 14
If you do not already have Composer installed, you may do so by following the instructions at
[getcomposer.org](https://getcomposer.org/download/). On Linux and Mac OS X, you'll run the following commands:
15

16 17 18
    curl -s http://getcomposer.org/installer | php
    mv composer.phar /usr/local/bin/composer

Larry Ullman committed
19
On Windows, you'll download and run [Composer-Setup.exe](https://getcomposer.org/Composer-Setup.exe).
20

21
Please refer to the [Composer Documentation](https://getcomposer.org/doc/) if you encounter any
Larry Ullman committed
22
problems or want to learn more about Composer usage.
23

Qiang Xue committed
24
With Composer installed, you can install Yii by running the following commands under a Web-accessible folder:
25

Qiang Xue committed
26
    composer global require "fxp/composer-asset-plugin:1.0.*@dev"
27
    composer create-project --prefer-dist yiisoft/yii2-app-basic basic
28

Qiang Xue committed
29 30 31
The first command installs the [composer asset plugin](https://github.com/francoispluchino/composer-asset-plugin/)
which allows managing bower and npm package dependencies through composer. You only need to run this command
once for all. The second command installs Yii in a directory named `basic`.
Qiang Xue committed
32

Larry Ullman committed
33
> Tip: If you want to install the latest development version of Yii, you may use the following command,
34 35 36 37 38
> which adds a [stability option](https://getcomposer.org/doc/04-schema.md#minimum-stability):
>
>     composer create-project --prefer-dist --stability=dev yiisoft/yii2-app-basic basic
>
> Note that the development version of Yii should not be used for production as it may break your running code.
39

Alexander Makarov committed
40

Qiang Xue committed
41
Installing from an Archive File <a name="installing-from-archive-file"></a>
42
-------------------------------
43

44
Installing Yii from an archive file involves two steps:
45

Larry Ullman committed
46 47
1. Download the archive file from [yiiframework.com](http://www.yiiframework.com/download/yii2-basic).
2. Unpack the downloaded file to a Web-accessible folder.
48 49 50 51 52 53 54
3. Modify the `config/web.php` file by entering a secret key for the `cookieValidationKey` configuration item
   (this is done automatically if you are installing Yii using Composer):

   ```php
   // !!! insert a secret key in the following (if it is empty) - this is required by cookie validation
   'cookieValidationKey' => 'enter your secret key here',
   ```
55 56


Qiang Xue committed
57
Other Installation Options <a name="other-installation-options"></a>
58
--------------------------
Alexander Makarov committed
59

60
The above installation instructions show how to install Yii, which also creates a basic Web application that works out of the box.
Larry Ullman committed
61
This approach is a good starting point for small projects, or for when you just start learning Yii.
62

Larry Ullman committed
63
But there are other installation options available:
64

Larry Ullman committed
65
* If you only want to install the core framework and would like to build an entire  application from scratch,
66
  you may follow the instructions as explained in [Building Application from Scratch](tutorial-start-from-scratch.md).
Larry Ullman committed
67 68
* If you want to start with a more sophisticated application, better suited to team development environments,
  you may consider installing the [Advanced Application Template](tutorial-advanced-app.md).
69 70


Larry Ullman committed
71
Verifying the Installation <a name="verifying-installation"></a>
72
--------------------------
73

Larry Ullman committed
74
After installation, you can use your browser to access the installed Yii application with the following URL:
75

76
```
77
http://localhost/basic/web/index.php
78
```
79

80
This URL assumes you have installed Yii in a directory named `basic`, directly under the Web server's document root directory,
Qiang Xue committed
81
and that the Web server is running on your local machine (`localhost`). You may need to adjust it to your installation environment.
Larry Ullman committed
82

83 84 85
![Successful Installation of Yii](images/start-app-installed.png)

You should see the above "Congratulations!" page in your browser. If not, please check if your PHP installation satisfies
Larry Ullman committed
86
Yii's requirements. You can check if the minimum requirements are met using one of the following approaches:
87

88
* Use a browser to access the URL `http://localhost/basic/requirements.php`
89
* Run the following commands:
90

91 92 93 94
  ```
  cd basic
  php requirements.php
  ```
95

Larry Ullman committed
96
You should configure your PHP installation so that it meets the minimum requirements of Yii. Most importantly, you should have PHP 5.4 or above. You should also install
97 98
the [PDO PHP Extension](http://www.php.net/manual/en/pdo.installation.php) and a corresponding database driver
(such as `pdo_mysql` for MySQL databases), if your application needs a database.
99 100


Qiang Xue committed
101
Configuring Web Servers <a name="configuring-web-servers"></a>
102
-----------------------
103

Larry Ullman committed
104
> Info: You may skip this subsection for now if you are just test driving Yii with no intention
Qiang Xue committed
105 106 107 108
  of deploying it to a production server.

The application installed according to the above instructions should work out of box with either
an [Apache HTTP server](http://httpd.apache.org/) or an [Nginx HTTP server](http://nginx.org/), on
109 110 111
Windows, Mac OS X, or Linux running PHP 5.4 or higher. Yii 2.0 is also compatible the facebooks
[HHVM](http://hhvm.com/) however there are some edge cases where HHVM behaves different than native
PHP so you have to take some extra care when using HHVM.
Qiang Xue committed
112 113

On a production server, you may want to configure your Web server so that the application can be accessed
114
via the URL `http://www.example.com/index.php` instead of `http://www.example.com/basic/web/index.php`. Such configuration
Larry Ullman committed
115
requires pointing the document root of your Web server to the `basic/web` folder. You may also
Qiang Xue committed
116
want to hide `index.php` from the URL, as described in the [URL Parsing and Generation](runtime-url-handling.md) section.
Larry Ullman committed
117
In this subsection, you'll learn how to configure your Apache or Nginx server to achieve these goals.
Qiang Xue committed
118 119 120

> Info: By setting `basic/web` as the document root, you also prevent end users from accessing
your private application code and sensitive data files that are stored in the sibling directories
121
of `basic/web`. Denying access to those other folders is a security improvement.
Qiang Xue committed
122

123
> Info: If your application will run in a shared hosting environment where you do not have permission
Larry Ullman committed
124
to modify its Web server configuration, you may still adjust the structure of your application for better security. Please refer to
Qiang Xue committed
125 126 127
the [Shared Hosting Environment](tutorial-shared-hosting.md) section for more details.


Qiang Xue committed
128
### Recommended Apache Configuration <a name="recommended-apache-configuration"></a>
Qiang Xue committed
129 130

Use the following configuration in Apache's `httpd.conf` file or within a virtual host configuration. Note that you
Larry Ullman committed
131
should replace `path/to/basic/web` with the actual path for `basic/web`.
132 133

```
Qiang Xue committed
134 135 136 137 138 139 140 141 142 143 144 145 146 147
# Set document root to be "basic/web"
DocumentRoot "path/to/basic/web"

<Directory "path/to/basic/web">
    RewriteEngine on

    # If a directory or a file exists, use the request directly
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_FILENAME} !-d
    # Otherwise forward the request to index.php
    RewriteRule . index.php

    # ...other settings...
</Directory>
148 149
```

Qiang Xue committed
150

Qiang Xue committed
151
### Recommended Nginx Configuration <a name="recommended-nginx-configuration"></a>
Qiang Xue committed
152

153
You should have installed PHP as an [FPM SAPI](http://php.net/install.fpm) to use [Nginx](http://wiki.nginx.org/).
154 155
Use the following Nginx configuration, replacing `path/to/basic/web` with the actual path for `basic/web` and `mysite.local` with
the actual hostname to serve.
Qiang Xue committed
156 157 158 159 160 161 162 163 164 165 166 167 168

```
server {
    charset utf-8;
    client_max_body_size 128M;

    listen 80; ## listen for ipv4
    #listen [::]:80 default_server ipv6only=on; ## listen for ipv6

    server_name mysite.local;
    root        /path/to/basic/web;
    index       index.php;

169 170
    access_log  /path/to/basic/log/access.log main;
    error_log   /path/to/basic/log/error.log;
Qiang Xue committed
171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186

    location / {
        # Redirect everything that isn't a real file to index.php
        try_files $uri $uri/ /index.php?$args;
    }

    # uncomment to avoid processing of calls to non-existing static files by Yii
    #location ~ \.(js|css|png|jpg|gif|swf|ico|pdf|mov|fla|zip|rar)$ {
    #    try_files $uri =404;
    #}
    #error_page 404 /404.html;

    location ~ \.php$ {
        include fastcgi.conf;
        fastcgi_pass   127.0.0.1:9000;
        #fastcgi_pass unix:/var/run/php5-fpm.sock;
187
        try_files $uri =404;
Qiang Xue committed
188 189 190 191 192 193 194 195
    }

    location ~ /\.(ht|svn|git) {
        deny all;
    }
}
```

Larry Ullman committed
196
When using this configuration, you should also set `cgi.fix_pathinfo=0` in the `php.ini` file
Qiang Xue committed
197 198
in order to avoid many unnecessary system `stat()` calls.

Larry Ullman committed
199
Also note that when running an HTTPS server, you need to add `fastcgi_param HTTPS on;` so that Yii
Qiang Xue committed
200
can properly detect if a connection is secure.