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.2.

How to upgrade?
---------------

To upgrade a project, you first need to upgrade symfony via PEAR or
change your `config/config.php` to update the symfony directory.

Then, you can launch the following 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 system or all your helpers to
the new system, you must enable the compatibility mode in `settings.yml`:

  [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
  * helpers
  * sfMail with phpmailer


Some upgrade tasks are not suited for automation and upgrading your configuration
and object model for Propel is one of them.

Propel
------

Propel also requires some upgrades, most notably to the dsn format and pdo transaction api.
For complete upgrade instructions see: http://propel.phpdb.org/trac/wiki/Users/Documentation/1.3/Upgrading


The remaining sections explains backward incompatible changes.

Flash attributes
----------------

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

  [php]
  // 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`:

  [php]
  // 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 still
available from `sfContext`:

  [php]
  sfContext::getInstance()->getI18N()
  sfContext::getInstance()->getRouting()
  sfContext::getInstance()->getLogger()

Here is their default configuration in `factories.yml`:

  i18n:
    class: sfI18N
    param:
      cache:
        class: sfFileCache
        param:
          automaticCleaningFactor: 0
          cacheDir:                %SF_I18N_CACHE_DIR%
          lifetime:                86400

  routing:
    class: sfPatternRouting
    param:
      load_configuration: true

  logger:
    class: sfAggregateLogger
    param:
      level: debug
      loggers:
        sf_web_debug:
          class: sfWebDebugLogger
          param:
            condition: %SF_WEB_DEBUG%
        sf_file_debug:
          class: sfFileLogger
          param:
            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.

sfFunctionCache
---------------

The sfFunctionCache object 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.

Autoloading
-----------

The `autoloading_function` setting in `settings.yml` is not used anymore.
You can register autoloading callables in the application `config.php`.
Here is the new default `config.php`:

  [php]
  <?php

  // include project configuration
  include(SF_ROOT_DIR.DIRECTORY_SEPARATOR.'config'.DIRECTORY_SEPARATOR.'config.php');

  // symfony bootstraping
  require_once($sf_symfony_lib_dir.'/util/sfCore.class.php');
  sfCore::bootstrap($sf_symfony_lib_dir, $sf_symfony_data_dir);

  // insert your own autoloading callables here

  if (sfConfig::get('sf_debug'))
  {
    spl_autoload_register(array('sfAutoload', 'autoloadAgain'));
  }

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.

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

VERSION
-------

The lib/VERSION file has been removed. If you want to get the current symfony version,
you can use the `sfCore::VERSION` constant.

Routing
-------

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

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

I18N
----

symfony core classes don't return internationalized strings anymore:

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

This behavior has changed for the following methods and functions:

  [php]
  sfWebRequest::getError()
  sfWebResponse::addMeta()

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

  [php]
  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:

  [php]
  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()`

sfValidator class
-----------------

If you use the symfony 1.0 interface for validation, your custom validators must
now extend the `sfValidatorBase` class.
