Qiang Xue
12 years ago
5 changed files with 299 additions and 79 deletions
@ -0,0 +1,138 @@ |
|||||||
|
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. |
||||||
@ -0,0 +1,142 @@ |
|||||||
|
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. |
||||||
@ -1,69 +0,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 |
|
||||||
Loading…
Reference in new issue