root/tags/RELEASE_0_6_1/UPGRADE

Upgrading symfony to 0.6/0.7 from 0.4/0.5
=========================================

If you have a project based on symfony 0.4.X or 0.5.X, it has to be upgraded 
in order to work with a 0.6.X or 0.7.X release. The process is quick and  
partly automated.

>**Note**: Stable releases have even second digit, nightly releases have odd second digit. For instance:
>
>* release 0.6.0 is stable
>* releases 0.6.xxx are also stable, and contain bug fixes to the 0.6.0
>* releases 0.7.xxx are subversion trunk nightly releases and bring additionnal features to the 0.6.0

Main steps
----------

 0. Update symfony to 0.6.XX (if it is not already done)
  
        $ pear upgrade symfony/symfony

    If you want to try symfony 0.6 alpha, use:

        $ pear upgrade symfony/symfony-alpha

 1. Make a backup of your project (this is the most important step!)

 2. Move all your application directories under a new `apps/` directory 
 (see step 1-2 of the _Application modifications_ section below)

 3. Launch the following command in your project root directory:

        $ symfony upgrade 0.6
        
    Or do manually the steps 3-12 described below

 4. Check the changes made to your project by the symfony upgrade command
 (`svn diff` if you use subversion) and make sure your code is still there.

 5. Update your `databases.yml` configuration file 
 (see step 13 of the _Application modifications_ section below)
  
 6. Follow the manual steps numbered 14 to 19 below

Be careful if your project directory contains external libraries using
`SF_XXX`, `MOD_XXX` or `APP_XXX` constants. As the `upgrade` command 
transforms these constants into a class method call, you will probably need to 
overwrite the upgraded libraries by the the backup copy (for instance, this 
happens for the 'geshi' library).

You can launch the `symfony upgrade 0.6` command several times without 
problem.

Application modifications
-------------------------

