start-installation.md 10.4 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.
Carsten Brandt committed
5
The former is the preferred way, as it allows you to install new [extensions](structure-extensions.md) or update Yii by simply running a single command.
Larry Ullman committed
6

Qiang Xue committed
7 8
Standard installations of Yii result in both the framework and an application template being downloaded and installed.
An application template is a working Yii application implementing some basic features, such as login, contact form, etc. 
9
Its code is organized in a recommended way. Therefore, it can serve as a good starting point for your projects.
Qiang Xue committed
10
    
Qiang Xue committed
11 12 13 14
In this and the next few sections, we will describe how to install Yii with the so-called *Basic Application Template* and
how to implement new features on top of this template. Yii also provides another template called
the [Advanced Application Template](tutorial-advanced-app.md) which is better used in a team development environment
to develop applications with multiple tiers.
Qiang Xue committed
15 16 17 18

> Info: The Basic Application Template is suitable for developing 90 percent of Web applications. It differs
  from the Advanced Application Template mainly in how their code is organized. If you are new to Yii, we strongly
  recommend you stick to the Basic Application Template for its simplicity yet sufficient functionalities.
19 20


21
Installing via Composer <span id="installing-via-composer"></span>
22 23
-----------------------

Larry Ullman committed
24 25
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:
26

27 28 29
    curl -s http://getcomposer.org/installer | php
    mv composer.phar /usr/local/bin/composer

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

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

35 36 37
If you had Composer already installed before, make sure you use an up to date version. You can update Composer
by running `composer self-update`.

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

40
    composer global require "fxp/composer-asset-plugin:1.0.0"
41
    composer create-project --prefer-dist yiisoft/yii2-app-basic basic
42

Qiang Xue committed
43
The first command installs the [composer asset plugin](https://github.com/francoispluchino/composer-asset-plugin/)
Carsten Brandt committed
44
which allows managing bower and npm package dependencies through Composer. You only need to run this command
45
once for all. The second command installs Yii in a directory named `basic`. You can choose a different directory name if you want.
Qiang Xue committed
46

Qiang Xue committed
47 48 49
> Note: During the installation Composer may ask for your Github login credentials. This is normal because Composer 
> needs to get enough API rate-limit to retrieve the dependent package information from Github. For more details, 
> please refer to the [Composer documentation](https://getcomposer.org/doc/articles/troubleshooting.md#api-rate-limit-and-oauth-tokens).
50

Carsten Brandt committed
51
> Tip: If you want to install the latest development version of Yii, you may use the following command instead,
52 53 54 55 56
> 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.
57

Alexander Makarov committed
58

59
Installing from an Archive File <span id="installing-from-archive-file"></span>
60
-------------------------------
61

Carsten Brandt committed
62
Installing Yii from an archive file involves three steps:
63

64
1. Download the archive file from [yiiframework.com](http://www.yiiframework.com/download/).
Larry Ullman committed
65
2. Unpack the downloaded file to a Web-accessible folder.
66 67 68 69 70 71 72
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',
   ```
73 74


75
Other Installation Options <span id="other-installation-options"></span>
76
--------------------------
Alexander Makarov committed
77

78
The above installation instructions show how to install Yii, which also creates a basic Web application that works out of the box.
Qiang Xue committed
79 80
This approach is a good starting point for most projects, either small or big. It is especially suitable if you just
start learning Yii.
81

Larry Ullman committed
82
But there are other installation options available:
83

Larry Ullman committed
84
* If you only want to install the core framework and would like to build an entire  application from scratch,
85
  you may follow the instructions as explained in [Building Application from Scratch](tutorial-start-from-scratch.md).
Larry Ullman committed
86 87
* 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).
88 89


90
Verifying the Installation <span id="verifying-installation"></span>
91
--------------------------
92

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

95
```
96
http://localhost/basic/web/index.php
97
```
98

99
This URL assumes you have installed Yii in a directory named `basic`, directly under the Web server's document root directory,
Qiang Xue committed
100
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
101

102 103 104
![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
105
Yii's requirements. You can check if the minimum requirements are met using one of the following approaches:
106

107
* Use a browser to access the URL `http://localhost/basic/requirements.php`
108
* Run the following commands:
109

110 111 112 113
  ```
  cd basic
  php requirements.php
  ```
114

Larry Ullman committed
115
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
116 117
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.
118 119


120
Configuring Web Servers <span id="configuring-web-servers"></span>
121
-----------------------
122

Larry Ullman committed
123
> Info: You may skip this subsection for now if you are just test driving Yii with no intention
Qiang Xue committed
124 125 126 127
  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
128 129 130
Windows, Mac OS X, or Linux running PHP 5.4 or higher. Yii 2.0 is also compatible with facebook's
[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
131 132

On a production server, you may want to configure your Web server so that the application can be accessed
133
via the URL `http://www.example.com/index.php` instead of `http://www.example.com/basic/web/index.php`. Such configuration
Larry Ullman committed
134
requires pointing the document root of your Web server to the `basic/web` folder. You may also
135
want to hide `index.php` from the URL, as described in the [Routing and URL Creation](runtime-routing.md) section.
Larry Ullman committed
136
In this subsection, you'll learn how to configure your Apache or Nginx server to achieve these goals.
Qiang Xue committed
137 138 139

> 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
140
of `basic/web`. Denying access to those other folders is a security improvement.
Qiang Xue committed
141

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


147
### Recommended Apache Configuration <span id="recommended-apache-configuration"></span>
Qiang Xue committed
148 149

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

```
Qiang Xue committed
153 154 155 156
# Set document root to be "basic/web"
DocumentRoot "path/to/basic/web"

<Directory "path/to/basic/web">
Carsten Brandt committed
157
    # use mod_rewrite for pretty URL support
Qiang Xue committed
158 159 160 161 162 163 164 165 166
    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>
167 168
```

Qiang Xue committed
169

170
### Recommended Nginx Configuration <span id="recommended-nginx-configuration"></span>
Qiang Xue committed
171

Qiang Xue committed
172 173 174
To use [Nginx](http://wiki.nginx.org/), you should install PHP as an [FPM SAPI](http://php.net/install.fpm).
You may 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
175 176 177 178 179 180 181 182 183 184 185 186 187

```
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;

188 189
    access_log  /path/to/basic/log/access.log main;
    error_log   /path/to/basic/log/error.log;
Qiang Xue committed
190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205

    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;
206
        try_files $uri =404;
Qiang Xue committed
207 208 209 210 211 212 213 214
    }

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

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

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