From 05d5962cfa3a3b6888c42a59e6cdcc43dbf78419 Mon Sep 17 00:00:00 2001 From: Qiang Xue Date: Fri, 3 May 2013 20:58:49 -0400 Subject: [PATCH] guide wip --- docs/guide/application.md | 0 docs/guide/bootstrap.md | 63 +++++++++++++++++++++++++ docs/guide/controller.md | 0 docs/guide/index.md | 30 ++++++++++++ docs/guide/installation.md | 111 +++++++++++++++++++++++++++++++++++++++++++++ docs/guide/model.md | 0 docs/guide/mvc.md | 51 +++++++++++++++++++++ docs/guide/overview.md | 36 +++++++++++++++ docs/guide/title.md | 8 ++++ docs/guide/view.md | 0 todo.md | 49 -------------------- 11 files changed, 299 insertions(+), 49 deletions(-) create mode 100644 docs/guide/application.md create mode 100644 docs/guide/bootstrap.md create mode 100644 docs/guide/controller.md create mode 100644 docs/guide/index.md create mode 100644 docs/guide/installation.md create mode 100644 docs/guide/model.md create mode 100644 docs/guide/mvc.md create mode 100644 docs/guide/overview.md create mode 100644 docs/guide/title.md create mode 100644 docs/guide/view.md delete mode 100644 todo.md diff --git a/docs/guide/application.md b/docs/guide/application.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/guide/bootstrap.md b/docs/guide/bootstrap.md new file mode 100644 index 0000000..5f00a75 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/guide/controller.md b/docs/guide/controller.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/guide/index.md b/docs/guide/index.md new file mode 100644 index 0000000..6ad733c --- /dev/null +++ b/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) diff --git a/docs/guide/installation.md b/docs/guide/installation.md new file mode 100644 index 0000000..6cc5ef8 --- /dev/null +++ b/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. diff --git a/docs/guide/model.md b/docs/guide/model.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/guide/mvc.md b/docs/guide/mvc.md new file mode 100644 index 0000000..79140ce --- /dev/null +++ b/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. diff --git a/docs/guide/overview.md b/docs/guide/overview.md new file mode 100644 index 0000000..9e54fd4 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/guide/title.md b/docs/guide/title.md new file mode 100644 index 0000000..a3e55a1 --- /dev/null +++ b/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. diff --git a/docs/guide/view.md b/docs/guide/view.md new file mode 100644 index 0000000..e69de29 diff --git a/todo.md b/todo.md deleted file mode 100644 index f66d3c1..0000000 --- a/todo.md +++ /dev/null @@ -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())?