From 36d452ae167f0aa1a798e4049ad8cc216ca79f19 Mon Sep 17 00:00:00 2001 From: Qiang Xue Date: Mon, 6 May 2013 19:20:20 -0400 Subject: [PATCH] Finished the initial draft of upgrading instructions --- docs/guide/upgrade-from-v1.md | 309 ++++++++++++++++++++++++++++++++++++++++-- readme.md | 13 +- 2 files changed, 308 insertions(+), 14 deletions(-) diff --git a/docs/guide/upgrade-from-v1.md b/docs/guide/upgrade-from-v1.md index af3c9ca..1aab3d1 100644 --- 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 -descendant class of `Object` should follow this convention when declaring a constructor: +The `Object` class introduces a uniform way of configuring objects. Any descendant class +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 -that should be done after all configurations are applied. +In the above, the last parameter of the constructor must take a configuration array +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 ` command to execute a console command, where `` +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: + +~~~ +beginWidget('yii\widgets\ActiveForm'); ?> + field($model, 'username')->textInput(); ?> + field($model, 'password')->passwordInput(); ?> +
+ +
+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//', + 'route' => 'post/index', + 'defaults' => array('page' => 1), +) +~~~ + + Response --------- \ No newline at end of file +-------- + +Extensions +---------- + +Integration with Composer +------------------------- + +TBD + diff --git a/readme.md b/readme.md index f395e95..178acd4 100644 --- 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/)