guide wip

docs/guide/bootstrap.md

@@ -0,0 +1,63 @@
+Bootstrap with Yii
+==================
+
+A ready-to-use Web application is distributed together with Yii. You may find
+its source code under the `app` folder after you expand the Yii release file.
+If you have installed Yii under a Web-accessible folder, you should be able to
+access this application through the following URL:
+
+~~~
+http://localhost/yii/app/index.php
+~~~
+
+
+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.
+
+~~~
+app/
+   index.php                 Web application entry script file
+   index-test.php            entry script file for the functional tests
+   assets/                   containing published resource files
+   css/                      containing CSS files
+   img/                      containing image files
+   themes/                   containing application themes
+   protected/                containing protected application files
+      yiic                   yiic command line script for Unix/Linux
+      yiic.bat               yiic command line script for Windows
+      yiic.php               yiic command line PHP script
+      commands/              containing customized 'yiic' commands
+      components/            containing reusable user components
+      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
+      data/                  containing the sample database
+         schema.mysql.sql    the DB schema for the sample MySQL database
+         schema.sqlite.sql   the DB schema for the sample SQLite database
+         bootstrap.db        the sample SQLite database file
+      vendor/                containing third-party extensions and libraries
+      messages/              containing translated messages
+      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
+~~~
+
+
+TBD

docs/guide/index.md

@@ -0,0 +1,30 @@
+* [Overview](overview.md)
+* [Installation](installation.md)
+* [Bootstrap with Yii](bootstrap.md)
+* [MVC Overview](mvc.md)
+* [Controller](controller.md)
+* [Model](model.md)
+* [View](view.md)
+* [Application](application.md)
+* [Form](form.md)
+* [Data Validation](validation.md)
+* [Database Access Objects](dao.md)
+* [Query Builder](query-builder.md)
+* [ActiveRecord](active-record.md)
+* [Database Migration](migration.md)
+* [Caching](caching.md)
+* [Internationalization](i18n.md)
+* [Extending Yii](extension.md)
+* [Authentication](authentication.md)
+* [Authorization](authorization.md)
+* [Logging](logging.md)
+* [URL Management](url.md)
+* [Theming](theming.md)
+* [Error Handling](error.md)
+* [Template](template.md)
+* [Console Application](console.md)
+* [Security](security.md)
+* [Performance Tuning](performance.md)
+* [Testing](testing.md)
+* [Automatic Code Generation](gii.md)
+* [Upgrading from 1.1 to 2.0](upgrade.md)

docs/guide/installation.md

