installation.md 6.75 KB
Newer Older
Qiang Xue committed
1 2 3
Installation
============

4 5
There are two ways you can install the Yii framework:

6 7
* Via [Composer](http://getcomposer.org/) (recommended)
* Download an application template containing all site requirements, including the Yii framework itself
8

9

10 11 12
Installing via Composer
-----------------------

13 14
The recommended way to install Yii is to use the [Composer](http://getcomposer.org/) package manager. If you do not already
have Composer installed, you may download it from [http://getcomposer.org/](http://getcomposer.org/) or run the following command:
15 16 17 18 19

```
curl -s http://getcomposer.org/installer | php
```

20 21
We strongly recommend a global composer installation.

22 23
For problems or more information, see the official Composer guide:

24
* [Linux](http://getcomposer.org/doc/00-intro.md#installation-nix)
25
* [Windows](http://getcomposer.org/doc/00-intro.md#installation-windows)
26

27 28
With Composer installed, you can create a new Yii site using one of Yii's ready-to-use application templates.
Based on your needs, choosing the right template can help bootstrap your project.
29

30
Currently, there are two application templates available:
31

32 33 34 35 36 37 38 39 40 41
- The [Basic Application Template](https://github.com/yiisoft/yii2-app-basic) - just a basic frontend application template.
- The [Advanced Application Template](https://github.com/yiisoft/yii2-app-advanced) - consisting of a  frontend, a backend,
  console resources, common (shared code), and support for environments.

For installation instructions for these templates, see the above linked pages.
To read more about the ideas behind these application templates and proposed usage,
refer to the [basic application template](apps-basic.md) and [advanced application template](apps-advanced.md) documents.

If you do not want to use a template and want to start from scratch you'll find information in the document about
[creating your own application structure](apps-own.md). This is only recommended for advanced users.
42

43 44 45 46

Installing from zip
-------------------

47
Installation from a zip file involves two steps:
Qiang Xue committed
48

49
   1. Downloading an application template from [yiiframework.com](http://www.yiiframework.com/download/).
50
   2. Unpacking the downloaded file.
Qiang Xue committed
51

52 53 54 55
If you only want the Yii Framework files you can download a ZIP file directly from [github](https://github.com/yiisoft/yii2-framework/releases).
To create your application you might want to follow the steps described in [creating your own application structure](apps-own.md).
This is only recommended for advanced users.

56
> Tip: The Yii framework itself does not need to be installed under a web-accessible directory.
57 58 59 60
A Yii application has one entry script which is usually the only file that absolutely must be
exposed to web users (i.e., placed within the web directory). Other PHP scripts, including those
part of the Yii Framework, should be protected from web access to prevent possible exploitation by hackers.

Qiang Xue committed
61 62 63 64 65

Requirements
------------

After installing Yii, you may want to verify that your server satisfies
66
Yii's requirements. You can do so by running the requirement checker
67 68 69 70
script in a web browser or from the command line.

If you have installed a Yii application template via zip or composer you'll find a `requirements.php` file in the
base directory of your application.
Qiang Xue committed
71

72 73 74 75 76 77 78 79
In order to run this script on the command line use the following command:

```
php requirements.php
```

In order to run this script in your browser, you should ensure it is accessable by the webserver and
access `http://hostname/path/to/yii-app/requirements.php` in your browser.
Carsten Brandt committed
80
If you are using Linux you can create a soft link to make it accessable, using the following command:
81 82

```
83
ln -s requirements.php ../requirements.php
84 85
```

86
For the advanded app the `requirements.php` is two levels up so you have to use `ln -s requirements.php ../../requirements.php`.
Carsten Brandt committed
87

88 89 90
Yii 2 requires PHP 5.4.0 or higher. Yii has been tested with the [Apache HTTP server](http://httpd.apache.org/) and
[Nginx HTTP server](http://nginx.org/) on Windows and Linux.
Yii may also be usable on other web servers and platforms, provided that PHP 5.4 or higher is supported.
Qiang Xue committed
91 92 93 94 95


Recommended Apache Configuration
--------------------------------

96 97
Yii is ready to work with a default Apache web server configuration. As a security measure, Yii comes with `.htaccess`
files in the Yii framework folder to deny access to those restricted resources.
98

99 100
By default, requests for pages in a Yii-based site go through the bootstrap file, usually named `index.php`, and placed
in the application's `web` directory. The result will be URLs in the format `http://hostname/index.php/controller/action/param/value`.
101

102
To hide the bootstrap file in your URLs, add `mod_rewrite` instructions to the `.htaccess` file in your web document root
103 104
(or add the instructions to the virtual host configuration in Apache's `httpd.conf` file, `Directory` section for your webroot).
The applicable instructions are:
Qiang Xue committed
105 106 107 108

~~~
RewriteEngine on

109
# If a directory or a file exists, use it directly
Qiang Xue committed
110 111
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-d
112
# Otherwise forward it to index.php
Qiang Xue committed
113 114 115
RewriteRule . index.php
~~~

116

Qiang Xue committed
117 118 119
Recommended Nginx Configuration
-------------------------------

120 121 122 123
Yii can also be used with the popular [Nginx](http://wiki.nginx.org/) web server, so long it has PHP installed as
an [FPM SAPI](http://php.net/install.fpm). Below is a sample host configuration for a Yii-based site on Nginx.
The configuration tells the server to send all requests for non-existent resources through the bootstrap file,
resulting in "prettier" URLs without the need for `index.php` references.
Qiang Xue committed
124

125
```
Qiang Xue committed
126
server {
Carsten Brandt committed
127
    set $yii_bootstrap "index.php";
Qiang Xue committed
128
    charset utf-8;
Carsten Brandt committed
129
    client_max_body_size 128M;
Qiang Xue committed
130

Carsten Brandt committed
131 132 133 134 135 136
    listen 80; ## listen for ipv4
    #listen [::]:80 default_server ipv6only=on; ## listen for ipv6

    server_name mysite.local;
    root        /path/to/project/web;
    index       $yii_bootstrap;
Qiang Xue committed
137

138
    access_log  /path/to/project/log/access.log  main;
Carsten Brandt committed
139
    error_log   /path/to/project/log/error.log;
Qiang Xue committed
140

141
    location / {
Carsten Brandt committed
142 143
        # Redirect everything that isn't real file to yii bootstrap file including arguments.
        try_files $uri $uri/ /$yii_bootstrap?$args;
Qiang Xue committed
144 145
    }

Carsten Brandt committed
146 147 148 149 150 151
    # uncomment to avoid processing of calls to unexisting 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;

152 153
    location ~ \.php$ {
        include fastcgi.conf;
Qiang Xue committed
154
        fastcgi_pass   127.0.0.1:9000;
lancecoder committed
155
        #fastcgi_pass unix:/var/run/php5-fpm.sock;
Qiang Xue committed
156 157
    }

158 159
    location ~ /\.(ht|svn|git) {
        deny all;
Qiang Xue committed
160 161
    }
}
162
```
Qiang Xue committed
163

164
When using this configuration, you should set `cgi.fix_pathinfo=0` in the `php.ini` file in order to avoid many unnecessary system `stat()` calls.
165 166


Carsten Brandt committed
167
Note that when running a HTTPS server you need to add `fastcgi_param HTTPS on;` in order for Yii to properly detect if
168
connection is secure.