Finished the initial draft of upgrading instructions

12 years ago · 36d452ae16
2 changed files with 308 additions and 14 deletions
--- a/docs/guide/upgrade-from-v1.md
+++ b/docs/guide/upgrade-from-v1.md
@ -22,30 +22,36 @@ data structures.
 Object Configuration
 --------------------
-The `Object` class introduces a convention for configuring objects. In general, any
+The `Object` class introduces a uniform way of configuring objects. Any descendant class
-descendant class of `Object` should follow this convention when declaring a constructor:
+of `Object` should declare its constructor (if needed) in the following way so that
 it can be properly configured:
 ~~~
 class MyClass extends \yii\Object
 {
    public function __construct($param1, $param2, $config = array())
    {
-        // ...
+        // ... initialization before configuration is applied
        parent::__construct($config);
    }
    public function init()
    {
        parent::init();
-        // ... at this point, all configurations have been applied ...
+
        // ... initialization after configuration is applied
    }
 }
 ~~~
-In descendant classes, you can override the `init()` method to do initialization work
+In the above, the last parameter of the constructor must take a configuration array
-that should be done after all configurations are applied.
+which contains name-value pairs for initializing the properties at the end of the constructor.
 You can override the `init()` method to do initialization work that should be done after
 the configuration is applied.
