Upgrade from 1.0 to 1.1

This document describes the changes made in symfony 1.1 and what need to be done to upgrade your symfony 1.0 projects.

WARNING: symfony 1.1 is only compatible with PHP > 5.1.

How to upgrade?

To upgrade a project:

• If you don't use a SCM tool, please make a backup of your project. As symfony replaces some files during the upgrade (front controllers for example), you need a way to merge your customizations after the upgrade.

• Update the symfony file located in the project root directory by changing those three lines:

  chdir(dirname(__FILE__));
  include('config/config.php');
  include($sf_symfony_data_dir.'/bin/symfony.php');

  to

  chdir(dirname(__FILE__));
  require_once(dirname(__FILE__).'/config/ProjectConfiguration.class.php');
  $configuration = new ProjectConfiguration();
  include($configuration->getSymfonyLibDir().'/command/cli.php');

  You can also copy the skeleton file from the symfony project skeleton directly:

  $ cp /path/to/symfony/lib/task/generator/skeleton/project/symfony symfony
  

• Create a config/ProjectConfiguration.class.php file with the following content:

  <?php
   
  require_once '##SYMFONY_LIB_DIR##/autoload/sfCoreAutoload.class.php';
  sfCoreAutoload::register();
   
  class ProjectConfiguration extends sfProjectConfiguration
  {
    public function setup()
    {
    }
  }

  Then, replace ##SYMFONY_LIB_DIR## with the path to the symfony 1.1 lib/ directory. This is the new way to change the symfony version used for your project.

  You can also copy the skeleton file from the symfony project skeleton directly:

  $ cp /path/to/symfony/lib/task/generator/skeleton/project/config/ProjectConfiguration.class.php config/ProjectConfiguration.class.php
  

• Launch the project:upgrade1.1 task from your project directory to perform an automatic upgrade:

  $ ./symfony project:upgrade1.1
  

  This task can be launched several times without any side effect. Each time you upgrade to a new symfony 1.1 beta / RC or the final symfony 1.1, you need to launch this task.

• If you don't plan to upgrade the validation or mailing system to the new system, you must enable the compatibility mode in settings.yml:

  all:
    .settings:
      compat_10: on

  Here is a list of the things that will be enabled when switching to the compatibility mode (see the bundled sfCompat10Plugin plugin for more information):

  • Zend Framework and ezComponents bridges
  • sfProcessCache
  • validation system (validate.yml, validator classes, ...)
  • fill in filter
  • sfMail with phpmailer

The remaining sections explains backward incompatible changes.

Batch scripts

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.

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:

<?php
define('SF_ROOT_DIR',    realpath(dirname(__FILE__).'/..'));
define('SF_APP',         'frontend');
define('SF_ENVIRONMENT', 'prod');
define('SF_DEBUG',       false);
 
  require_once(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'apps'.DIRECTORY_SEPARATOR.SF_APP.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php');
// your batch code here

To:

<?php
require_once(dirname(__FILE__).'/../config/ProjectConfiguration.class.php');
$configuration = ProjectConfiguration::getApplicationConfiguration('frontend', 'prod', false);
sfContext::createInstance($configuration);
 
// your batch code here

If you need to initialize the database connection, just add the following lines:

$databaseManager = new sfDatabaseManager($configuration);
$databaseManager->loadConfiguration();

Flash attributes

Flash attributes are now managed directly by sfUser. New usage:

// action
$this->getUser()->setFlash('notice', 'foo');
$notice = $this->getUser()->getFlash('notice');
 
// template
<?php $sf_user->hasFlash('notice'): ?>
  <?php echo $sf_user->getFlash('notice') ?>
<?php endif; ?>

The flash entry in filters.yml must be removed too as the sfFlashFilter was removed.

The project:upgrade1.1 task makes all those changes for you.

Deprecated methods in sfComponent

The following methods of sfComponent have been removed:

• ->getPresentationFor()
• ->sendEmail()

They are accessible from sfController:

// action
$this->getController()->getPresentationFor(...);

The project:upgrade1.1 task makes all those changes for you.

Singletons

The sfI18N, sfRouting, and sfLogger objects are now factories and not singletons.

If you want to get one of those objects in your code, they are available from sfContext:

sfContext::getInstance()->getI18N()
sfContext::getInstance()->getRouting()
sfContext::getInstance()->getLogger()

Routing

Here is the default configuration for the routing in factories.yml:

routing:
  class: sfPatternRouting
  param:
    load_configuration: true

The project:upgrade1.1 task makes all the changes for you.

Logging

Here is the default configuration for logging in factories.yml:

logger:
  class: sfAggregateLogger
  param:
    level: debug
    loggers:
      sf_web_debug:
        class: sfWebDebugLogger
        param:
          level: debug
          condition: %SF_WEB_DEBUG%
          xdebug_logging: true
      sf_file_debug:
        class: sfFileLogger
        param:
          level: debug
          file: %SF_LOG_DIR%/%SF_APP%_%SF_ENVIRONMENT%.log

The logging.yml configuration file is not used anymore. Instead, you can configure logging in factories.yml.

To disable logging in the production environment, you will have to change your application factories.yml:

prod:
  logger:
    class:   sfNoLogger
    param:
      level:   err
      loggers: ~

There is also a new logging_enabled setting in settings.yml. This can be used to prevent logging in the production environment altogether:

prod:
  .settings:
    logging_enabled: off

The project:upgrade1.1 task makes all those changes for you.

i18n

Here is the default configuration for i18n in factories.yml:

i18n:
  class: sfI18N
  param:
    source:              XLIFF
    debug:               off
    untranslated_prefix: "[T]"
    untranslated_suffix: "[/T]"
    cache:
      class: sfFileCache
      param:
        automatic_cleaning_factor: 0
        cache_dir:                 %SF_I18N_CACHE_DIR%
        lifetime:                  86400
        prefix:                    %SF_APP_DIR%

The i18n.yml configuration file is not used anymore. Instead, you can configure i18n in factories.yml.

The only exception is the default_culture setting which is now configurable in settings.yml and do not depend on the i18n framework anymore:

default_culture: en

If your project has some specific settings, you must move your current configuration from the i18n.yml to the factories.yml and add the default culture in settings.yml as shown above.

Cache Framework

The sfFunctionCache class does not extend sfFileCache anymore. You must now pass a cache object to the constructor. The first argument to ->call() must now be a PHP callable.

Some sfCache configuration parameter have changed their named to underscore names:

• automaticCleaningFactor -> automatic_cleaning_factor
• cacheDir -> cache_dir

The project:upgrade1.1 task makes all those changes for you.

Autoloading

The autoloading_function setting in settings.yml is not used anymore. You can register autoloading callables in your application configuration class.

Thanks to the new sfAutoload::autoloadAgain() method, you won't need to clear the cache when you add or move classes in your project. This method will automatically find the changes and flush the autoloading cache.

VERSION

The lib/VERSION file has been removed. If you want to get the current symfony version, you can use the SYMFONY_VERSION constant. This constant is defined in autoload/sfCoreAutoload.class.php

Routing

To inject default route parameters, you can now use the ->setDefaultParameter() method instead of using the sf_routing_defaults setting:

$this->context->getRouting()->setDefaultParameter($key, $value);

I18N

symfony core classes don't return internationalized strings anymore:

<?php echo __($sf_request->getError('foo')) ?>

This behavior has changed for the following methods and functions:

sfWebRequest::getError()
sfWebResponse::addMeta()

The following helpers (in sfCompat10Plugin) still return internationalized data:

form_error()
include_metas()

The getGlobalMessageSource() and getGlobalMessageFormat() methods has been removed from the sfI18N class. They are now equivalent to getMessageSource() and getMessageFormat().

Logger

Logger priorities are now constants:

sfLogger::INFO

The project:upgrade1.1 task makes all those changes for you.

Deprecated methods in sfAction

The following methods of sfAction have been deprecated and throw a sfConfigurationException if sf_compat_10 is set to false:

• ->validate()
• ->handleError()

Deprecated methods in sfRequest

The following methods of sfRequest have been deprecated and throw a sfConfigurationException if sf_compat_10 is set to false:

• ->getError()
• ->getErrors()
• ->getErrorNames()
• ->hasError()
• ->hasErrors()
• ->setError()
• ->setErrors()
• ->removeError()

Deprecated methods in sfWebRequest

The following methods of sfWebRequest have been deprecated and throw a sfConfigurationException if sf_compat_10 is set to false:

• ->getFile()
• ->getFileError()
• ->getFileName()
• ->getFileNames()
• ->getFilePath()
• ->getFileSize()
• ->getFileType()
• ->hasFile()
• ->hasFileError()
• ->hasFileErrors()
• ->hasFiles()
• ->getFileValue()
• ->getFileValues()
• ->getFileExtension()
• ->moveFile()

->initialize() methods

Most symfony core classes are initialized thanks to a ->initialize() method. As of symfony 1.1, this method is automatically called by __construct(), so, there is no need to call it by yourself.

Configuration files loading

Some core classes can be configured with a .yml file:

In symfony 1.1, the loading of the configuration file for ''independant'' sub-frameworks has been moved to a loadConfiguration() method to ease decoupling and reuse them without needing the whole framework:

• sfDatabaseManager
• sfI18N
• sfPatternRouting

So, for example, if you need a database manager in your batch script, you will have to change from:

$databaseManager = new sfDatabaseManager();
$databaseManager->initialize();

to:

$configuration = ProjectConfiguration::getApplicationConfiguration($application, $env, true);
$databaseManager = new sfDatabaseManager($configuration);
$databaseManager->loadConfiguration();

The initialize() call is not needed anymore (see the point above).

Web Debug

The web_debug entry in filters.yml must be removed as the sfWebDebugFilter has been removed. The web debug toolbar is now injected in the response thanks to a listener.

The project:upgrade1.1 task makes all those changes for you.

Session timeout

The sf_timeout setting is not used anymore. To change the session timeout, you now have to edit factories.yml instead of the settings.yml, and change the parameters of the user factory:

all:
  user:
    class: myUser
    param:
      timeout:     1800     # session timeout in seconds

Routing configuration

The sf_suffix, sf_default_module, and sf_default_action settings are not used anymore. To change the default suffix, module, or action, you now have to edit factories.yml instead of settings.yml, and change the parameters of the routing factory:

all:
  routing:
    class: sfPatternRouting
    param:
      load_configuration: true
      suffix:             .       # Default suffix for generated URLs. If set to a single dot (.), no suffix is added. Possible values: .html, .php, and so on.
      default_module:     default # Default module and action to be called when
      default_action:     index   # A routing rule doesn't set it

php.yml configuration file

The php.yml configuration file has been removed.

The only setting you will have to check by hand is log_errors, which was set to on by php.yml.

php.yml is replaced by the check_configuration.php utility you can find in data/bin. It checks your environment against symfony requirements. You can launch it from anywhere:

$ php /path/to/symfony/data/bin/check_configuration.php

Even if you can use this utility from the command line, it's strongly recommended to launch it from the web by copying it under your web root directory as PHP can use different php.ini configuration files for the CLI and the web.

$sf_symfony_data_dir removal

In symfony 1.1, $sf_symfony_data_dir has been removed. All relevant files and directories from the symfony data directory have been moved to the lib directory:

The symfony core has been upgraded to take these changes into account.

sfLoader

All sfLoader static methods (except ::getHelperDirs() and ::loadHelpers()) have been moved to the sfProjectConfiguration and sfApplicationConfiguration classes:

• sfProjectConfiguration:

  • ->getGeneratorSkeletonDirs()
  • ->getGeneratorTemplate()
  • ->getGeneratorTemplateDirs()
  • ->getModelDirs()

• sfApplicationConfiguration:

  • ->getControllerDirs()
  • ->getTemplateDirs()
  • ->getTemplateDir()
  • ->getTemplatePath()
  • ->getI18NGlobalDirs()
  • ->getI18NDirs()
  • ->getConfigPaths()

sfCore

The sfCore has been removed. The code has been moved to sfProjectConfiguration, sfApplicationConfiguration, and sfContext classes.

Front Controllers

All front controllers have to be upgraded. The SF_DEBUG, SF_APP, SF_ENVIRONMENT, and SF_ROOT_DIR constants are gone. If you use some of these constants in your project, please use their sfConfig::get('') counterparts:

The project:upgrade1.1 task upgrades all front controllers for you. If you made some customizations, symfony will issue a warning and won't upgrade them automatically. You can then copy the default skeleton from symfony: /path/to/symfony/lib/task/generator/skeleton/app/web/index.php

config.php

All config.php files have been removed. The are replaced by the ProjectConfiguration class and the application configuration classes.

If you've added some cutomizations in config.php files, you will have to migrate them to those new classes.

Directory structure

All sfConfig constants ending with _dir_name have been removed.

Cache keys

The sfViewCacheManager::removePattern() and sfToolkit::clearGlob() don't work anymore for removing several cache parts at once. But the sfViewCacheManager::remove() now accepts internal URIs with wildcards. So you can replace:

$cacheManager->removePattern('*/all/user/show/id/*');

By:

$cacheManager->remove('user/show?id=*', '*', 'all');

This also works for partials and contextual partials. You can then replace:

$cacheManager->removePattern('/sf_cache_partial/user/_my_partial/sf_cache_key/*');

By:

$cacheManager->remove('@sf_cache_partial?module=user&action=_my_partial&sf_cache_key=*');

And the biggets benefit is that it allows you to clear 'glob' URIs in any cache factory, not only the sfFileCache.

Layout

The action template variables are not available anymore in the layout. This means that the layout only has access to global variables (all sf_ variables) and variables registered via the template.filter_parameters event.

Refer to this wiki page for more information on how to upgrade:

http://trac.symfony-project.com/wiki/Symfony11LayoutUpgrade

Tasks

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:

As before, if you want to list the available tasks, just call the symfony command with no argument:

> php symfony

NOTE to early adopters

If you have upgraded your project and have a lib/ProjectConfiguration.class.php file, then you need to upgrade your project manually before being able to launch the project:upgrade1.1 task.

Here is how:

• Move lib/ProjectConfiguration.class.php to config/ProjectConfiguration.class.php

• Change the path to symfony in config/ProjectConfiguration.class.php if needed.

• Move all your application configuration classes (lib/$APP_NAME$Configuration.class.php) to their respective apps/$APP_NAME$/config/ directory.

• Remove the require_once dirname(__FILE__).'/ProjectConfiguration.class.php'; in all the application configuration classes.

• Change the location of ProjectConfiguration.class.php in the main symfony script to config/

• Change your front controllers so they look like this:

  <?php
   
  require_once(dirname(__FILE__).'/../config/ProjectConfiguration.class.php');
   
  $configuration = ProjectConfiguration::getApplicationConfiguration('frontend', 'dev', true);
  sfContext::createInstance($configuration)->dispatch();

You can now launch the project:upgrade1.1 script to finish the upgrade.