Skip to content

Y
yii2
Commit f68bc346 by Qiang Xue
Options

Merge branch 'master' of github.com:yiisoft/yii2

parents 369f82b4 1367f957
Showing with 300 additions and 79 deletions
docs/guide/apps-advanced.md 0 → 100644
Advanced application template
=============================
This template is for large projects developed in teams where backend is divided from frontend, application is deployed
to multiple servers etc. This application template also goes a bit further regarding features and provides essential
database, signup and password restore out of the box.
Directory structure
-------------------
The root directory contains the following subdirectories:
- `backend` - backend web application.
- `common` - files common to all applications.
- `console` - console application.
- `environments` - environment configs.
- `frontend` - frontend web application.
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.
- `composer.json` - Composer config described in detail below.
- `init` - initialization script described in "Composer config described in detail below".
- `init.bat` - same for Windows.
- `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.
Applications
------------
There are three applications in advanced template: frontend, backend and console. Frontend is typically what is presented
to end user, the project itself. Backend is admin panel, analytics and such functionality. Console is typically used for
cron jobs and low-level server management. Also it's used during application deployment and handles migrations and assets.
There's also a `common` directory that contains files used by more than one application. For example, `User` model.
frontend and backend are both web applications and both contain `web` directory. That's the webroot you should point your
webserver to.
Each application has its own namespace and alias corresponding to its name. Same applies to common directory.
Configuration and environments
------------------------------
There are multiple problems with straightforward approach to configuration:
- Each team member has its own configuration options. Commiting such config will affect other team members.
- Production database password and API keys should not end up in repository.
- There are multiple servers: development, testing, production. Each should have its own configuration.
- Defining all configuration options for each case is very repetitive and takes too much time to maintain.
In order to solve these issues Yii introduces environments concept that is very simple. Each environment is represented
by a set of files under `environments` directory. `init` command is used to switch between these. What is really does is
just copying everything from environment directory over the root directory where all applications are.
Typically environment contains application bootstrap files such as `index.php` and config files postfixed with
`-local.php`. These are added to `.gitignore` and never added to source code repository.
In order to avoid duplication configurations are overrding each other. For example, frontend reads configuration in the
following order:
- `frontend/config/main.php`
- `frontend/config/main-local.php`
Parameters are read in the following order:
- `common/config/params.php`
- `common/config/params-local.php`
- `frontend/config/params.php`
- `frontend/config/params-local.php`
The later config file overrides the former.
Another difference is that most application component configurations are moved to params. Since params are read from
`common` as well it allows you to specify database connection in one file and it will be then used for all applications.
Configuring Composer
--------------------
After application template is installed it's a good idea to adjust defaul `composer.json` that can be found in the root
directory:
```javascript
{
"name": "yiisoft/yii2-app-advanced",
"description": "Yii 2 Advanced Application Template",
"keywords": ["yii", "framework", "advanced", "application template"],
"homepage": "http://www.yiiframework.com/",
"type": "project",
"license": "BSD-3-Clause",
"support": {
"issues": "https://github.com/yiisoft/yii2/issues?state=open",
"forum": "http://www.yiiframework.com/forum/",
"wiki": "http://www.yiiframework.com/wiki/",
"irc": "irc://irc.freenode.net/yii",
"source": "https://github.com/yiisoft/yii2"
},
"minimum-stability": "dev",
"require": {
"php": ">=5.3.0",
"yiisoft/yii2": "dev-master",
"yiisoft/yii2-composer": "dev-master"
},
"scripts": {
"post-create-project-cmd": [
"yii\\composer\\InstallHandler::setPermissions"
]
},
"extra": {
"yii-install-writable": [
"backend/runtime",
"backend/web/assets",
"console/runtime",
"console/migrations",
"frontend/runtime",
"frontend/web/assets"
]
}
}
```
First we're updating basic information. Change `name`, `description`, `keywords`, `homepage` and `support` to match
your project.
Now the interesting part. You can add more packages your application needs to `require` section.
For example, to use markdown helper you need to add `michelf/php-markdown`. All these packages are coming from
[packagist.org](https://packagist.org/) so feel free to browse the website for useful code.
After your `composer.json` is changed you can run `php composer.phar update`, wait till packages are downloaded and
installed and then just use them. Autoloading of classes will be handled automatically.
docs/guide/apps-basic.md 0 → 100644
Basic application template
==========================
This template is a perfect fit for small projects or learning Yii2.
The application has four pages: the homepage, the about page, the contact page and the login page.
The contact page displays a contact form that users can fill in to submit their inquiries to the webmaster,
and the login page allows users to be authenticated before accessing privileged contents.
Directory structure
-------------------
The basic application does not divide application directories much. Here's the basic structure:
- `commands` - console controllers.
- `config` - configuration.
- `controllers` - web controllers.
- `models` - application models.
- `runtime` - logs, states, file cache.
- `views` - view templates.
- `web` - webroot.
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:
- `AppAsset.php` - definition of application assets such as CSS, JavaScript etc. Check [Managing assets](assets.md) for
details.
- `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 except `AppAsset.php` 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.
Configuring Composer
--------------------
After application template is installed it's a good idea to adjust defaul `composer.json` that can be found in the root
directory:
```javascript
{
"name": "yiisoft/yii2-app-basic",
"description": "Yii 2 Basic Application Template",
"keywords": ["yii", "framework", "basic", "application template"],
"homepage": "http://www.yiiframework.com/",
"type": "project",
"license": "BSD-3-Clause",
"support": {
"issues": "https://github.com/yiisoft/yii2/issues?state=open",
"forum": "http://www.yiiframework.com/forum/",
"wiki": "http://www.yiiframework.com/wiki/",
"irc": "irc://irc.freenode.net/yii",
"source": "https://github.com/yiisoft/yii2"
},
"minimum-stability": "dev",
"require": {
"php": ">=5.3.0",
"yiisoft/yii2": "dev-master",
"yiisoft/yii2-composer": "dev-master"
},
"scripts": {
"post-create-project-cmd": [
"yii\\composer\\InstallHandler::setPermissions"
]
},
"extra": {
"yii-install-writable": [
"runtime",
"web/assets"
],
"yii-install-executable": [
"yii"
]
}
}
```
First we're updating basic information. Change `name`, `description`, `keywords`, `homepage` and `support` to match
your project.
Now the interesting part. You can add more packages your application needs to `require` section.
For example, to use markdown helper you need to add `michelf/php-markdown`. All these packages are coming from
[packagist.org](https://packagist.org/) so feel free to browse the website for useful code.
After your `composer.json` is changed you can run `php composer.phar update`, wait till packages are downloaded and
installed and then just use them. Autoloading of classes will be handled automatically.
\ No newline at end of file
docs/guide/bootstrap.md deleted 100644 → 0
Bootstrap with Yii
==================
Yii provides a few ready-to-use application templates. Based on your needs, you may
choose one of them to bootstrap your project.
In the following, we describe how to get started with the "Yii 2 Basic Application Template".
### Install via Composer
If you do not have [Composer](http://getcomposer.org/), you may download it from
[http://getcomposer.org/](http://getcomposer.org/) or run the following command on Linux/Unix/MacOS:
~~~
curl -s http://getcomposer.org/installer | php
~~~
You can then install the Bootstrap Application using the following command:
~~~
php composer.phar create-project --stability=dev yiisoft/yii2-app-basic yii-basic
~~~
Now you should be able to access the Bootstrap Application using the URL `http://localhost/yii-basic/web/`,
assuming `yii-basic` is directly under the document root of your Web server.
As you can see, the application has four pages: the homepage, the about page,
the contact page and the login page. The contact page displays a contact
form that users can fill in to submit their inquiries to the webmaster,
and the login page allows users to be authenticated before accessing privileged contents.
The following diagram shows the directory structure of this application.
~~~
yii-basic/
yii yii command line script for Unix/Linux
yii.bat yii command line script for Windows
requirements.php the requirement checker script
commands/ containing customized yii console commands
config/ containing configuration files
console.php the console application configuration
main.php the Web application configuration
controllers/ containing controller class files
SiteController.php the default controller class
vendor/ containing third-party extensions and libraries
models/ containing model class files
User.php the User model
LoginForm.php the form model for 'login' action
ContactForm.php the form model for 'contact' action
runtime/ containing temporarily generated files
views/ containing controller view and layout files
layouts/ containing layout view files
main.php the base layout shared by all pages
site/ containing view files for the 'site' controller
about.php the view for the 'about' action
contact.php the view for the 'contact' action
index.php the view for the 'index' action
login.php the view for the 'login' action
web/ containing Web-accessible resources
index.php Web application entry script file
assets/ containing published resource files
css/ containing CSS files
~~~
TBD
docs/guide/index.md
......@@ -7,9 +7,15 @@ Getting started
===============
- [Installation](installation.md)
- [Bootstrap with Yii](bootstrap.md)
- [Configuration](configuration.md)
Application templates
=====================
- [Basic](apps-basic.md)
- [Advanced](apps-advanced.md)
- [Creating your own application template](apps-own.md)
Base concepts
=============
......@@ -57,13 +63,6 @@ Toolbox
- [Error Handling](error.md)
- [Logging](logging.md)
Application templates
=====================
- [Basic](application-basic.md)
- [Advanced](application-advanced.md)
- [Creating your own application template](application-own.md)
More
====
......@@ -76,5 +75,6 @@ More
- [Theming](theming.md)
- [Console Application](console.md)
- [Performance Tuning](performance.md)
- [Managing assets](assets.md)
- [Testing](testing.md)
- [Upgrading from 1.1 to 2.0](upgrade-from-v1.md)
docs/guide/installation.md
......@@ -4,7 +4,15 @@ Installation
Installing via Composer
-----------------------
The recommended way of installing Yii is by using Composer package manager.
The recommended way of installing Yii is by using [Composer](http://getcomposer.org/) package manager. If you do not
have it, you may download it from [http://getcomposer.org/](http://getcomposer.org/) or run the following command:
```
curl -s http://getcomposer.org/installer | php
```
Yii provides a few ready-to-use application templates. Based on your needs, you may choose one of them to bootstrap
your project.
There are two application templates available:
......@@ -12,7 +20,8 @@ There are two application templates available:
- [advanced](https://github.com/yiisoft/yii2-app-advanced) that is a set of frontend, backend, console, common
(shared code) and environments support.
Please refer to installation instructions on these pages.
Please refer to installation instructions on these pages. To read more about ideas behing these application templates and
proposed usage refer to [basic application template](apps-basic.md) and [advanced application template](apps-advanced.md).
Installing from zip
-------------------
......
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