-By following this convention, you will be able to use the powerful object creation method via:
+By following this convention, you will be able to create and configure a new object
 using a configuration array like the following:
 ~~~
 $object = Yii::createObject(array(
@ -87,6 +93,23 @@ Yii::$app->trigger($eventName);
 ~~~
 Path Alias
 ----------
 Yii 2.0 expands the usage of path aliases to both file/directory paths and URLs. An alias
 must start with a `@` character so that it can be differentiated from file/directory paths and URLs.
 For example, the alias `@yii` refers to the Yii installation directory. Path aliases are
 supported in most places in the Yii core code. For example, `FileCache::cachePath` can take
 both a path alias and a normal directory path.
 Path alias is also closely related with class namespaces. It is recommended that a path
 alias defined for each root namespace so that you can use Yii class autoloader without
 any further configuration. For example, because `@yii` refers to the Yii installation directory,
 a class like `yii\web\Request` can be autoloaded by Yii. If you use a third party library
 such as Zend Framework, you may define a path alias `@Zend` which refers to its installation directory.
 And Yii will be able to autoload any class in this library.
 View
 ----
@ -111,53 +134,313 @@ $content = Yii::$app->view->renderFile($viewFile, $params);
 Also, there is no more `CClientScript` in Yii 2.0. The `View` class has taken over its role
 with significant improvements. For more details, please see the "assets" subsection.
-TBD: built-in renderers
+While Yii 2.0 continues to use PHP as its main template language, it comes with built-in
 support for two popular template engines: Smarty and Twig. The Prado template engine is
 no longer supported. To use these template engines, simply configure the "view" application 
 component as follows,
 ~~~
 'view' => array(
    'renders' => array(
        array(
            'tpl' => array(
                'class' => 'yii\renderers\SmartyRenderer',
            ),
            'twig' => array(
                'class' => 'yii\renderers\TwigRenderer',
            ),
        )
    ),
 )
 ~~~
 Models
 ------
 A model is now associated with a form name returned its `formName()` method. This is
 mainly used when using HTML forms to collect user inputs for a model. Previously in 1.1,
 this is usually hardcoded as the class name of the model.
 Yii 2.0 introduces a new method called `scenarios()` to declare which attributes require
 validation under which scenario. Child classes should overwrite `scenarios()` to return
 a list of scenarios and the corresponding attributes that need to be validated when
 `validate()` is called. For example,
 ~~~
 public function scenarios()
 {
    return array(
        'backend' => array('email', 'role'),
        'frontend' => array('email', '!name'),
    );
 }
 ~~~
 This method also determines which attributes are safe and which are not. In particular,
 given a scenario, if an attribute appears in the corresponding attribute list in `scenarios()`
 and the name is not prefixed with `!`, it is considered *safe*.
 Because of the above change, Yii 2.0 no longer has "safe" and "unsafe" validators.
 If your model only has one scenario (very common), you do not have to overwrite `scenarios()`,
 and everything will still work like the 1.1 way.
 Controllers
 -----------
 The `render()` and `renderPartial()` methods now return the rendering results instead of directly
 sending them out. You have to `echo` them explicitly, e.g., `echo $this->render(...);`.
 A new method called `populate()` is introduced to simplify the data population from user inputs
 to a model. For example,
 ~~~
 $post = new Post;
 if ($this->populate($_POST, $model)) {...}
 // which is equivalent to:
 if (isset($_POST['Post'])) {
    $post->attributes = $_POST['Post'];
 }
 ~~~
 Themes
 ------
 Theme works completely different in 2.0. It is now based on a path map to "translate" a source
 view into a themed view. For example, if the path map for a theme is
 `array('/www/views' => '/www/themes/basic')`, then the themed version for a view file
 `/www/views/site/index.php` will be `/www/themes/basic/site/index.php`.
 For this reason, theme can now be applied to any view file, even if a view rendered outside
 of the context of a controller or a widget.
 There is no more `CThemeManager`. Instead, `theme` is a configurable property of the "view"
 application component.
 Console Applications
 --------------------
 Console applications are now composed by controllers, too, like Web applications. In fact,
 console controllers and Web controllers share the same base controller class.
 Each console controller is like `CConsoleCommand` in 1.1. It consists of one or several
 actions. You use the `yiic <route>` command to execute a console command, where `<route>`
 stands for a controller route (e.g. `sitemap/index`). Additional anonymous arguments
 are passed as the parameters to the corresponding controller action method, and named arguments
 are treated as global options declared in `globalOptions()`.
 Yii 2.0 supports automatic generation of command help information from comment blocks.
 I18N
 ----
-Behaviors
+Yii 2.0 removes date formatter and number formatter in favor of the PECL intl PHP module.
 ---------
-TBD
+Message translation is still supported, but managed via the "i18n" application component.
 The component manages a set of message sources, which allows you to use different message
 sources based on message categories. For more information, see the class documentation for `I18N`.
 The message translation method is changed by merging the message category into the message being
 translated. For example, `Yii::t('yii|message to be translated')`.
-Action filters are replaced by behaviors (`ActiionFilter`).
+
 Action Filters
 --------------
 Action filters are implemented via behaviors now. You should extend from `ActionFilter` to
 define a new filter. To use a filter, you should attach the filter class to the controller
 as a behavior. For example, to use the `AccessControl` filter, you should have the following
 code in a controller:
 ~~~
 public function behaviors()
 {
    return array(
        'access' => array(
            'class' => 'yii\web\AccessControl',
            'rules' => array(
                array('allow' => true, 'actions' => array('admin'), 'roles' => array('@')),
                array('allow' => false),
            ),
        ),
    );
 }
 ~~~
 Assets
 ------
 Yii 2.0 introduces a new concept called *asset bundle*. It is a bit similar to script
 packages (managed by `CClientScript`) in 1.1, but with better support.
 An asset bundle is a collection of asset files (e.g. JavaScript files, CSS files, image files, etc.)
 under a directory. By registering an asset bundle via `View::registerAssetBundle()`, you
 will be able to make the assets in that bundle accessible via Web, and the current page
 will automatically contain references to the JavaScript and CSS files in that bundle.
 Static Helpers
 --------------
 Yii 2.0 introduces many commonly used static helper classes, such as `Html`, `ArrayHelper`,
 `StringHelper`. These classes are designed to be easily extended. Note that static classes
 are usually hard to be extended because of the fixed class name references. But Yii 2.0
 introduces the class map (via `Yii::$classMap`) to overcome this difficulty.
 `ActiveForm`
 ------------
 Yii 2.0 introduces the *field* concept for building a form using `ActiveForm`. A field
 is a container consisting of a label, an input, and an error message. It is represented
 as an `ActiveField` object. Using fields, you can build a form more cleanly than before:
 ~~~
 <?php $form = $this->beginWidget('yii\widgets\ActiveForm'); ?>
 	<?php echo $form->field($model, 'username')->textInput(); ?>
 	<?php echo $form->field($model, 'password')->passwordInput(); ?>
 	<div class="form-actions">
 		<?php echo Html::submitButton('Login'); ?>
 	</div>
 <?php $this->endWidget(); ?>
 ~~~
 Query Builder
 -------------
 In 1.1, query building is scattered among several classes, including `CDbCommand`,
 `CDbCriteria`, and `CDbCommandBuilder`. Yii 2.0 uses `Query` to represent a DB query
 and `QueryBuilder` to generate SQL statements from query objects. For example,
 ~~~
 $query = new \yii\db\Query;
 $query->select('id, name')
      ->from('tbl_user')
      ->limit(10);
 $command = $query->createCommand();
 $sql = $command->sql;
 $rows = $command->queryAll();
 ~~~
 Best of all, such query building methods can be used together with `ActiveRecord`,
 as explained in the next sub-section.
 ActiveRecord
 ------------
 ActiveRecord has undergone significant changes in Yii 2.0. The most important one
 is about relational ActiveRecord query. In 1.1, you have to declare the relations
 in the `relations()` method. In 2.0, this is done via getter methods that return
 an `ActiveQuery` object. For example, the following method declares an "orders" relation:
 ~~~
 class Customer extends \yii\db\ActiveRecord
 {
 	public function getOrders()
 	{
 		return $this->hasMany('Order', array('customer_id' => 'id'));
 	}
 }
 ~~~
 You can use `$customer->orders` to access the customer's orders. You can also
 use `$customer->getOrders()->andWhere('status=1')->all()` to perform on-the-fly
 relational query with customized query conditions.
 When loading relational records in an eager way, Yii 2.0 does it differently from 1.1.
 In particular, in 1.1 a JOIN query would be used to bring both the primary and the relational
 records; while in 2.0, two SQL statements are executed without using JOIN: the first
 statement brings back the primary records and the second brings back the relational records
 by filtering with the primary keys of the primary records.
 Yii 2.0 no longer uses the `model()` method when performing queries. Instead, you
 use the `find()` method like the following:
 ~~~
 // to retrieve all *active* customers and order them by their ID:
 $customers = Customer::find()
 	->where(array('status' => $active))
 	->orderBy('id')
 	->all();
 // return the customer whose PK is 1
 $customer = Customer::find(1);
 ~~~
 The `find()` method returns an instance of `ActiveQuery` which is a subclass of `Query`.
 Therefore, you can use all query methods of `Query`.
 Instead of returning ActiveRecord objects, you may call `ActiveQuery::asArray()` to
 return results in terms of arrays. This is more efficient and is especially useful
 when you need to return large number of records. For example,
 ~~~
 $customers = Customer::find()->asArray()->all();
 ~~~
 Auto-quoting Table and Column Names
 ------------------------------------
 Yii 2.0 supports automatic quoting of database table and column names. A name enclosed
 within double curly brackets is treated as a table name, and a name enclosed within
 double square brackets is treated as a column name. They will be quoted according to
 the database driver being used. For example,
 ~~~
 $command = $connection->createCommand('SELECT [[id]] FROM {{posts}}');
 echo $command->sql;  // MySQL: SELECT `id` FROM `posts`
 ~~~
 This feature is especially useful if you are developing an application that supports
 different DBMS.
 User and Identity
 -----------------
 The `CWebUser` class in 1.1 is now replaced by `\yii\Web\User`, and there is no more
 `CUserIdentity` class. Instead, you should implement the `Identity` interface which
 is much more straightforward to implement. The bootstrap application provides such an example.
 URL Management
 --------------
 URL management is similar to 1.1. A major enhancement is that it now supports optional
 parameters. For example, if you have rule declared as follows, then it will match
 both `post/popular` and `post/1/popular`. In 1.1, you would have to use two rules to achieve
 the same goal.
 ~~~
 array(
 	'pattern' => 'post/<page:\d+>/<tag>',
 	'route' => 'post/index',
 	'defaults' => array('page' => 1),
 )
 ~~~
 Response
--------
+--------
 Extensions
 ----------
 Integration with Composer
 -------------------------
 TBD
--- a/readme.md
+++ b/readme.md
@ -27,10 +27,21 @@ REQUIREMENTS
 The minimum requirement by Yii is that your Web server supports PHP 5.3.?.
 DOCUMENTATION
 -------------
 For 1.1 users, you may refer to [Upgrading from Yii 1.1](docs/guide/upgrade-from-v1.md)
 to have a general idea of what has changed in 2.0.
 We are writing more documentation to get you started and learn more in depth.
 HOW TO PARTICIPATE
 ------------------
-You are welcome to participate in Yii 2 development in the following ways:
+**Your participation to Yii 2 development is very welcome!**
 You may participate in the following ways:
 * [Report issues](https://github.com/yiisoft/yii2/issues)
 * [Give us feedback or start a design discussion](http://www.yiiframework.com/forum/index.php/forum/42-design-discussions-for-yii-20/)