The most basic and straightforward way to get started with Yii 2 is to use the application boilerplate published by the Yii 2 team on their GitHub repository (https://github.com/yiisoft/yii2) and available through the Composer tool. In the prior versions of Yii, you had to manually download and extract the archive with the framework contents. While you can still do the same in Yii 2, this version is carefully crafted so that it's especially simple to install it using the Composer tool.
$ curl -sS https://getcomposer.org/installer | php
Now run the following command to create a subdirectory called
basic, and fill it with the basic application template:
$ php composer.phar create-project --prefer-dist --stability=dev \ yiisoft/yii2-app-basic basic
Please note that Yii 2 specifies several system-wide dependencies for itself. You probably will need to consult the
composer.json file inside their GitHub repository to learn about them beforehand (https://github.com/yiisoft/yii2). But in any case, Composer will tell you what you need to install to make Yii 2 workable. Yii 2 gets new updates quite often and its requirements are a moving target.
It's a line split into two lines for readability, with a slash denoting the overflow of the command line to the next line of text. Shell interpreters on Unix-like systems should understand this convention, so you can probably just copy and paste the code verbatim and it'll be executed correctly. You better check the documentation of Composer for the meaning of the beginning of the preceding command, but the part relevant to us is
yiisoft/yii2-app-basic basic, which means "copy contents of the repo published at https://github.com/yiisoft/yii2-app-basic to our local folder named
basic." The command will install the project skeleton in the form of a set of predefined folders, and among them the
vendor subdirectory, which contains quite a lot of other Composer packages. Inside the
basic folder will be your application root.
$ php -S localhost:8000 ât basic/web
8000 is the port number, which you can change to anything you want. This will launch the web server built into PHP.
This is not the preferred setup for PHP-based web applications, of course. The built-in web server was used only as a "smoke test" to verify that everything in general works. It is suitable only for local development without a heavy load. The next chapter will deal with the real-world deployment of a Yii-based web application.
Point your web browser at the
http://localhost:8000/ URL. You should see the welcome page for the Yii 2 application, which means that you're done setting things up.
You can get a comprehensive overview of the various folders inside the basic template by reading the README file provided with the template (https://github.com/yiisoft/yii2/blob/master/apps/basic/README.md), or by reading the global Yii 2 documentation page describing basic applications (http://www.yiiframework.com/doc-2.0/guide-start-installation.html).
The most important thing you should understand is that the publicly available web root directory is just one folder in the overall code base. It's the
web directory for our basic application. Every other folder is outside the web root directory, that is, out of reach for the web server.
As you have already seen in the installation description, given that you have PHP and, optionally, curl, this code base is ready to use right from the start; no specific environment is needed to be set up. All the dependencies are managed through the Composer tool.
A three-tier automatic testing harness is already set up in the basic template. It contains acceptance, functional, and unit tests covering most of the functionalities. The tests already included in the template are useful as examples that show how to utilize the testing framework used, which is Codeception (http://codeception.com/).
The template can be really useful to you if all you need is something like a news feed feature or a web tool spanning a couple of pages. However, the absence of separation by subsystems, such as the administrative backend and public frontend, will start to hinder you on a larger web application; probably, an application with more than just 10 unique routes.
Note that by reading the project dependencies in the
composer.json file, Yii 2 has several important parts separated out as pluggable packages, and they are already included in your code base by Composer. These packages are listed as follows:
Gii, the code generator, which we will discuss in detail in Chapter 3, Automatically Generating the CRUD Code
The debug console that is already enabled on the basic application template
A wrapper around the Codeception testing framework
The Twitter Bootstrap UI library packaged as a Yii 2 asset bundle (it's practically ubiquitous nowadays, but here's the link anyway: http://getbootstrap.com/)
The first three are set up so that you get them only when you are developing the application, since they are useless and even harmful in the production environment. Most probably, you'll need all of these on any serious project though.
Apart from the basic application template, Yii 2 has an advanced application template. It's geared more towards medium-sized applications (such as applications that are really useful to businesses), and its main feature is two separate web interfaces: one dedicated to content management and the other to presenting this content to visitors. So, you get an almost complete CMS skeleton with this template.
$ curl -sS https://getcomposer.org/installer | php $ php composer.phar create-project --prefer-dist --stability=dev \ yiisoft/yii2-app-advanced advanced
You can see that the difference is just that instead of the word "basic", we use the word "advanced".
Now, let's make further changes. First, go to the newly created directory named
advanced. After this, you need to generate the required local configuration by running the following command:
Yes, it's just the
init script from the root of the code base. It'll ask you whether you want a development mode or a production mode and create all the necessary auxiliary configuration snippets and entry scripts. To be precise, it just copies the contents of the
prod folders from the
environments subdirectory depending on whether you selected the development environment or the production one. Just open the
environments subdirectory and you'll understand how it works.
Next, you need to create the database to be used by this application. By default, for configuration of a development environment, you have to set up a MySQL database named
yii2advanced accessible from the
localhost at the default MySQL port for user
root without any password. You can see the details in the
Given that you have the database set up, you need to run migrations. We'll talk about migration scripts in the next chapter (and we will even write several scripts ourselves), but if the very concept of database migrations is foreign to you, you can read about it in the official documentation at the Yii 2 website (at the time of writing this, there is no official documentation, but the framework has the docs included in the GitHub repository at https://github.com/yiisoft/yii2/blob/master/docs/guide/db-migrations.md).
Just run the following command anyway:
$ ./yii migrate
It'll present you with a list of exactly one migration and ask you for confirmation before doing its job.
Now, you are ready. Make both the sides of the application accessible for you by executing the following commands:
$ php -S localhost:8080 -t frontend/web $ php -S localhost:8081 -t backend/web
As with the basic application template, we are using the built-in PHP web server just because it's a lot simpler to be demonstrated in the book than explain how to set up Apache or some other web server to serve from these folders.
Now you'll have the backend side of the application intended to be used by content managers and the frontend side of the application intended to be the website your visitors will see. Also, note that you have a completely controllable console runner launched by the
yii script you used when doing migrations.
Advanced application has exactly the same frontend as basic application. Here is how its backend looks like:
The advanced template backend is locked down initially. After logging in, you get the same page as the one from the basic template or the advanced template frontend, but with only the login feature in the menu.
frontendfolder is the application structure for the public-facing side of your website. Real functionalities and the content of your website or web application is expected to be placed here.
The folder named
backendis for your CMS, protected from unauthorized access. You are expected to place all of your admin-accessible CRUD here.
consolefolder is mainly for your custom console commands, in hope you'll have any, and a lot more likely, for your migration scripts.
commonfolder contains code that will be used by all the entry points, since it's a single application after all.
Of course, nobody forces you to use the frontend and backend sides as described. You just have two web frontends sharing the same code base, so you are free to use them as you wish. However, the UI already prepared for the advanced template that has a password-protected backend right from the start.
You should know about the login feature for the freshly installed advanced application template. Initially, it had no users defined, and you had to create one by utilizing the signup feature at the frontend. After that, you'll be able to login to both backend and frontend using the created credentials. The frontend is identical to the basic application, and the backend is stripped of everything except the login feature and front page, so everything is up to you.
A short overview of the installation of the advanced application:
$ curl -sS https://getcomposer.org/installer | php $ php composer.phar create-project --prefer-dist \ --stability=dev yiisoft/yii2-app-advanced advanced $ cd advanced $ ./init $ mysql -u root -e 'create database yii2advanced' $./yii migrate $ php -S localhost:8080 -t frontend/web $ php -S localhost:8081 -t backend/web
Yii 2 allows you to configure almost all paths used by the framework, and hence you can create any directory tree you wish. By utilizing the PHP 5.3 namespaces wisely, you can even have a physical structure of your project different from the logical one, that is, your files will lie in folders differently from how your classes are structured by namespaces. This will surely be quite tedious to do though.
In the next chapter, we'll look at how we can utilize Yii in a (albeit small) real-world project, built completely from scratch, and without using the templates we saw in this chapter.