For all your applications within a project:

 1. Move all your apps under an `apps/` directory

    0.4.X/0.5.X              | 0.6.X/0.7.X
    -------------------------|----------------------------
    `SF_ROOT_DIR/frontend`   | `SF_ROOT_DIR/apps/frontend`
    `SF_ROOT_DIR/backend`    | `SF_ROOT_DIR/apps/backend`

 2. Change the path to `config.php` in your `index.php` and all the other
 front controllers.
    
        require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php');

 3. Update your `myapp/config/config.php` file with the new one 
 (`data/symfony/skeleton/app/app/config/config.php`).

 4. Change the calls to all the symfony configuration constants  in the php code
 (`SF_XXX`, `APP_XXX`, `MOD_XXX`) to calls to the new `sfConfig` class, except
 for the constants called in `index.php` (`SF_ROOT_DIR`, `SF_APP`,
 `SF_ENVIRONMENT, SF_DEBUG`):

    0.4.X/0.5.X                | 0.6.X/0.7.X
    ---------------------------|-------------------------------------
    `define('SF_FOO', 'bar')`  | `sfConfig::set('sf_foo', 'bar')`
    `defined('SF_FOO')`        | `sfConfig::get('sf_foo') or nothing`
    `SF_FOO`                   | `sfConfig::get('sf_foo')`

 5. In your template files, change the shortcuts to the symfony objects 
 by adding a `sf_` prefix:

    0.4.X/0.5.X        | 0.6.X/0.7.X
    -------------------|-------------------
    `$context`         | `$sf_context`
    `$params`          | `$sf_params`
    `$request`         | `$sf_request`
    `$user`            | `$sf_user`
    `$view`            | `$sf_view`
    `$last_module`     | `$sf_last_module`
    `$last_actio`      | `$sf_last_action`
    `$first_module`    | `$sf_first_module`
    `$first_action`    | `$sf_first_action`

 6. Update the `settings.yml` configuration file:
  
    0.4.X/0.5.X                             | 0.6.X/0.7.X
    ----------------------------------------|-------------------------------------------
    `standard_helpers: Partial,Cache,Form`  | `standard_helpers: [Partial, Cache, Form]`
    `is_i18n: on`                           | `i18n: on`
    `default_culture: en`                   | -> new `i18n.yml` configuration file

 7. Move your `messages.xml` i18n XML file from `i18n/global` to the `i18n`
 directory.

 8. Replace any definition of the `disable_web_debug` attribute by a call to:
  
        sfConfig::set('sf_web_debug', false);
        
    (this is used to disable the web debug toolbar in development for
    non-html views).

 9. Rename the calls to the `sfPager` class to `sfPropelPager`
  
 10. `mail_to` has a new parameter

    0.4.X/0.5.X                   | 0.6.X/0.7.X
    ------------------------------|-------------------------------------
    `mail_to($email, true)`       | `mail_to($email, $name, 'encode=1')`

 11. Change all the deprecated methods in your actions

    0.4.X/0.5.X                  | 0.6.X/0.7.X
    -----------------------------|----------------------------
    `$this->forward404_if()`     | `$this->forward404If()`
    `$this->forward404_unless()` | `$this->forward404Unless()`
    `$this->forward_if()`        | `$this->forwardIf()`
    `$this->forward_unless()`    | `$this->forwardUnless()`
    `$this->redirect_if()`       | `$this->redirectIf()`
    `$this->redirect_unless()`   | `$this->redirectUnless()`

 12. Change all the comments in your YAML files from `;` to `#`

 13. Update your `databases.yml` configuration file. The `orm.yml`
 configuration file is not needed anymore. All database configuration now occur
 in the `databases.yml`.
       
        [0.4.X/0.5.X > orm.yml]
        all:
          adapter:  mysql
          host:     localhost
          database: dbname
          username: root
          password:
         
        [0.6.X/0.7.X > databases.yml]
        all:
          propel:
            class:          sfPropelDatabase
            param:
              datasource:   symfony
              phptype:      mysql
              hostspec:     localhost
              database:     dbname
              username:     root
              password:     
              compat_assoc_lower:  true
              compat_rtrim_string: true

    The `datasource` parameter (`symfony` in this example) refers to the database connection as defined in the the `name` attribute of the `<database>` tag in the `schema.xml`.

    If you don't specify the `datasource` param, it takes the value of the label given to the connection settings (`propel` in this example).

    To get a dabatase connection, you must now use the symfony database manager:

       0.4.X/0.5.X                  | 0.6.X/0.7.X
       -----------------------------|--------------------------------------------------------------------
       `Propel::getConnection()`    | `sfContext::getInstance()->getDatabaseConnection($connection_name)`

    `$connection_name` is the name of your connection (`propel` in the example above).

 14. Change all calls to the `->setSort()` method of the `sfPropelPager` object
 to the equivalent `Criteria` methods.

 15. Change your symlinks or apache configuration to move the `web/sf` directory:

    0.4.X/0.5.X                           | 0.6.X/0.7.X
    --------------------------------------|----------------------------
    SVN                                   |
    `/SYMFONY_PATH/data/symfony/web/sf`   | `/SYMFONY_PATH/data/web/sf`
                                          |
    PEAR                                  |
    `/PEAR_DATA_PATH/data/symfony/web/sf` | `/PEAR_DATA_PATH/data/web/sf`

 16. If your project use the `sfShoppingCart` or `sfFeed` classes, install the
 related plugins, since they are no longer shipped with the default symfony
 installation:
   
        $ symfony plugin-install [local|global] symfony/sfFeed
        $ symfony plugin-install [local|global] symfony/sfShoppingCart        
        or       
        $ pear install symfony/sfFeed (equivalent to the `global` install)
        $ pear install symfony/sfShoppingCart

 17. The first parameter of the `options_for_select()` helper changed to be
 more intuitive:

    0.4.X/0.5.X                                              | 0.6.X/0.7.X
    ---------------------------------------------------------|-------------------------------------------------------
    `options_for_select(array('France' => 1, 'USA' => 2))`   | `options_for_select(array(1 => 'France', 2 => 'USA'))`
    `options_for_select(array_flip(array('France', 'USA')))` | `options_for_select(array('France', 'USA'))`

 18. If you have some batch files using database connection, you now have to
 initialize the context. Add the following line after `config.php` loading:
  
        sfContext::getInstance();

 19. Clear the symfony cache