Development

/tags/RELEASE_1_1_5/UPGRADE

You must first sign up to be able to contribute.

root/tags/RELEASE_1_1_5/UPGRADE

Revision 11147, 21.4 kB (checked in by fabien, 6 years ago)

[1.1, 1.2] fixed Markdown for UPGRADE files

Line 
1 Upgrade from 1.0 to 1.1
2 =======================
3
4 This document describes the changes made in symfony 1.1 and what need
5 to be done to upgrade your symfony 1.0 projects.
6
7 WARNING: symfony 1.1 is only compatible with PHP > 5.1.
8
9 How to upgrade?
10 ---------------
11
12 To upgrade a project:
13
14   * If you don't use a SCM tool, please make a backup of your project.
15     As symfony replaces some files during the upgrade
16     (front controllers for example), you need a way to merge your
17     customizations after the upgrade.
18
19   * Update the `symfony` file located in the project root directory
20     by changing those three lines:
21
22         [php]
23         chdir(dirname(__FILE__));
24         include('config/config.php');
25         include($sf_symfony_data_dir.'/bin/symfony.php');
26
27     to
28
29         [php]
30         chdir(dirname(__FILE__));
31         require_once(dirname(__FILE__).'/config/ProjectConfiguration.class.php');
32         $configuration = new ProjectConfiguration();
33         include($configuration->getSymfonyLibDir().'/command/cli.php');
34
35     You can also copy the skeleton file from the symfony project skeleton directly:
36
37         $ cp /path/to/symfony/lib/task/generator/skeleton/project/symfony symfony
38
39   * Create a `config/ProjectConfiguration.class.php` file with the following content:
40
41         [php]
42         <?php
43
44         require_once '##SYMFONY_LIB_DIR##/autoload/sfCoreAutoload.class.php';
45         sfCoreAutoload::register();
46
47         class ProjectConfiguration extends sfProjectConfiguration
48         {
49           public function setup()
50           {
51           }
52         }
53
54     Then, replace `##SYMFONY_LIB_DIR##` with the path to the symfony 1.1
55     `lib/` directory. This is the new way to change the symfony version used
56     for your project.
57
58     You can also copy the skeleton file from the symfony project skeleton directly:
59
60         $ cp /path/to/symfony/lib/task/generator/skeleton/project/config/ProjectConfiguration.class.php config/ProjectConfiguration.class.php
61
62   * Launch the `project:upgrade1.1` task from your project directory
63     to perform an automatic upgrade:
64
65         $ ./symfony project:upgrade1.1
66
67     This task can be launched several times without any side effect. Each time
68     you upgrade to a new symfony 1.1 beta / RC or the final symfony 1.1, you
69     need to launch this task.
70
71   * If you don't plan to upgrade the validation or mailing system to
72     the new system, you must enable the compatibility mode in `settings.yml`:
73
74         [yml]
75         all:
76           .settings:
77             compat_10: on
78
79     Here is a list of the things that will be enabled when switching to the
80     compatibility mode (see the bundled `sfCompat10Plugin` plugin for
81     more information):
82
83       * Zend Framework and ezComponents bridges
84       * sfProcessCache
85       * validation system (validate.yml, validator classes, ...)
86       * fill in filter
87       * sfMail with phpmailer
88
89 The remaining sections explains backward incompatible changes.
90
91 Batch scripts
92 -------------
93
94 The use of batch scripts is deprecated, in favor of custom CLI tasks. The new CLI system makes it easy to add a new symfony command to a project, so refer to the Chapter 16 of the symfony book for a detailed how-to on CLI tasks.
95
96 If you just want your old batch scripts to work, you need to change the first lines of the every batch scripts--the lines that look like a front controller's initialization. So change the following:
97
98     [php]
99     <?php
100     define('SF_ROOT_DIR',    realpath(dirname(__FILE__).'/..'));
101     define('SF_APP',         'frontend');
102     define('SF_ENVIRONMENT', 'prod');
103     define('SF_DEBUG',       false);
104
105       require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php');
106     // your batch code here
107
108 To:
109
110     [php]
111     <?php
112     require_once(dirname(__FILE__).'/../config/ProjectConfiguration.class.php');
113     $configuration = ProjectConfiguration::getApplicationConfiguration('frontend', 'prod', false);
114     sfContext::createInstance($configuration);
115
116     // your batch code here
117
118 If you need to initialize the database connection, just add the following lines:
119
120     [php]
121     $databaseManager = new sfDatabaseManager($configuration);
122     $databaseManager->loadConfiguration();
123
124 Flash attributes
125 ----------------
126
127 Flash attributes are now managed directly by `sfUser`. New usage:
128
129     [php]
130     // action
131     $this->getUser()->setFlash('notice', 'foo');
132     $notice = $this->getUser()->getFlash('notice');
133
134     // template
135     <?php $sf_user->hasFlash('notice'): ?>
136       <?php echo $sf_user->getFlash('notice') ?>
137     <?php endif; ?>
138
139 The `flash` entry in `filters.yml` must be removed too as the `sfFlashFilter`
140 was removed.
141
142 The `project:upgrade1.1` task makes all those changes for you.
143
144 Deprecated methods in sfComponent
145 ---------------------------------
146
147 The following methods of `sfComponent` have been removed:
148
149   * `->getPresentationFor()`
150   * `->sendEmail()`
151
152 They are accessible from `sfController`:
153
154     [php]
155     // action
156     $this->getController()->getPresentationFor(...);
157
158 The `project:upgrade1.1` task makes all those changes for you.
159
160 Singletons
161 ----------
162
163 The sfI18N, sfRouting, and sfLogger objects are now factories and
164 not singletons.
165
166 If you want to get one of those objects in your code, they are
167 available from `sfContext`:
168
169     [php]
170     sfContext::getInstance()->getI18N()
171     sfContext::getInstance()->getRouting()
172     sfContext::getInstance()->getLogger()
173
174 ### Routing
175
176 Here is the default configuration for the routing in `factories.yml`:
177
178     [yml]
179     routing:
180       class: sfPatternRouting
181       param:
182         load_configuration: true
183
184 The `project:upgrade1.1` task makes all the changes for you.
185
186 ### Logging
187
188 Here is the default configuration for logging in `factories.yml`:
189
190     [yml]
191     logger:
192       class: sfAggregateLogger
193       param:
194         level: debug
195         loggers:
196           sf_web_debug:
197             class: sfWebDebugLogger
198             param:
199               level: debug
200               condition: %SF_WEB_DEBUG%
201               xdebug_logging: true
202           sf_file_debug:
203             class: sfFileLogger
204             param:
205               level: debug
206               file: %SF_LOG_DIR%/%SF_APP%_%SF_ENVIRONMENT%.log
207
208 The `logging.yml` configuration file is not used anymore.
209 Instead, you can configure logging in `factories.yml`.
210
211 To disable logging in the production environment, you will have to change
212 your application `factories.yml`:
213
214     [yml]
215     prod:
216       logger:
217         class:   sfNoLogger
218         param:
219           level:   err
220           loggers: ~
221
222 There is also a new `logging_enabled` setting in `settings.yml`.
223 This can be used to prevent logging in the production environment altogether:
224
225     [yml]
226     prod:
227       .settings:
228         logging_enabled: off
229
230 The `project:upgrade1.1` task makes all those changes for you.
231
232 ### i18n
233
234 Here is the default configuration for i18n in `factories.yml`:
235
236     [yml]
237     i18n:
238       class: sfI18N
239       param:
240         source:              XLIFF
241         debug:               off
242         untranslated_prefix: "[T]"
243         untranslated_suffix: "[/T]"
244         cache:
245           class: sfFileCache
246           param:
247             automatic_cleaning_factor: 0
248             cache_dir:                 %SF_I18N_CACHE_DIR%
249             lifetime:                  86400
250             prefix:                    %SF_APP_DIR%
251
252 The `i18n.yml` configuration file is not used anymore.
253 Instead, you can configure i18n in `factories.yml`.
254
255 The only exception is the `default_culture` setting which is now configurable
256 in `settings.yml` and do not depend on the i18n framework anymore:
257
258   default_culture: en
259
260 If your project has some specific settings, you must move your current
261 configuration from the `i18n.yml` to the `factories.yml` and add the default
262 culture in `settings.yml` as shown above.
263
264 Cache Framework
265 ---------------
266
267 The `sfFunctionCache` class does not extend `sfFileCache` anymore.
268 You must now pass a cache object to the constructor.
269 The first argument to ->call() must now be a PHP callable.
270
271 Some `sfCache` configuration parameter have changed their named to underscore names:
272
273   * automaticCleaningFactor -> automatic_cleaning_factor
274   * cacheDir -> cache_dir
275
276 The `project:upgrade1.1` task makes all those changes for you.
277
278 Autoloading
279 -----------
280
281 The `autoloading_function` setting in `settings.yml` is not used anymore.
282 You can register autoloading callables in your application configuration class.
283
284 Thanks to the new `sfAutoload::autoloadAgain()` method, you won't need to clear
285 the cache when you add or move classes in your project. This method will
286 automatically find the changes and flush the autoloading cache.
287
288 VERSION
289 -------
290
291 The lib/VERSION file has been removed. If you want to get the current symfony
292 version, you can use the `SYMFONY_VERSION` constant. This constant is defined
293 in `autoload/sfCoreAutoload.class.php`
294
295 Routing
296 -------
297
298 To inject default route parameters, you can now use the `->setDefaultParameter()`
299 method instead of using the `sf_routing_defaults` setting:
300
301     [php]
302     $this->context->getRouting()->setDefaultParameter($key, $value);
303
304 I18N
305 ----
306
307 symfony core classes don't return internationalized strings anymore:
308
309     [php]
310     <?php echo __($sf_request->getError('foo')) ?>
311
312 This behavior has changed for the following methods and functions:
313
314     [php]
315     sfWebRequest::getError()
316     sfWebResponse::addMeta()
317
318 The following helpers (in sfCompat10Plugin) still return internationalized data:
319
320     [php]
321     form_error()
322     include_metas()
323
324 The `getGlobalMessageSource()` and `getGlobalMessageFormat()` methods has been
325 removed from the sfI18N class. They are now equivalent to `getMessageSource()`
326 and `getMessageFormat()`.
327
328 Logger
329 ------
330
331 Logger priorities are now constants:
332
333     [php]
334     sfLogger::INFO
335
336 The `project:upgrade1.1` task makes all those changes for you.
337
338 Deprecated methods in sfAction
339 ------------------------------
340
341 The following methods of `sfAction` have been deprecated and throw
342 a `sfConfigurationException` if `sf_compat_10` is set to `false`:
343
344   * `->validate()`
345   * `->handleError()`
346
347 Deprecated methods in sfRequest
348 -------------------------------
349
350 The following methods of `sfRequest` have been deprecated and throw
351 a `sfConfigurationException` if `sf_compat_10` is set to `false`:
352
353   * `->getError()`
354   * `->getErrors()`
355   * `->getErrorNames()`
356   * `->hasError()`
357   * `->hasErrors()`
358   * `->setError()`
359   * `->setErrors()`
360   * `->removeError()`
361
362 Deprecated methods in sfWebRequest
363 ----------------------------------
364
365 The following methods of `sfWebRequest` have been deprecated and throw
366 a `sfConfigurationException` if `sf_compat_10` is set to `false`:
367
368   * `->getFile()`
369   * `->getFileError()`
370   * `->getFileName()`
371   * `->getFileNames()`
372   * `->getFilePath()`
373   * `->getFileSize()`
374   * `->getFileType()`
375   * `->hasFile()`
376   * `->hasFileError()`
377   * `->hasFileErrors()`
378   * `->hasFiles()`
379   * `->getFileValue()`
380   * `->getFileValues()`
381   * `->getFileExtension()`
382   * `->moveFile()`
383
384 `->initialize()` methods
385 ------------------------
386
387 Most symfony core classes are initialized thanks to a `->initialize()` method.
388 As of symfony 1.1, this method is automatically called by `__construct()`,
389 so, there is no need to call it by yourself.
390
391 Configuration files loading
392 ---------------------------
393
394 Some core classes can be configured with a `.yml` file:
395
396  *Class*              | *Configuration file*
397  -------------------- | --------------------------------
398  `sfAction`           | `security.yml`
399  `sfAutoload`         | `autoload.yml`
400  `sfConfigCache`      | `config_handlers.yml`
401  `sfContext`          | `factories.yml`
402  `sfController`       | `generator.yml` and `module.yml`
403  `sfDatabaseManager`  | `databases.yml`
404  `sfFilterChain`      | `filters.yml`
405  `sfI18N`             | `i18n.yml`
406  `sfPatternRouting`   | `routing.yml`
407  `sfPHPView`          | `view.yml`
408  `sfViewCacheManager` | `cache.yml`
409
410 In symfony 1.1, the loading of the configuration file for ''independant''
411 sub-frameworks has been moved to a `loadConfiguration()` method to ease
412 decoupling and reuse them without needing the whole framework:
413
414   * `sfDatabaseManager`
415   * `sfI18N`
416   * `sfPatternRouting`
417
418 So, for example, if you need a database manager in your batch script,
419 you will have to change from:
420
421     [php]
422     $databaseManager = new sfDatabaseManager();
423     $databaseManager->initialize();
424
425 to:
426
427     [php]
428     $configuration = ProjectConfiguration::getApplicationConfiguration($application, $env, true);
429     $databaseManager = new sfDatabaseManager($configuration);
430     $databaseManager->loadConfiguration();
431
432 The `initialize()` call is not needed anymore (see the point above).
433
434 Web Debug
435 ---------
436
437 The `web_debug` entry in `filters.yml` must be removed as the `sfWebDebugFilter`
438 has been removed. The web debug toolbar is now injected in the response thanks
439 to a listener.
440
441 The `project:upgrade1.1` task makes all those changes for you.
442
443 Session timeout
444 ---------------
445
446 The `sf_timeout` setting is not used anymore. To change the session timeout,
447 you now have to edit `factories.yml` instead of the `settings.yml`,
448 and change the parameters of the `user` factory:
449
450     [yml]
451     all:
452       user:
453         class: myUser
454         param:
455           timeout:     1800     # session timeout in seconds
456
457 Routing configuration
458 ---------------------
459
460 The `sf_suffix`, `sf_default_module`, and `sf_default_action` settings are not
461 used anymore. To change the default suffix, module, or action, you now have
462 to edit `factories.yml` instead of `settings.yml`, and change the parameters
463 of the `routing` factory:
464
465     [yml]
466     all:
467       routing:
468         class: sfPatternRouting
469         param:
470           load_configuration: true
471           suffix:             .       # Default suffix for generated URLs. If set to a single dot (.), no suffix is added. Possible values: .html, .php, and so on.
472           default_module:     default # Default module and action to be called when
473           default_action:     index   # A routing rule doesn't set it
474
475 `php.yml` configuration file
476 ----------------------------
477
478 The `php.yml` configuration file has been removed.
479
480 The only setting you will have to check by hand is `log_errors`, which was set
481 to `on` by `php.yml`.
482
483 `php.yml` is replaced by the `check_configuration.php` utility you can find
484 in `data/bin`. It checks your environment against symfony requirements.
485 You can launch it from anywhere:
486
487     $ php /path/to/symfony/data/bin/check_configuration.php
488
489 Even if you can use this utility from the command line, it's strongly recommended
490 to launch it from the web by copying it under your web root directory as PHP can
491 use different php.ini configuration files for the CLI and the web.
492
493 `$sf_symfony_data_dir` removal
494 ------------------------------
495
496 In symfony 1.1, `$sf_symfony_data_dir` has been removed. All relevant files and
497 directories from the symfony `data` directory have been moved to the `lib`
498 directory:
499
500  *Old Location*         | *New Location*
501  ---------------------- | -----------------------------
502  `data/config`          | `lib/config/config`
503  `data/i18n`            | `lib/i18n/data`
504  `data/skeleton`        | `lib/task/generator/skeleton`
505  `data/modules/default` | `lib/controller/default`
506  `data/web/errors`      | `lib/exception/data`
507  `data/exception.*`     | `lib/exception/data`
508
509 The symfony core has been upgraded to take these changes into account.
510
511 sfLoader
512 --------
513
514 All `sfLoader` static methods (except `::getHelperDirs()` and `::loadHelpers()`)
515 have been moved to the `sfProjectConfiguration` and `sfApplicationConfiguration`
516 classes:
517
518   * `sfProjectConfiguration`:
519       * `->getGeneratorSkeletonDirs()`
520       * `->getGeneratorTemplate()`
521       * `->getGeneratorTemplateDirs()`
522       * `->getModelDirs()`
523
524   * `sfApplicationConfiguration`:
525       * `->getControllerDirs()`
526       * `->getTemplateDirs()`
527       * `->getTemplateDir()`
528       * `->getTemplatePath()`
529       * `->getI18NGlobalDirs()`
530       * `->getI18NDirs()`
531       * `->getConfigPaths()`
532
533 sfCore
534 ------
535
536 The `sfCore` has been removed. The code has been moved to `sfProjectConfiguration`,
537 `sfApplicationConfiguration`, and `sfContext` classes.
538
539 Front Controllers
540 -----------------
541
542 All front controllers have to be upgraded. The SF_DEBUG, SF_APP, SF_ENVIRONMENT,
543 and SF_ROOT_DIR constants are gone. If you use some of these constants in your
544 project, please use their sfConfig::get('') counterparts:
545
546  *Old*             | *New*
547  ----------------- | ---------------------------------
548  `SF_ROOT_DIR`     | `sfConfig::get('sf_root_dir')`
549  `SF_ENVIRONMENT`  | `sfConfig::get('sf_environment')`
550  `SF_APP`          | `sfConfig::get('sf_app')`
551  `SF_DEBUG`        | `sfConfig::get('sf_debug')`
552
553 The `project:upgrade1.1` task upgrades all front controllers for you.
554 If you made some customizations, symfony will issue a warning and won't
555 upgrade them automatically. You can then copy the default skeleton from
556 symfony: /path/to/symfony/lib/task/generator/skeleton/app/web/index.php
557
558 config.php
559 ----------
560
561 All `config.php` files have been removed. The are replaced by the `ProjectConfiguration`
562 class and the application configuration classes.
563
564 If you've added some cutomizations in `config.php` files, you will have to migrate them
565 to those new classes.
566
567 Directory structure
568 -------------------
569
570 All `sfConfig` constants ending with `_dir_name` have been removed.
571
572 Cache keys
573 ----------
574
575 The `sfViewCacheManager::removePattern()` and `sfToolkit::clearGlob()` don't work anymore
576 for removing several cache parts at once. But the `sfViewCacheManager::remove()` now
577 accepts internal URIs with wildcards. So you can replace:
578
579     $cacheManager->removePattern('*/all/user/show/id/*');
580
581 By:
582
583     $cacheManager->remove('user/show?id=*', '*', 'all');
584
585 This also works for partials and contextual partials. You can then replace:
586
587     $cacheManager->removePattern('/sf_cache_partial/user/_my_partial/sf_cache_key/*');
588
589 By:
590
591     $cacheManager->remove('@sf_cache_partial?module=user&action=_my_partial&sf_cache_key=*');
592
593 And the biggets benefit is that it allows you to clear 'glob' URIs in *any* cache
594 factory, not only the `sfFileCache`.
595
596 Layout
597 ------
598
599 The action template variables are not available anymore in the layout. This means that the layout
600 only has access to **global** variables (all `sf_` variables) and variables registered via the
601 `template.filter_parameters` event.
602
603 Refer to this wiki page for more information on how to upgrade:
604
605     http://trac.symfony-project.com/wiki/Symfony11LayoutUpgrade
606
607 Tasks
608 -----
609
610 The symfony command line task names have changed. They now use a namespace syntax. The old task names still work--they are just aliases for the new task names. Here is a table showing the name changes:
611
612  Old task name             |  New task name
613  ------------------------- | ----------------
614  clear-cache               | cache:clear
615  clear-controllers         | project:clear-controllers
616  disable                   | project:disable
617  downgrade                 | [Not implemented]
618  enable                    | project:enable
619  fix-perms                 | project:permissions
620  freeze                    | project:freeze
621  init-app                  | generate:app
622  init-batch                | [Not implemented]
623  init-controller           | [Not implemented]
624  init-module               | generate:module
625  init-project              | generate:project
626  log-purge                 | log:clear
627  log-rotate                | log:rotate
628  plugin-install            | plugin:install
629  plugin-list               | plugin:list
630  plugin-uninstall          | plugin:uninstall
631  plugin-upgrade            | plugin:upgrade
632  propel-build-all          | propel:build-all
633  propel-build-all-load     | propel:build-all-load
634  propel-build-db           | propel:build-db
635  propel-build-model        | propel:build-model
636  propel-build-schema       | propel:build-schema
637  propel-build-sql          | propel:build-sql
638  propel-convert-xml-schema | propel:schema-to-yml
639  propel-convert-yml-schema | propel:schema-to-xml
640  propel-dump-data          | propel:data-dump
641  propel-generate-crud      | propel:generate-crud
642  propel-init-admin         | propel:init-admin
643  propel-init-crud          | [Not implemented]
644  propel-insert-sql         | propel:insert-sql
645  propel-load-data          | propel:data-load
646  sync                      | project:deploy
647  test-all                  | test:all
648  test-functional           | test:functional
649  test-unit                 | test:unit
650  unfreeze                  | project:unfreeze
651  upgrade                   | project:freeze
652
653 As before, if you want to list the available tasks, just call the `symfony` command with no argument:
654
655     > php symfony
656
657 NOTE to early adopters
658 ----------------------
659
660 If you have upgraded your project and have a `lib/ProjectConfiguration.class.php` file,
661 then you need to upgrade your project manually before being able to launch the
662 `project:upgrade1.1` task.
663
664 Here is how:
665
666   * Move `lib/ProjectConfiguration.class.php` to `config/ProjectConfiguration.class.php`
667
668   * Change the path to symfony in `config/ProjectConfiguration.class.php` if needed.
669
670   * Move all your application configuration classes (`lib/$APP_NAME$Configuration.class.php`)
671     to their respective `apps/$APP_NAME$/config/` directory.
672
673   * Remove the `require_once dirname(__FILE__).'/ProjectConfiguration.class.php';` in all
674     the application configuration classes.
675
676   * Change the location of `ProjectConfiguration.class.php` in the main `symfony` script to `config/`
677
678   * Change your front controllers so they look like this:
679
680         [php]
681         <?php
682
683         require_once(dirname(__FILE__).'/../config/ProjectConfiguration.class.php');
684
685         $configuration = ProjectConfiguration::getApplicationConfiguration('frontend', 'dev', true);
686         sfContext::createInstance($configuration)->dispatch();
687
688 You can now launch the `project:upgrade1.1` script to finish the upgrade.
Note: See TracBrowser for help on using the browser.