Skip to content

Y
yii2
Commit 3e351fb8 by Qiang Xue
Options

guide wip [skip ci]

parent e4bd3b59
Showing with 242 additions and 63 deletions
docs/guide/start-installation.md
......@@ -6,6 +6,7 @@ The former is the preferred way as it allows you to install new [extensions](str
or update Yii by running a single command.
<a name="installing-via-composer"></a>
Installing via Composer
-----------------------
......@@ -39,6 +40,7 @@ composer create-project --prefer-dist --stability=dev yiisoft/yii2-app-basic bas
Note that the development version of Yii should not be used for production as it may break your running code.
<a name="installing-from-archive-file"></a>
Installing from an Archive File
-------------------------------
......@@ -48,6 +50,7 @@ Installing Yii from an archive file involves two steps:
2. Unpack the downloaded file to a Web accessible folder.
<a name="other-installation-options"></a>
Other Installation Options
--------------------------
......@@ -62,6 +65,7 @@ There are other installation options available:
you may consider [Advanced Application Template](tutorial-advanced-app.md).
<a name="verifying-installation"></a>
Verifying Installation
----------------------
......@@ -84,28 +88,110 @@ Yii's requirements by using one of the following approaches:
```
You should configure your PHP installation so that it meets the minimum requirement of Yii.
Yii has been tested with the [Apache HTTP server](http://httpd.apache.org/) and [Nginx HTTP server](http://nginx.org/)
on both Windows and Linux. It requires PHP 5.4 or above. And you should install
In general, you should have PHP 5.4 or above. And you should install
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.
Adjusting Document Root
<a name="configuring-web-servers"></a>
Configuring Web Servers
-----------------------
The above installation is fine in a development environment which can only be accessed from the local machine
or the local network.
> Info: You may skip this sub-section for now if you are just testing 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](http://httpd.apache.org/) or an [Nginx HTTP server](http://nginx.org/), on
either Windows or Linux.
On a production server, you may want to configure your Web server so that the application can be accessed
via the URL `http://hostname` without the part `/basic/web/index.php`. This requires configuring your
Web server by
* pointing the Web document root to the `basic/web` folder;
* and hiding `index.php` from the URL.
By setting `basic/web` as the document root, you also secure your application by preventing end users
from accessing your private application code and sensitive data files that are stored in the sibling directories
of `basic/web`.
In a production environment, you should configure the Web server by pointing its document root
to the `basic/web` folder. This is necessary because besides Web accessible files under the `basic/web` folder,
the `basic` folder also contains your application code and/or sensitive data files that you do not want to
expose to the Web. After the adjustment, you should be able to access the installed application via URL:
Below we show the configurations recommended for Apache and Nginx.
> Info: If your application will run in a shared hosting environment where you do not have the permission
to modify its Web server setting, you may adjust the structure of your application. Please refer to
the [Shared Hosting Environment](tutorial-shared-hosting.md) section for more details.
<a name="recommended-apache-configuration"></a>
### Recommended Apache Configuration
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 of `basic/web`.
```
http://localhost/index.php
# 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>
```
If you plan to deploy your application to a shared hosting environment and you do not have the permission
to modify its Web server setting, please refer to the [Shared Hosting Environment](tutorial-shared-hosting.md) section
on how to adjust your application.
<a name="recommended-nginx-configuration"></a>
### Recommended Nginx Configuration
You should have installed PHP as an [FPM SAPI](http://php.net/install.fpm) for [Nginx](http://wiki.nginx.org/).
Use the following Nginx configuration and replace `path/to/basic/web` with the actual path of `basic/web`.
```
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/project/log/access.log main;
error_log /path/to/project/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;
}
location ~ /\.(ht|svn|git) {
deny all;
}
}
```
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.
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.
docs/guide/start-lifecycle.md deleted 100644 → 0
Request Lifecycle
=================
> Note: This section is under development.
The following diagram shows a typical workflow of a Yii application handling a user request:
![Typical workflow of a Yii application](images/flow.png)
1. A user makes a request of the URL `http://www.example.com/index.php?r=post/show&id=1`.
The Web server handles the request by executing the bootstrap script `index.php`.
2. The bootstrap script creates an [[yii\web\Application|Application]] instance and runs it.
3. The Application instance obtains the detailed user request information from an application component named `request`.
4. The application determines which [controller](controller.md) and which action of that controller was requested.
This is accomplished with the help of an application component named `urlManager`.
For this example, the controller is `post`, which refers to the `PostController` class, and the action is `show`,
whose actual meaning is determined by the controller.
5. The application creates an instance of the requested controller to further handle the user's request.
The controller determines that the action `show` refers to a method named `actionShow` in the controller class.
The controller then creates and executes any filters associated with this action (e.g. access control or benchmarking).
The action is then executed, if execution is allowed by the filters (e.g., if the user has permission to execute that action).
6. The action creates a `Post` [model](model.md) instance, using the underlying database table, where the ID value of the corresponding record is `1`.
7. The action renders a [view](view.md) named `show`, providing to the view the `Post` model instance.
8. The view reads the attributes of the `Post` model instance and displays the values of those attributes.
9. The view executes some [widgets](view.md#widgets).
10. The view rendering result--the output from the previous steps--is embedded within a [layout](view.md#layout) to create a complete HTML page.
11. The action completes the view rendering and displays the result to the user.
docs/guide/start-structure.md deleted 100644 → 0
Application Structure
=====================
> Note: This section is under development.
Yii implements the model-view-controller (MVC) design pattern, which is
widely adopted in Web and other application programming. MVC aims to separate business logic from
user interface considerations, allowing developers to more easily change one component of an application without affecting, or even touching, another.
In MVC, the *model* represents both the
information (the data) and the business rules to which the data must adhere. The *view* contains elements
of the user interface, such as text, images, and form elements. The *controller* manages
the communication between the model and the view, acting as an agent that handles actions and requests.
Besides implementing the MVC design pattern, Yii also introduces a *front-controller*, called
*application*. The front-controller encapsulates the *execution context* for the processing of a request. This means that the front-controller collects information about a user request, and
then dispatches it to an appropriate controller for the actual handling of that request. In other words, the front-controller is the primary application manager, handling all requests and delegating action accordingly.
The following diagram shows the static structure of a Yii application:
![Static structure of Yii application](images/structure.png)
docs/guide/start-workflow.md 0 → 100644
Running Applications
====================
Application Structure
---------------------
The basic application that you just installed is organized as follows,
```
basic/ application base path
assets/ contains asset bundles
commands/ contains console commands
config/ contains application configurations
controllers/ contains controller classes
mail/ contains views for mail messages
layouts/ contains layouts for mail messages
models/ contains model classes
runtime/ contains files generated during runtime, such as logs, cache files
views/ application view base path
layouts/ contains layout files
site/ contains view files for the site controller
web/ application Web root
assets/ contains published asset files by Yii, such as css files, js files
css/ contains CSS files
```
The basic application template includes four pages: a homepage, an about page, a contact page, and a login page.
The contact page displays a contact form that users can fill in to submit their inquiries to the webmaster. Assuming the site has access to a mail server and that the administrator's email address is entered in the configuration file, the contact form will work. The same goes for the login page, which allows users to be authenticated before accessing privileged content.
Root directory contains a set of files.
- `.gitignore` contains a list of directories ignored by git version system. If you need something never get to your source
code repository, add it there.
- `codeception.yml` - Codeception config.
- `composer.json` - Composer config described in detail below.
- `LICENSE.md` - license info. Put your project license there. Especially when opensourcing.
- `README.md` - basic info about installing template. Consider replacing it with information about your project and its
installation.
- `requirements.php` - Yii requirements checker.
- `yii` - console application bootstrap.
- `yii.bat` - same for Windows.
### config
This directory contains configuration files:
- `console.php` - console application configuration.
- `params.php` - common application parameters.
- `web.php` - web application configuration.
- `web-test.php` - web application configuration used when running functional tests.
All these files are returning arrays used to configure corresponding application properties. Check
[Configuration](configuration.md) guide section for details.
### views
Views directory contains templates your application is using. In the basic template there are:
```
layouts
main.php
site
about.php
contact.php
error.php
index.php
login.php
```
`layouts` contains HTML layouts i.e. page markup except content: doctype, head section, main menu, footer etc.
The rest are typically controller views. By convention these are located in subdirectories matching controller id. For
`SiteController` views are under `site`. Names of the views themselves are typically match controller action names.
Partials are often named starting with underscore.
### web
Directory is a webroot. Typically a webserver is pointed into it.
```
assets
css
index.php
index-test.php
```
`assets` contains published asset files such as CSS, JavaScript etc. Publishing process is automatic so you don't need
to do anything with this directory other than making sure Yii has enough permissions to write to it.
`css` contains plain CSS files and is useful for global CSS that isn't going to be compressed or merged by assets manager.
`index.php` is the main web application bootstrap and is the central entry point for it. `index-test.php` is the entry
point for functional testing.
The following diagram shows a typical workflow of a Yii application handling a user request:
![Typical workflow of a Yii application](images/flow.png)
1. A user makes a request of the URL `http://www.example.com/index.php?r=post/show&id=1`.
The Web server handles the request by executing the bootstrap script `index.php`.
2. The bootstrap script creates an [[yii\web\Application|Application]] instance and runs it.
3. The Application instance obtains the detailed user request information from an application component named `request`.
4. The application determines which [controller](controller.md) and which action of that controller was requested.
This is accomplished with the help of an application component named `urlManager`.
For this example, the controller is `post`, which refers to the `PostController` class, and the action is `show`,
whose actual meaning is determined by the controller.
5. The application creates an instance of the requested controller to further handle the user's request.
The controller determines that the action `show` refers to a method named `actionShow` in the controller class.
The controller then creates and executes any filters associated with this action (e.g. access control or benchmarking).
The action is then executed, if execution is allowed by the filters (e.g., if the user has permission to execute that action).
6. The action creates a `Post` [model](model.md) instance, using the underlying database table, where the ID value of the corresponding record is `1`.
7. The action renders a [view](view.md) named `show`, providing to the view the `Post` model instance.
8. The view reads the attributes of the `Post` model instance and displays the values of those attributes.
9. The view executes some [widgets](view.md#widgets).
10. The view rendering result--the output from the previous steps--is embedded within a [layout](view.md#layout) to create a complete HTML page.
11. The action completes the view rendering and displays the result to the user.
Application Structure
-----
> Note: This section is under development.
Yii implements the model-view-controller (MVC) design pattern, which is
widely adopted in Web and other application programming. MVC aims to separate business logic from
user interface considerations, allowing developers to more easily change one component of an application without affecting, or even touching, another.
In MVC, the *model* represents both the
information (the data) and the business rules to which the data must adhere. The *view* contains elements
of the user interface, such as text, images, and form elements. The *controller* manages
the communication between the model and the view, acting as an agent that handles actions and requests.
Besides implementing the MVC design pattern, Yii also introduces a *front-controller*, called
*application*. The front-controller encapsulates the *execution context* for the processing of a request. This means that the front-controller collects information about a user request, and
then dispatches it to an appropriate controller for the actual handling of that request. In other words, the front-controller is the primary application manager, handling all requests and delegating action accordingly.
The following diagram shows the static structure of a Yii application:
![Static structure of Yii application](images/structure.png)
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment