You can install Yii in two ways, using Composer or by downloading an archive file. The former is the preferred way, as it allows you to install new extensions or update Yii by simply running a single command.
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. Its code is organized in a recommended way. Therefore, it can serve as a good starting point for your projects.
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 which is better used in a team development environment to develop applications with multiple tiers.
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.
If you do not already have Composer installed, you may do so by following the instructions at getcomposer.org. On Linux and Mac OS X, you'll run the following commands:
curl -s http://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer
On Windows, you'll download and run Composer-Setup.exe.
Please refer to the Composer Documentation if you encounter any problems or want to learn more about Composer usage.
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.
With Composer installed, you can install Yii by running the following commands under a Web-accessible folder:
composer global require "fxp/composer-asset-plugin:1.0.0-beta4"
composer create-project --prefer-dist yiisoft/yii2-app-basic basic
The first command installs the 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. You can choose a different directory name if you want.
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.
Tip: If you want to install the latest development version of Yii, you may use the following command instead, which adds a stability option:
composer create-project --prefer-dist --stability=dev yiisoft/yii2-app-basic basicNote that the development version of Yii should not be used for production as it may break your running code.
Installing Yii from an archive file involves three steps:
-
Download the archive file from yiiframework.com.
-
Unpack the downloaded file to a Web-accessible folder.
-
Modify the
config/web.phpfile by entering a secret key for thecookieValidationKeyconfiguration item (this is done automatically if you are installing Yii using Composer):// !!! insert a secret key in the following (if it is empty) - this is required by cookie validation 'cookieValidationKey' => 'enter your secret key here',
The above installation instructions show how to install Yii, which also creates a basic Web application that works out of the box. This approach is a good starting point for most projects, either small or big. It is especially suitable if you just start learning Yii.
But there are other installation options available:
- If you only want to install the core framework and would like to build an entire application from scratch, you may follow the instructions as explained in Building Application from Scratch.
- If you want to start with a more sophisticated application, better suited to team development environments, you may consider installing the Advanced Application Template.
After installation, you can use your browser to access the installed Yii application with the following URL:
http://localhost/basic/web/index.php
This URL assumes you have installed Yii in a directory named basic, directly under the Web server's document root directory,
and that the Web server is running on your local machine (localhost). You may need to adjust it to your installation environment.
You should see the above "Congratulations!" page in your browser. If not, please check if your PHP installation satisfies Yii's requirements. You can check if the minimum requirements are met using one of the following approaches:
-
Use a browser to access the URL
http://localhost/basic/requirements.php -
Run the following commands:
cd basic php requirements.php
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
the PDO PHP Extension and a corresponding database driver
(such as pdo_mysql for MySQL databases), if your application needs a database.
Info: You may skip this subsection for now if you are just test driving Yii with no intention 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 or an Nginx HTTP server, on Windows, Mac OS X, or Linux running PHP 5.4 or higher. Yii 2.0 is also compatible with facebooks HHVM however there are some edge cases where HHVM behaves different than native PHP so you have to take some extra care when using HHVM.
On a production server, you may want to configure your Web server so that the application can be accessed
via the URL http://www.example.com/index.php instead of http://www.example.com/basic/web/index.php. Such configuration
requires pointing the document root of your Web server to the basic/web folder. You may also
want to hide index.php from the URL, as described in the Routing and URL Creation section.
In this subsection, you'll learn how to configure your Apache or Nginx server to achieve these goals.
Info: By setting
basic/webas 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 ofbasic/web. Denying access to those other folders is a security improvement.
Info: If your application will run in a shared hosting environment where you do not have permission to modify its Web server configuration, you may still adjust the structure of your application for better security. Please refer to the Shared Hosting Environment section for more details.
Use the following configuration in Apache's httpd.conf file or within a virtual host configuration. Note that you
should replace path/to/basic/web with the actual path for basic/web.
# Set document root to be "basic/web"
DocumentRoot "path/to/basic/web"
<Directory "path/to/basic/web">
# use mod_rewrite for pretty URL support
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>
To use Nginx, you should install PHP as an FPM SAPI.
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.
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;
access_log /path/to/basic/log/access.log main;
error_log /path/to/basic/log/error.log;
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;
try_files $uri =404;
}
location ~ /\.(ht|svn|git) {
deny all;
}
}
When using this configuration, you should also set cgi.fix_pathinfo=0 in the php.ini file
in order to avoid many unnecessary system stat() calls.
Also note that when running an HTTPS server, you need to add fastcgi_param HTTPS on; so that Yii
can properly detect if a connection is secure.