From 328b7fbac9db37062ef12b65937f59ccde8f9f50 Mon Sep 17 00:00:00 2001 From: Kevin LEVRON Date: Thu, 12 Jun 2014 17:09:16 +0200 Subject: [PATCH] French intro-upgrade-from-v1 (wip) [skip ci] --- docs/guide-fr/intro-upgrade-from-v1.md | 504 +++++++++++++++++++++++++ 1 file changed, 504 insertions(+) create mode 100644 docs/guide-fr/intro-upgrade-from-v1.md diff --git a/docs/guide-fr/intro-upgrade-from-v1.md b/docs/guide-fr/intro-upgrade-from-v1.md new file mode 100644 index 0000000000..82d424c5f5 --- /dev/null +++ b/docs/guide-fr/intro-upgrade-from-v1.md @@ -0,0 +1,504 @@ +Mise à jour depuis la version 1.1 +================================= + +Il y a beaucoup de différences entre les versions 1.1 et 2.0 de Yii, le framework ayant été complètement réécrit pour la 2.0. +En conséquence, la mise à jour depuis la version 1.1 n'est pas aussi simple que la mise à jour entre deux versions mineures. Dans ce guide, vous +trouverez les principales différences entre les deux versions. + +Si vous n'avez pas utilisé Yii 1.1 avant, vous pouvez ignorer cette section et passer directement à la partie "[Mise en route] (start-installation.md)". + +Merci de noter que Yii 2.0 introduit plus de nouvelles fonctionnalités que celles abordées ici. Il est fortement recommandé +de lire tout le guide de référence pour en apprendre davantage. Il y a des chances que +certaines fonctionnalités, que vous aviez préalablement développées pour vous, fassent désormais partie du code du noyau. + + +Installation +------------ + +Yii 2.0 exploite pleinement [Composer] (https://getcomposer.org/), le gestionnaire de paquet PHP. L'installation +du framework, ainsi que des extensions, sont gérées par Composer. Merci de lire la partie +[Starting from Basic App](start-basic.md) pour apprendre comment installer Yii 2.0. Si vous voulez +créer de nouvelles extensions, ou rendre vos extensions existantes 1.1 compatibles 2.0, merci de lire +la partie [Créer des extensions](extend-creating-extensions.md) de ce guide. + + +Pré-requis PHP +-------------- + +Yii 2.0 requiert PHP 5.4 ou plus, ce qui est une grosse amélioration par rapport à PHP 5.2 qui était requis pour Yii 1.1. + +Par conséquent, il y a beaucoup de différences au niveau du langage pour lesquelles vous devriez prêter attention. +Voici un résumé des principaux changements concernant PHP: + +- [Espaces de noms](http://php.net/manual/fr/language.namespaces.php). +- [Fonctions anonymes](http://php.net/manual/fr/functions.anonymous.php). +- Syntaxe courte pour les tableaux : `[...elements...]` est utilisé au lieu de `array(...elements...)`. +- Syntaxe courte pour echo : ` 'MyClass', + 'property1' => 'abc', + 'property2' => 'cde', +], [$param1, $param2]); +``` + +More details about configurations can be found in the [Object Configurations](concept-configurations.md) section. + + +Events +------ + +In Yii 1, events were created by defining an `on`-method (e.g., `onBeforeSave`). In Yii 2, you can now use any event name. You trigger an event by calling +the [[yii\base\Component::trigger()|trigger()]] method: + +```php +$event = new \yii\base\Event; +$component->trigger($eventName, $event); +``` + +To attach a handler to an event, use the [[yii\base\Component::on()|on()]] method: + +```php +$component->on($eventName, $handler); +// To detach the handler, use: +// $component->off($eventName, $handler); +``` + +There are many enhancements to the event features. For more details, please refer to the [Events](concept-events.md) section. + + +Path Aliases +------------ + +Yii 2.0 expands the usage of path aliases to both file/directory paths and URLs. Yii 2.0 also now requires +an alias name to start with the `@` character, to differentiate aliases from normal file/directory paths or 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, [[yii\caching\FileCache::cachePath]] can take +both a path alias and a normal directory path. + +A path alias is also closely related to a class namespace. It is recommended that a path +alias be defined for each root namespace, thereby allowing you to use Yii the 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. If you use a third party library, +such as the Zend Framework, you may define a path alias `@Zend` that refers to that framework's installation +directory. Once you've done that, Yii will be able to autoload any class in that Zend Framework library, too. + +More on path aliases can be found in the [Path Aliases](concept-aliases.md) section. + + +Views +----- + +The most significant change about views in Yii 2 is that the special variable `$this` in a view no longer refers to +the current controller or widget. Instead, `$this` now refers to a *view* object, a new concept +introduced in 2.0. The *view* object is of type [[yii\web\View]], which represents the view part +of the MVC pattern. If you want to access the controller or widget in a view, you can use `$this->context`. + +To render a partial view within another view, you use `$this->render()`, not `$this->renderPartial()`. The call to `render` also now has to be explicitly echoed, as the `render()` method returns the rendering +result, rather than directly displaying it. For example: + +```php +echo $this->render('_item', ['item' => $item]); +``` + +Besides using PHP as the primary template language, Yii 2.0 is also equipped with official +support for two popular template engines: Smarty and Twig. The Prado template engine is no longer supported. +To use these template engines, you need to configure the `view` application component by setting the +[[yii\base\View::$renderers|View::$renderers]] property. Please refer to the [Template Engines](tutorial-template-engines.md) +section for more details. + + +Models +------ + +Yii 2.0 uses [[yii\base\Model]] as the base model, similar to `CModel` in 1.1. +The class `CFormModel` has been dropped entirely. Instead, in Yii 2 you should extend [[yii\base\Model]] to create a form model class. + +Yii 2.0 introduces a new method called [[yii\base\Model::scenarios()|scenarios()]] to declare +supported scenarios, and to indicate under which scenario an attribute needs to be validated, can be considered as safe or not, etc. For example: + +```php +public function scenarios() +{ + return [ + 'backend' => ['email', 'role'], + 'frontend' => ['email', '!name'], + ]; +} +``` + +In the above, two scenarios are declared: `backend` and `frontend`. For the `backend` scenario, both the +`email` and `role` attributes are safe, and can be massively assigned. For the `frontend` scenario, +`email` can be massively assigned while `role` cannot. Both `email` and `role` should be validated using rules. + +The [[yii\base\Model::rules()|rules()]] method is still used to declare the validation rules. Note that due to the introduction of [[yii\base\Model::scenarios()|scenarios()]], there is no longer an `unsafe` validator. + +In most cases, you do not need to override [[yii\base\Model::scenarios()|scenarios()]] +if the [[yii\base\Model::rules()|rules()]] method fully specifies the scenarios that will exist, and if there is no need to declare +`unsafe` attributes. + +To learn more details about models, please refer to the [Models](basic-models.md) section. + + +Controllers +----------- + +Yii 2.0 uses [[yii\web\Controller]] as the base controller class, similar to `CWebController` in Yii 1.1. +[[yii\base\Action]] is the base class for action classes. + +The most obvious impact of these changes on your code is that a controller action should return the content +that you want to render instead of echoing it: + +```php +public function actionView($id) +{ + $model = \app\models\Post::findOne($id); + if ($model) { + return $this->render('view', ['model' => $model]); + } else { + throw new \yii\web\NotFoundHttpException; + } +} +``` + +Please refer to the [Controllers](structure-controllers.md) section for more details about controllers. + + +Widgets +------- + +Yii 2.0 uses [[yii\base\Widget]] as the base widget class, similar to `CWidget` in Yii 1.1. + +To get better support for the framework in IDEs, Yii 2.0 introduces a new syntax for using widgets. The static methods +[[yii\base\Widget::begin()|begin()]], [[yii\base\Widget::end()|end()]], and [[yii\base\Widget::widget()|widget()]] +have been introduced, to be used like so: + +```php +use yii\widgets\Menu; +use yii\widgets\ActiveForm; + +// Note that you have to "echo" the result to display it +echo Menu::widget(['items' => $items]); + +// Passing an array to initialize the object properties +$form = ActiveForm::begin([ + 'options' => ['class' => 'form-horizontal'], + 'fieldConfig' => ['inputOptions' => ['class' => 'input-xlarge']], +]); +... form input fields here ... +ActiveForm::end(); +``` + +Please refer to the [Widgets](structure-widgets.md) section for more details. + + +Themes +------ + +Themes work completely differently in 2.0. They are now based on a path mapping mechanism that maps a source +view file path to a themed view file path. For example, if the path map for a theme is +`['/web/views' => '/web/themes/basic']`, then the themed version for the view file +`/web/views/site/index.php` will be `/web/themes/basic/site/index.php`. For this reason, themes can now +be applied to any view file, even a view rendered outside of the context of a controller or a widget. + +Also, there is no more `CThemeManager` component. Instead, `theme` is a configurable property of the `view` +application component. + +Please refer to the [Theming](tutorial-theming.md) section for more details. + + +Console Applications +-------------------- + +Console applications are now organized as controllers, like Web applications. Console controllers +should extend from [[yii\console\Controller]], similar to `CConsoleCommand` in 1.1. + +To run a console command, use `yii `, where `` stands for a controller route +(e.g. `sitemap/index`). Additional anonymous arguments are passed as the parameters to the +corresponding controller action method, while named arguments are parsed according to +the declarations in [[yii\console\Controller::options()]]. + +Yii 2.0 supports automatic generation of command help information from comment blocks. + +Please refer to the [Console Commands](tutorial-console.md) section for more details. + + +I18N +---- + +Yii 2.0 removes the built-in date formatter and number formatter pieces in favor of the [PECL intl PHP module](http://pecl.php.net/package/intl). + +Message translation is now performed via the `i18n` application component. +This component manages a set of message sources, which allows you to use different message +sources based on message categories. + +Please refer to the [Internationalization](tutorial-i18n.md) section for more details. + + +Action Filters +-------------- + +Action filters are implemented via behaviors now. To define a new, custom filter, extend from [[yii\base\ActionFilter]]. To use a filter, attach the filter class to the controller +as a behavior. For example, to use the [[yii\filters\AccessControl]] filter, you would have the following +code in a controller: + +```php +public function behaviors() +{ + return [ + 'access' => [ + 'class' => 'yii\filters\AccessControl', + 'rules' => [ + ['allow' => true, 'actions' => ['admin'], 'roles' => ['@']], + ], + ], + ]; +} +``` + +Please refer to the [Filtering](runtime-filtering.md) section for more details. + + +Assets +------ + +Yii 2.0 introduces a new concept called *asset bundle* that replaces the script package concept found in Yii 1.1. + +An asset bundle is a collection of asset files (e.g. JavaScript files, CSS files, image files, etc.) +within a directory. Each asset bundle is represented as a class extending [[yii\web\AssetBundle]]. +By registering an asset bundle via [[yii\web\AssetBundle::register()]], you make +the assets in that bundle accessible via the Web. Unlike in Yii 1, the page registering the bundle will automatically +contain the references to the JavaScript and CSS files specified in that bundle. + +Please refer to the [Managing Assets](output-assets.md) section for more details. + + +Helpers +------- + +Yii 2.0 introduces many commonly used static helper classes, including. + +* [[yii\helpers\Html]] +* [[yii\helpers\ArrayHelper]] +* [[yii\helpers\StringHelper]] +* [[yii\helpers\FileHelper]] +* [[yii\helpers\Json]] +* [[yii\helpers\Security]] + +Please refer to the [Helper Overview](helper-overview.md) section for more details. + +Forms +----- + +Yii 2.0 introduces the *field* concept for building a form using [[yii\widgets\ActiveForm]]. A field +is a container consisting of a label, an input, an error message, and/or a hint text. +A field is represented as an [[yii\widgets\ActiveField|ActiveField]] object. +Using fields, you can build a form more cleanly than before: + +```php + + field($model, 'username') ?> + field($model, 'password')->passwordInput() ?> +
+ +
+ +``` + +Please refer to the [Creating Forms](input-forms.md) section for more details. + + +Query Builder +------------- + +In 1.1, query building was scattered among several classes, including `CDbCommand`, +`CDbCriteria`, and `CDbCommandBuilder`. Yii 2.0 represents a DB query in terms of a [[yii\db\Query|Query]] object +that can be turned into a SQL statement with the help of [[yii\db\QueryBuilder|QueryBuilder]] behind the scene. +For example: + +```php +$query = new \yii\db\Query(); +$query->select('id, name') + ->from('user') + ->limit(10); + +$command = $query->createCommand(); +$sql = $command->sql; +$rows = $command->queryAll(); +``` + +Best of all, such query building methods can also be used when working with [Active Record](db-active-record.md). + +Please refer to the [Query Builder](db-query-builder.md) section for more details. + + +Active Record +------------- + +Yii 2.0 introduces a lot of changes to [Active Record](db-active-record.md). The two most obvious ones involve +query building and relational query handling. + +The `CDbCriteria` class in 1.1 is replaced by [[yii\db\ActiveQuery]] in Yii 2. That class extends from [[yii\db\Query]], and thus +inherits all query building methods. You call [[yii\db\ActiveRecord::find()]] to start building a query: + +```php +// To retrieve all *active* customers and order them by their ID: +$customers = Customer::find() + ->where(['status' => $active]) + ->orderBy('id') + ->all(); +``` + +To declare a relation, simply define a getter method that returns an [[yii\db\ActiveQuery|ActiveQuery]] object. +The property name defined by the getter represents the relation name. For example, the following code declares +an `orders` relation (in 1.1, you would have to declare relations in a central place `relations()`): + +```php +class Customer extends \yii\db\ActiveRecord +{ + public function getOrders() + { + return $this->hasMany('Order', ['customer_id' => 'id']); + } +} +``` + +Now you can use `$customer->orders` to access a customer's orders from the related table. You can also use the following code +to perform an on-the-fly relational query with a customized query condition: + +```php +$orders = $customer->getOrders()->andWhere('status=1')->all(); +``` + +When eager loading a relation, Yii 2.0 does it differently from 1.1. In particular, in 1.1 a JOIN query +would be created to select both the primary and the relational records. In Yii 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. + +Instead of returning [[yii\db\ActiveRecord|ActiveRecord]] objects, you may chain the [[yii\db\ActiveQuery::asArray()|asArray()]] +method when building a query to return a large number of records. This will cause the query result to be returned +as arrays, which can significantly reduce the needed CPU time and memory if large number of records . For example, + +```php +$customers = Customer::find()->asArray()->all(); +``` + +Another change is that you can't define attribute default values through public properties anymore. +If you need those, you should set them in the init method of your record class. + +```php +public function init() +{ + parent::init(); + $this->status = self::STATUS_NEW; +} +``` + +There where some problems with overriding the constructor of an ActiveRecord class in 1.1. These are not present in +version 2.0 anymore. Note that when adding parameters to the constructor you might have to override [[yii\db\ActiveRecord::instantiate()]]. + +There are many other changes and enhancements to Active Record. Please refer to +the [Active Record](db-active-record.md) section for more details. + + +User and IdentityInterface +-------------------------- + +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 [[yii\web\IdentityInterface]] which +is much more straightforward to use. The advanced application template provides such an example. + +Please refer to the [Authentication](security-authentication.md), [Authorization](security-authorization.md), and [Advanced Application Technique](tutorial-advanced-app.md) sections for more details. + + +URL Management +-------------- + +URL management in Yii 2 is similar to that in 1.1. A major enhancement is that URL management now supports optional +parameters. For example, if you have a rule declared as follows, then it will match +both `post/popular` and `post/1/popular`. In 1.1, you would have had to use two rules to achieve +the same goal. + +```php +[ + 'pattern' => 'post//', + 'route' => 'post/index', + 'defaults' => ['page' => 1], +] +``` + +Please refer to the [Url manager docs](url.md) section for more details. + +Using Yii 1.1 and 2.x together +------------------------------ + +If you have legacy Yii 1.1 code that you want to use together with Yii 2.0, please refer to +the [Using Yii 1.1 and 2.0 Together](extend-using-v1-v2.md) section. +