@@ -0,0 +1,111 @@
+Installation
+============
+
+Installation of Yii mainly involves the following two steps:
+
+   1. Download Yii Framework from [yiiframework.com](http://www.yiiframework.com/).
+   2. Unpack the Yii release file to a Web-accessible directory.
+
+> Tip: Yii does not need to be installed under a Web-accessible directory.
+A Yii application has one entry script which is usually the only file that
+needs to be exposed to Web users. Other PHP scripts, including those from
+Yii, should be protected from Web access; otherwise they might be exploited
+by hackers.
+
+
+Requirements
+------------
+
+After installing Yii, you may want to verify that your server satisfies
+Yii's requirements. You can do so by accessing the requirement checker
+script via the following URL in a Web browser:
+
+~~~
+http://hostname/path/to/yii/requirements/index.php
+~~~
+
+Yii requires PHP 5.3, so the server must have PHP 5.3 or above installed and
+available to the web server.  Yii has been tested with [Apache HTTP server](http://httpd.apache.org/)
+on Windows and Linux.  It may also run on other Web servers and platforms,
+provided PHP 5.3 is supported.
+
+
+Recommended Apache Configuration
+--------------------------------
+
+Yii is ready to work with a default Apache web server configuration.
+The `.htaccess` files in Yii framework and application folders restrict
+access to the restricted resources. To hide the bootstrap file (usually `index.php`)
+in your URLs you can add `mod_rewrite` instructions to the `.htaccess` file
+in your document root or to the virtual host configuration:
+
+~~~
+RewriteEngine on
+
+# if a directory or a file exists, use it directly
+RewriteCond %{REQUEST_FILENAME} !-f
+RewriteCond %{REQUEST_FILENAME} !-d
+# otherwise forward it to index.php
+RewriteRule . index.php
+~~~
+
+
+Recommended Nginx Configuration
+-------------------------------
+
+You can use Yii with [Nginx](http://wiki.nginx.org/) and PHP with [FPM SAPI](http://php.net/install.fpm).
+Here is a sample host configuration. It defines the bootstrap file and makes
+Yii to catch all requests to nonexistent files, which allows us to have nice-looking URLs.
+
+~~~
+server {
+    set $host_path "/www/mysite";
+    access_log  /www/mysite/log/access.log  main;
+
+    server_name  mysite;
+    root   $host_path/htdocs;
+    set $yii_bootstrap "index.php";
+
+    charset utf-8;
+
+    location / {
+        index  index.html $yii_bootstrap;
+        try_files $uri $uri/ /$yii_bootstrap?$args;
+    }
+
+    location ~ ^/(protected|framework|themes/\w+/views) {
+        deny  all;
+    }
+
+    #avoid processing of calls to unexisting static files by yii
+    location ~ \.(js|css|png|jpg|gif|swf|ico|pdf|mov|fla|zip|rar)$ {
+        try_files $uri =404;
+    }
+
+    # pass the PHP scripts to FastCGI server listening on 127.0.0.1:9000
+    #
+    location ~ \.php {
+        fastcgi_split_path_info  ^(.+\.php)(.*)$;
+
+        #let yii catch the calls to unexising PHP files
+        set $fsn /$yii_bootstrap;
+        if (-f $document_root$fastcgi_script_name){
+            set $fsn $fastcgi_script_name;
+        }
+
+        fastcgi_pass   127.0.0.1:9000;
+        include fastcgi_params;
+        fastcgi_param  SCRIPT_FILENAME  $document_root$fsn;
+
+        #PATH_INFO and PATH_TRANSLATED can be omitted, but RFC 3875 specifies them for CGI
+        fastcgi_param  PATH_INFO        $fastcgi_path_info;
+        fastcgi_param  PATH_TRANSLATED  $document_root$fsn;
+    }
+
+    location ~ /\.ht {
+        deny  all;
+    }
+}
+~~~
+
+Using this configuration you can set `cgi.fix_pathinfo=0` in php.ini to avoid many unnecessary system stat() calls.

docs/guide/mvc.md

@@ -0,0 +1,51 @@
+MVC Overview
+============
+
+Yii implements the model-view-controller (MVC) design pattern, which is
+widely adopted in Web programming. MVC aims to separate business logic from
+user interface considerations, so that developers can more easily change
+each part without affecting the other. In MVC, the model represents the
+information (the data) and the business rules; the view contains elements
+of the user interface such as text, form inputs; and the controller manages
+the communication between the model and the view.
+
+Besides implementing MVC, Yii also introduces a front-controller, called
+`Application`, which encapsulates the execution context for the processing
+of a request.  Application collects some information about a user request and
+then dispatches it to an appropriate controller for further handling.
+
+The following diagram shows the static structure of a Yii application:
+
+![Static structure of Yii application](structure.png)
+
+
+A Typical Workflow
+------------------
+The following diagram shows a typical workflow of a Yii application when
+it is handling a user request:
+
+![Typical workflow of a Yii application](flow.png)
+
+   1. A user makes a request with the URL `http://www.example.com/index.php?r=post/show&id=1`
+and the Web server handles the request by executing the bootstrap script `index.php`.
+   2. The bootstrap script creates an [Application](/doc/guide/basics.application)
+instance and runs it.
+   3. The Application obtains detailed user request information from
+an [application component](/doc/guide/basics.application#application-component)
+named `request`.
+   4. The application determines the requested [controller](/doc/guide/basics.controller)
+and [action](/doc/guide/basics.controller#action) 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 request. The controller determines that the action
+`show` refers to a method named `actionShow` in the controller class. It then
+creates and executes filters (e.g. access control, benchmarking) associated
+with this action. The action is executed if it is allowed by the filters.
+   6. The action reads a `Post` [model](/doc/guide/basics.model) whose ID is `1` from the database.
+   7. The action renders a [view](/doc/guide/basics.view) named `show` with the `Post` model.
+   8. The view reads and displays the attributes of the `Post` model.
+   9. The view executes some [widgets](/doc/guide/basics.view#widget).
+   10. The view rendering result is embedded in a [layout](/doc/guide/basics.view#layout).
+   11. The action completes the view rendering and displays the result to the user.

docs/guide/overview.md

@@ -0,0 +1,36 @@
+What is Yii
+===========
+
+Yii is a high-performance, component-based PHP framework for developing
+large-scale Web applications rapidly. It enables maximum reusability in Web
+programming and can significantly accelerate your Web application development
+process. The name Yii (pronounced `Yee` or `[ji:]`) is an acronym for
+"**Yes It Is!**".
+
+
+Requirements
+------------
+
+To run a Yii-powered Web application, you need a Web server that supports
+PHP 5.3.?.
+
+For developers who want to use Yii, understanding object-oriented
+programming (OOP) is very helpful, because Yii is a pure OOP framework.
+
+
+What is Yii Best for?
+---------------------
+
+Yii is a generic Web programming framework that can be used for developing
+virtually any type of Web application.  Because it is light-weight and
+equipped with sophisticated caching mechanisms, it is especially suited
+to high-traffic applications, such as portals, forums, content
+management systems (CMS), e-commerce systems, etc.
+
+
+How does Yii Compare with Other Frameworks?
+-------------------------------------------
+
+Like most PHP frameworks, Yii is an MVC (Model-View-Controller) framework.
+
+TBD

docs/guide/title.md

@@ -0,0 +1,8 @@
+The Definitive Guide to Yii 2.0
+===============================
+
+This tutorial is released under [the Terms of Yii Documentation](http://www.yiiframework.com/doc/terms/).
+
+All Rights Reserved.
+
+2008 (c) Yii Software LLC.

todo.md

@@ -1,49 +0,0 @@
-- caching
-	* dependency unit tests
-- validators
-	* Refactor validators to add validateValue() for every validator, if possible. Check if value is an array.
-	* FileValidator: depends on CUploadedFile
-	* CaptchaValidator: depends on CaptchaAction
-	* DateValidator: should we use CDateTimeParser, or simply use strtotime()?
-	* CompareValidator::clientValidateAttribute(): depends on CHtml::activeId()
-
-memo
-	* Minimal PHP version required: 5.3.7 (http://www.php.net/manual/en/function.crypt.php)
----
-
-- base
-	* module
-	  - Module should be able to define its own configuration including routes. Application should be able to overwrite it.
-	* application
-- built-in console commands
-	+ api doc builder
-		* support for markdown syntax
-		* support for [[name]]
-		* consider to be released as a separate tool for user app docs
-- i18n
-	* consider using PHP built-in support and data
-	* formatting: number and date
-	* parsing??
-	* make dates/date patterns uniform application-wide including JUI, formats etc.
-- helpers
-	* image
-	* string
-	* file
-- web: TBD
-	* get/setFlash() should be moved to session component
-	* support optional parameter in URL patterns
-	* Response object.
-	* ErrorAction
-- gii
-    * move generation API out of gii, provide yiic commands to use it. Use same templates for gii/yiic.
-	* i18n variant of templates
-	* allow to generate module-specific CRUD
-- assets
-    * ability to manage scripts order (store these in a vector?)
-	* http://ryanbigg.com/guides/asset_pipeline.html, http://guides.rubyonrails.org/asset_pipeline.html, use content hash instead of mtime + directory hash.
-- Requirement checker
-- Optional configurable input filtering in request
-- widgets
-    * if we're going to supply default ones, these should generate really unique IDs. This will solve a lot of AJAX-nesting problems.
-- Make sure type hinting is used when components are passed to methods
-- Decouple controller from application (by passing web application instance to controller and if not passed, using Yii::app())?