root/branches/1.3/WHATS_NEW

What's new in symfony 1.3?
==========================

This tutorial is a quick technical introduction for symfony 1.3.
It is for developers who have already worked with symfony 1.2
and who want to quickly learn new features of symfony 1.3.

First, please note that symfony 1.3 is compatible with PHP 5.2.4 or later.

If you want to upgrade from 1.2, please read the
[UPGRADE](http://www.symfony-project.org/installation/1_3/upgrade) file
found in the symfony distribution.
You will have there all the information needed to safely upgrade
your projects to symfony 1.3.

Security
--------

When a new application is created with the `generate:app` task, the security
settings are now enabled by default:

  * `escaping_strategy`: The value is now `on` by default (can be disabled
    with the `--escaping-strategy` option).

  * `csrf_secret`: A random password is generated by default, and thus, the
    CSRF protection is enabled by default (can be disabled with the
    `--csrf-secret` option). It is highly recommended that you change the
    default generated password, by editing the `settings.yml` configuration
    file, or by using the `--csrf-secret` option.

Widgets
-------

### Default Labels

When a label is auto-generated from the field name, `_id` suffixes are now
removed:

  * `first_name` => First name (as before)
  * `author_id` => Author (was "Author id" before)

Validators
----------

### `sfValidatorRegex`

The `sfValidatorRegex` has a new `must_match` option. If set to `false`, the
regex must not match for the validator to pass.

### `sfValidatorSchemaCompare`

The `sfValidatorSchemaCompare` class has two new comparators:

 * `IDENTICAL`, which is equivalent to `===`;
 * `NOT_IDENTICAL`, which is equivalent to `!==`;

sfToolkit
---------

The `getTmpDir()` method has been deprecated and is no longer used in the
symfony core classes. You can replace usage of this method by the built-in
`sys_get_temp_dir()` PHP function. The `getTmpDir()` is now just a proxy to
this method.

This method will be removed in the symfony 1.4.

Forms
-----

### `sfForm::useFields()`

The new `sfForm::useFields()` method removes all fields from a form except the
ones given as an argument. It is sometimes easier to explicitly give the
fields you want to keep in a form, instead of unsetting all unneeded fields.
For instance, when adding new fields to a base form, they won't automagically
appears in your form until explicitly added (think of a model form where you
add a new column to the related table).

    [php]
    class ArticleForm extends BaseArticleForm
    {
      public function configure()
      {
        $this->useFields(array('title', 'content'));
      }
    }

By default, the array of fields is also used to change the fields order. You
can pass `false` as the second argument to `useFields()` to disable the
automatic reordering.

Validators
----------

### Default Error Messages

You can now define default error messages globally by using the
`sfForm::setDefaultMessage()` method:

    [php]
    sfValidatorBase::setDefaultMessage('required', 'This field is required.');

The previous code will override the default 'Required.' message for all
validators. Note that the default messages must be defined before any
validator is created (the configuration class is a good place).

>**NOTE**
>The `setRequiredMessage()` and `setInvalidMessage()` methods are
>deprecated and call the new `setDefaultMessage()` method.

When symfony displays an error, the error message to use is determined as
follows:

  * Symfony looks for a message passed when the validator was created (via the
    second argument of the validator constructor);

  * If it is not defined, it looks for a default message defined with
    the `setDefaultMessage()` method;

  * If it is not defined, it falls back to the default message defined by the
    validator itself (when the message has been added with the `addMessage()`
    method).

Autoloaders
-----------

### `sfAutoloadAgain` (EXPERIMENTAL)

A special autoloader has been added that is just for use in debug mode. The
new `sfAutoloadAgain` class will reload the standard symfony autoloader and
search the filesystem for the class in question. The net effect is that you no
longer have to run `symfony cc` after adding a new class to a project.

Tests
-----

### Functional Tests

When a request generates an exception, the `debug()` method of the response
tester now outputs a readable text representation of the exception, instead of
the normal HTML output. It makes debugging much more easier.

`sfTesterResponse` has a new `matches()` method that runs a regex on the whole
response content. It is of great help on non XML-like responses, where
`checkElement()` is not useable. It also replaces the less-powerful
`contains()` method:

    [php]
    $browser->with('response')->begin()->
      matches('/I have \d+ apples/')->    // it takes a regex as an argument
      matches('!/I have \d+ apples/')->   // a ! at the beginning means that the regex must not match
      matches('!/I have \d+ apples/i')->  // you can also add regex modifiers
    end();

Tasks
-----

### `sfTask::askAndValidate()`

There is a new `sfTask::askAndValidate()` method to ask a question to the user
and validates its input:

    [php]
    $anwser = $this->askAndValidate('What is you email?', new sfValidatorEmail());

The method also accepts an array of options (see the API doc for more
information).

Exceptions
----------

### Autoloading

When an exception is thrown during autoloading, symfony now catch them and
outputs an error to the user. That should solve most "White screen of death"
pages.

Propel
------

### `propel:insert-sql`

Before `propel:insert-sql` removes all data from a database, it asks for a
confirmation. As this task can remove data from several databases, it now also
displays the name of the connections of the related databases.