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