From dd908985b26c54d5aa2d3520ff0065847bb6e05c Mon Sep 17 00:00:00 2001 From: Alexander Makarov Date: Tue, 13 Aug 2013 15:58:22 +0400 Subject: [PATCH 1/4] Reorganized application template docs structure --- docs/guide/apps-advanced.md | 3 ++ docs/guide/apps-basic.md | 6 ++++ docs/guide/bootstrap.md | 69 --------------------------------------------- docs/guide/index.md | 15 +++++----- docs/guide/installation.md | 13 +++++++-- 5 files changed, 27 insertions(+), 79 deletions(-) create mode 100644 docs/guide/apps-advanced.md create mode 100644 docs/guide/apps-basic.md delete mode 100644 docs/guide/bootstrap.md diff --git a/docs/guide/apps-advanced.md b/docs/guide/apps-advanced.md new file mode 100644 index 0000000..978c786 --- /dev/null +++ b/docs/guide/apps-advanced.md @@ -0,0 +1,3 @@ +Advanced application template +============================= + diff --git a/docs/guide/apps-basic.md b/docs/guide/apps-basic.md new file mode 100644 index 0000000..98dc4f0 --- /dev/null +++ b/docs/guide/apps-basic.md @@ -0,0 +1,6 @@ +Basic application template +========================== + +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. \ No newline at end of file diff --git a/docs/guide/bootstrap.md b/docs/guide/bootstrap.md deleted file mode 100644 index 08dc6aa..0000000 --- a/docs/guide/bootstrap.md +++ /dev/null @@ -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 diff --git a/docs/guide/index.md b/docs/guide/index.md index cdc810a..7675a8a 100644 --- a/docs/guide/index.md +++ b/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 ==== diff --git a/docs/guide/installation.md b/docs/guide/installation.md index 5447635..c7b7cee 100644 --- a/docs/guide/installation.md +++ b/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 ------------------- From 88339b0cf62d2ae8657acb14b7da68cd24720304 Mon Sep 17 00:00:00 2001 From: Alexander Makarov Date: Tue, 13 Aug 2013 17:25:02 +0400 Subject: [PATCH 2/4] basic application usage guide --- docs/guide/apps-basic.md | 138 ++++++++++++++++++++++++++++++++++++++++++++++- docs/guide/index.md | 1 + 2 files changed, 138 insertions(+), 1 deletion(-) diff --git a/docs/guide/apps-basic.md b/docs/guide/apps-basic.md index 98dc4f0..d55f16c 100644 --- a/docs/guide/apps-basic.md +++ b/docs/guide/apps-basic.md @@ -1,6 +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. \ No newline at end of file +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. Don't forget to delete it when deployed to the server. +- `yii` - console application bootstrap. +- `yii.bat` - console application bootstrap 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 diff --git a/docs/guide/index.md b/docs/guide/index.md index 7675a8a..df16890 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -75,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) From 55b0b4100979ca6640f936470915e18ab4954e9f Mon Sep 17 00:00:00 2001 From: Alexander Makarov Date: Tue, 13 Aug 2013 18:03:36 +0400 Subject: [PATCH 3/4] started advanced application guide --- docs/guide/apps-advanced.md | 103 ++++++++++++++++++++++++++++++++++++++++++++ docs/guide/apps-basic.md | 4 +- 2 files changed, 105 insertions(+), 2 deletions(-) diff --git a/docs/guide/apps-advanced.md b/docs/guide/apps-advanced.md index 978c786..0091730 100644 --- a/docs/guide/apps-advanced.md +++ b/docs/guide/apps-advanced.md @@ -1,3 +1,106 @@ 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. + +Configuration and environments +------------------------------ + + + +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. diff --git a/docs/guide/apps-basic.md b/docs/guide/apps-basic.md index d55f16c..696219a 100644 --- a/docs/guide/apps-basic.md +++ b/docs/guide/apps-basic.md @@ -29,9 +29,9 @@ code repository, add it there. - `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. Don't forget to delete it when deployed to the server. +- `requirements.php` - Yii requirements checker. - `yii` - console application bootstrap. -- `yii.bat` - console application bootstrap for Windows. +- `yii.bat` - same for Windows. ### config From 1367f95725a28f1e574e2db9e4b3f21a9c640677 Mon Sep 17 00:00:00 2001 From: Alexander Makarov Date: Tue, 13 Aug 2013 18:35:01 +0400 Subject: [PATCH 4/4] more on advanced app docs --- docs/guide/apps-advanced.md | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/guide/apps-advanced.md b/docs/guide/apps-advanced.md index 0091730..728a862 100644 --- a/docs/guide/apps-advanced.md +++ b/docs/guide/apps-advanced.md @@ -42,10 +42,42 @@ There's also a `common` directory that contains files used by more than one appl 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 --------------------