diff -r 000000000000 -r 7f95f8617b0b vendor/symfony/UPDATE.md --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/vendor/symfony/UPDATE.md Sat Sep 24 15:40:41 2011 +0200 @@ -0,0 +1,863 @@ +How to update your project? +=========================== + +This document explains how to upgrade from one Symfony2 version to the next +one. It only discusses changes that need to be done when using the "public" +API of the framework. If you "hack" the core, you should probably follow the +timeline closely anyway. + +RC4 to RC5 +---------- + +* The `MapFileClassLoader` has been removed in favor of a new + `MapClassLoader`. + +* The `exception_controller` setting has been moved from the `framework` + section to the `twig` one. + +* The custom error pages must now reference `TwigBundle` instead of + `FrameworkBundle` (see + http://symfony.com/doc/2.0/cookbook/controller/error_pages.html) + +* `EntityUserProvider` class has been moved and FQCN changed from + `Symfony\Component\Security\Core\User\EntityUserProvider` to + `Symfony\Bridge\Doctrine\Security\User\EntityUserProvider`. + +* Cookies access from `HeaderBag` has been removed. Accessing Request cookies + must be done via `Request::$cookies``. + +* `ResponseHeaderBag::getCookie()` and `ResponseHeaderBag::hasCookie()` + methods were removed. + +* The method `ResponseHeaderBag::getCookies()` now supports an argument for the + returned format (possible values are `ResponseHeaderBag::COOKIES_FLAT` + (default value) or `ResponseHeaderBag::COOKIES_ARRAY`). + + * `ResponseHeaderBag::COOKIES_FLAT` returns a simple array (the array keys + are not cookie names anymore): + + * array(0 => `a Cookie instance`, 1 => `another Cookie instance`) + + * `ResponseHeaderBag::COOKIES_ARRAY` returns a multi-dimensional array: + + * array(`the domain` => array(`the path` => array(`the cookie name` => `a Cookie instance`))) + +* Removed the guesser for the Choice constraint as the constraint only knows + about the valid keys, and not their values. + +* The configuration of MonologBundle has been refactored. + + * Only services are supported for the processors. They are now registered + using the `monolog.processor` tag which accept three optionnal attributes: + + * `handler`: the name of an handler to register it only for a specific handler + * `channel`: to register it only for one logging channel (exclusive with `handler`) + * `method`: The method used to process the record (`__invoke` is used if not set) + + * The email_prototype for the `SwiftMailerHandler` only accept a service id now. + + * Before: + + email_prototype: @acme_demo.monolog.email_prototype + + * After: + + email_prototype: acme_demo.monolog.email_prototype + + or if you want to use a factory for the prototype: + + email_prototype: + id: acme_demo.monolog.email_prototype + method: getPrototype + +* To avoid security issues, HTTP headers coming from proxies are not trusted + anymore by default (like `HTTP_X_FORWARDED_FOR`, `X_FORWARDED_PROTO`, and + `X_FORWARDED_HOST`). If your application is behind a reverse proxy, add the + following configuration: + + framework: + trust_proxy_headers: true + +* To avoid hidden naming collisions, the AbstractType does not try to define + the name of form types magically. You now need to implement the `getName()` + method explicitly when creating a custom type. + +* Renamed some methods to follow the naming conventions: + + Session::getAttributes() -> Session::all() + Session::setAttributes() -> Session::replace() + +* {_locale} is not supported in paths in the access_control section anymore. You can + rewrite the paths using a regular expression such as "(?:[a-z]{2})". + +RC3 to RC4 +---------- + +* Annotation classes must be annotated with @Annotation + (see the validator constraints for examples) + +* Annotations are not using the PHP autoloading but their own mechanism. This + allows much more control about possible failure states. To make your code + work, add the following lines at the end of your `autoload.php` file: + + use Doctrine\Common\Annotations\AnnotationRegistry; + + AnnotationRegistry::registerLoader(function($class) use ($loader) { + $loader->loadClass($class); + return class_exists($class, false); + }); + + AnnotationRegistry::registerFile( + __DIR__.'/../vendor/doctrine/lib/Doctrine/ORM/Mapping/Driver/DoctrineAnnotations.php' + ); + + The `$loader` variable is an instance of `UniversalClassLoader`. + Additionally you might have to adjust the ORM path to the + `DoctrineAnnotations.php`. If you are not using the `UniversalClassLoader` + see the [Doctrine Annotations + documentation](http://www.doctrine-project.org/docs/common/2.1/en/reference/annotations.html) + for more details on how to register annotations. + +beta5 to RC1 +------------ + +* Renamed `Symfony\Bundle\FrameworkBundle\Command\Command` to + `Symfony\Bundle\FrameworkBundle\Command\ContainerAwareCommand` + +* Removed the routing `AnnotGlobLoader` class + +* Some blocks in the Twig Form templates have been renamed to avoid + collisions: + + * `container_attributes` to `widget_container_attributes` + * `attributes` to `widget_attributes` + * `options` to `widget_choice_options` + +* Event changes: + + * All listeners must now be tagged with `kernel.event_listener` instead of + `kernel.listener`. + * Kernel events are now properly prefixed with `kernel` instead of `core`: + + * Before: + + + + * After: + + + + Note: the method can of course remain as `onCoreRequest`, but renaming it + as well for consistency with future projects makes sense. + + * The `Symfony\Component\HttpKernel\CoreEvents` class has been renamed to + `Symfony\Component\HttpKernel\KernelEvents` + +* `TrueValidator` and `FalseValidator` constraints validators no longer accepts any value as valid data. + +beta4 to beta5 +-------------- + +* `UserProviderInterface::loadUser()` has been renamed to + `UserProviderInterface::refreshUser()` to make the goal of the method + clearer. + +* The `$kernel` property on `WebTestCase` is now static. Change any instances + of `$this->kernel` in your functional tests to `self::$kernel`. + +* The AsseticBundle has been moved to its own repository (it still bundled + with Symfony SE). + +* Yaml Component: + + * Exception classes have been moved to their own namespace + * `Yaml::load()` has been renamed to `Yaml::parse()` + +* The File classes from `HttpFoundation` have been refactored: + + * `Symfony\Component\HttpFoundation\File\File` has a new API: + + * It now extends `\SplFileInfo`: + + * former `getName()` equivalent is `getBasename()`, + * former `getDirectory()` equivalent is `getPath()`, + * former `getPath()` equivalent is `getRealPath()`. + + * the `move()` method now creates the target directory when it does not exist, + + * `getExtension()` and `guessExtension()` do not return the extension + with a leading `.` anymore + + * `Symfony\Component\HttpFoundation\File\UploadedFile` has a new API: + + * The constructor has a new Boolean parameter that must be set to true + in test mode only in order to be able to move the file. This parameter + is not intended to be set to true from outside of the core files. + + * `getMimeType()` now always returns the mime type of the underlying file. + Use `getClientMimeType()` to get the mime type from the request. + + * `getSize()` now always returns the size of the underlying file. + Use `getClientSize()` to get the file size from the request. + + * Use `getClientOriginalName()` to retrieve the original name from the + request. + +* The `extensions` setting for Twig has been removed. There is now only one + way to register Twig extensions, via the `twig.extension` tag. + +* The stack of Monolog handlers now bubbles the records by default. To stop + the propagation you need to configure the bubbling explicitly. + +* Expanded the `SerializerInterface`, while reducing the number of public + methods in the Serializer class itself breaking BC and adding component + specific Exception classes. + +* The `FileType` Form class has been heavily changed: + + * The temporary storage has been removed. + + * The file type `type` option has also been removed (the new behavior is + the same as when the `type` was set to `file` before). + + * The file input is now rendered as any other input field. + +* The `em` option of the Doctrine `EntityType` class now takes the entity + manager name instead of the EntityManager instance. If you don't pass this + option, the default Entity Manager will be used as before. + +* In the Console component: `Command::getFullname()` and + `Command::getNamespace()` have been removed (`Command::getName()` behavior + is now the same as the old `Command::getFullname()`). + +* Default Twig form templates have been moved to the Twig bridge. Here is how + you can reference them now from a template or in a configuration setting: + + Before: + + TwigBundle:Form:div_layout.html.twig + + After: + + form_div_layout.html.twig + +* All settings regarding the cache warmers have been removed. + +* `Response::isRedirected()` has been merged with `Response::isRedirect()` + +beta3 to beta4 +-------------- + +* `Client::getProfiler` has been removed in favor of `Client::getProfile`, + which returns an instance of `Profile`. + +* Some `UniversalClassLoader` methods have been renamed: + + * `registerPrefixFallback` to `registerPrefixFallbacks` + * `registerNamespaceFallback` to `registerNamespaceFallbacks` + +* The event system has been made more flexible. A listener can now be any + valid PHP callable. + + * `EventDispatcher::addListener($eventName, $listener, $priority = 0)`: + * `$eventName` is the event name (cannot be an array anymore), + * `$listener` is a PHP callable. + + * The events classes and constants have been renamed: + + * Old class name `Symfony\Component\Form\Events` and constants: + + Events::preBind = 'preBind' + Events::postBind = 'postBind' + Events::preSetData = 'preSetData' + Events::postSetData = 'postSetData' + Events::onBindClientData = 'onBindClientData' + Events::onBindNormData = 'onBindNormData' + Events::onSetData = 'onSetData' + + * New class name `Symfony\Component\Form\FormEvents` and constants: + + FormEvents::PRE_BIND = 'form.pre_bind' + FormEvents::POST_BIND = 'form.post_bind' + FormEvents::PRE_SET_DATA = 'form.pre_set_data' + FormEvents::POST_SET_DATA = 'form.post_set_data' + FormEvents::BIND_CLIENT_DATA = 'form.bind_client_data' + FormEvents::BIND_NORM_DATA = 'form.bind_norm_data' + FormEvents::SET_DATA = 'form.set_data' + + * Old class name `Symfony\Component\HttpKernel\Events` and constants: + + Events::onCoreRequest = 'onCoreRequest' + Events::onCoreException = 'onCoreException' + Events::onCoreView = 'onCoreView' + Events::onCoreController = 'onCoreController' + Events::onCoreResponse = 'onCoreResponse' + + * New class name `Symfony\Component\HttpKernel\CoreEvents` and constants: + + CoreEvents::REQUEST = 'core.request' + CoreEvents::EXCEPTION = 'core.exception' + CoreEvents::VIEW = 'core.view' + CoreEvents::CONTROLLER = 'core.controller' + CoreEvents::RESPONSE = 'core.response' + + * Old class name `Symfony\Component\Security\Http\Events` and constants: + + Events::onSecurityInteractiveLogin = 'onSecurityInteractiveLogin' + Events::onSecuritySwitchUser = 'onSecuritySwitchUser' + + * New class name `Symfony\Component\Security\Http\SecurityEvents` and constants: + + SecurityEvents::INTERACTIVE_LOGIN = 'security.interactive_login' + SecurityEvents::SWITCH_USER = 'security.switch_user' + + * `addListenerService` now only takes a single event name as its first + argument, + + * Tags in configuration must now set the method to call: + + * Before: + + + + * After: + + + + * Subscribers must now always return a hash: + + * Before: + + public static function getSubscribedEvents() + { + return Events::onBindNormData; + } + + * After: + + public static function getSubscribedEvents() + { + return array(FormEvents::BIND_NORM_DATA => 'onBindNormData'); + } + +* Form `DateType` parameter `single-text` changed to `single_text` +* Form field label helpers now accepts setting attributes, i.e.: + +```html+jinja +{{ form_label(form.name, 'Custom label', { 'attr': {'class': 'name_field'} }) }} +``` + +* In order to use Swiftmailer, you should now register its "init.php" file via + the autoloader ("app/autoloader.php") and remove the `Swift_` prefix from + the autoloader. For an example on how this should be done, see the Standard + Distribution + [autoload.php](https://github.com/symfony/symfony-standard/blob/v2.0.0BETA4/app/autoload.php#L29). + +beta2 to beta3 +-------------- + +* The settings under `framework.annotations` have changed slightly: + + Before: + + framework: + annotations: + cache: file + file_cache: + debug: true + dir: /foo + + After: + + framework: + annotations: + cache: file + debug: true + file_cache_dir: /foo + +beta1 to beta2 +-------------- + +* The annotation parsing process has been changed (it now uses Doctrine Common + 3.0). All annotations which are used in a class must now be imported (just + like you import PHP namespaces with the "use" statement): + + Before: + +``` php +getParameter('doctrine.orm.entity_managers') + $container->getParameter('doctrine.orm.default_entity_manager') + $container->getParameter('doctrine.orm.default_connection') + + After: + + $container->get('doctrine')->getEntityManagerNames() + $container->get('doctrine')->getDefaultEntityManagerName() + $container->get('doctrine')->getDefaultConnectionName() + + But you don't really need to use these methods anymore, as to get an entity + manager, you can now use the registry directly: + + Before: + + $em = $this->get('doctrine.orm.entity_manager'); + $em = $this->get('doctrine.orm.foobar_entity_manager'); + + After: + + $em = $this->get('doctrine')->getEntityManager(); + $em = $this->get('doctrine')->getEntityManager('foobar'); + +* The `doctrine:generate:entities` arguments and options changed. Run + `./app/console doctrine:generate:entities --help` for more information about + the new syntax. + +* The `doctrine:generate:repositories` command has been removed. The + functionality has been moved to the `doctrine:generate:entities`. + +* Doctrine event subscribers now use a unique "doctrine.event_subscriber" tag. + Doctrine event listeners also use a unique "doctrine.event_listener" tag. To + specify a connection, use the optional "connection" attribute. + + Before: + + listener: + class: MyEventListener + tags: + - { name: doctrine.common.event_listener, event: name } + - { name: doctrine.dbal.default_event_listener, event: name } + subscriber: + class: MyEventSubscriber + tags: + - { name: doctrine.common.event_subscriber } + - { name: doctrine.dbal.default_event_subscriber } + + After: + + listener: + class: MyEventListener + tags: + - { name: doctrine.event_listener, event: name } # register for all connections + - { name: doctrine.event_listener, event: name, connection: default } # only for the default connection + subscriber: + class: MyEventSubscriber + tags: + - { name: doctrine.event_subscriber } # register for all connections + - { name: doctrine.event_subscriber, connection: default } # only for the default connection + +* Application translations are now stored in the `Resources` directory: + + Before: + + app/translations/catalogue.fr.xml + + After: + + app/Resources/translations/catalogue.fr.xml + +* The option `modifiable` of the `collection` form type was split into two + options `allow_add` and `allow_delete`. + + Before: + + $builder->add('tags', 'collection', array( + 'type' => 'text', + 'modifiable' => true, + )); + + After: + + $builder->add('tags', 'collection', array( + 'type' => 'text', + 'allow_add' => true, + 'allow_delete' => true, + )); + +* `Request::hasSession()` has been renamed to `Request::hasPreviousSession()`. The + method `hasSession()` still exists, but only checks if the request contains a + session object, not if the session was started in a previous request. + +* Serializer: The NormalizerInterface's `supports()` method has been split in + two methods: `supportsNormalization()` and `supportsDenormalization()`. + +* `ParameterBag::getDeep()` has been removed, and is replaced with a boolean flag + on the `ParameterBag::get()` method. + +* Serializer: `AbstractEncoder` & `AbstractNormalizer` were renamed to + `SerializerAwareEncoder` & `SerializerAwareNormalizer`. + +* Serializer: The `$properties` argument has been dropped from all interfaces. + +* Form: Renamed option value `text` of `widget` option of the `date` type was + renamed to `single-text`. `text` indicates to use separate text boxes now + (like for the `time` type). + +* Form: Renamed view variable `name` to `full_name`. The variable `name` now + contains the local, short name (equivalent to `$form->getName()`). + +PR12 to beta1 +------------- + +* The CSRF secret configuration has been moved to a mandatory global `secret` + setting (as the secret is now used for everything and not just CSRF): + + Before: + + framework: + csrf_protection: + secret: S3cr3t + + After: + + framework: + secret: S3cr3t + +* The `File::getWebPath()` and `File::rename()` methods have been removed, as + well as the `framework.document_root` configuration setting. + +* The `File::getDefaultExtension()` method has been renamed to `File::guessExtension()`. + The renamed method now returns null if it cannot guess the extension. + +* The `session` configuration has been refactored: + + * The `class` option has been removed (use the `session.class` parameter + instead); + + * The PDO session storage configuration has been removed (a cookbook recipe + is in the work); + + * The `storage_id` option now takes a service id instead of just part of it. + +* The `DoctrineMigrationsBundle` and `DoctrineFixturesBundle` bundles have + been moved to their own repositories. + +* The form framework has been refactored extensively (more information in the + documentation). + +* The `trans` tag does not accept a message as an argument anymore: + + {% trans "foo" %} + {% trans foo %} + + Use the long version the tags or the filter instead: + + {% trans %}foo{% endtrans %} + {{ foo|trans }} + + This has been done to clarify the usage of the tag and filter and also to + make it clearer when the automatic output escaping rules are applied (see + the doc for more information). + +* Some methods in the DependencyInjection component's `ContainerBuilder` and + `Definition` classes have been renamed to be more specific and consistent: + + Before: + + $container->remove('my_definition'); + $definition->setArgument(0, 'foo'); + + After: + + $container->removeDefinition('my_definition'); + $definition->replaceArgument(0, 'foo'); + +* In the rememberme configuration, the `token_provider key` now expects a real + service id instead of only a suffix. + +PR11 to PR12 +------------ + +* `HttpFoundation\Cookie::getExpire()` was renamed to `getExpiresTime()` + +* XML configurations have been normalized. All tags with only one attribute + have been converted to tag content: + + Before: + + + + + + After: + + MyBundle + twig + twig.extension.debug + +* Fixes a critical security issue which allowed all users to switch to + arbitrary accounts when the SwitchUserListener was activated. Configurations + which do not use the SwitchUserListener are not affected. + +* The Dependency Injection Container now strongly validates the references of + all your services at the end of its compilation process. If you have invalid + references this will result in a compile-time exception instead of a run-time + exception (the previous behavior). + +PR10 to PR11 +------------ + +* Extension configuration classes should now implement the + `Symfony\Component\Config\Definition\ConfigurationInterface` interface. Note + that the BC is kept but implementing this interface in your extensions will + allow for further developments. + +* The `fingerscrossed` Monolog option has been renamed to `fingers_crossed`. + +PR9 to PR10 +----------- + +* Bundle logical names earned back their `Bundle` suffix: + + *Controllers*: `Blog:Post:show` -> `BlogBundle:Post:show` + + *Templates*: `Blog:Post:show.html.twig` -> `BlogBundle:Post:show.html.twig` + + *Resources*: `@Blog/Resources/config/blog.xml` -> `@BlogBundle/Resources/config/blog.xml` + + *Doctrine*: `$em->find('Blog:Post', $id)` -> `$em->find('BlogBundle:Post', $id)` + +* `ZendBundle` has been replaced by `MonologBundle`. Have a look at the + changes made to Symfony SE to see how to upgrade your projects: + https://github.com/symfony/symfony-standard/pull/30/files + +* Almost all core bundles parameters have been removed. You should use the + settings exposed by the bundle extension configuration instead. + +* Some core bundles service names changed for better consistency. + +* Namespace for validators has changed from `validation` to `assert` (it was + announced for PR9 but it was not the case then): + + Before: + + @validation:NotNull + + After: + + @assert:NotNull + + Moreover, the `Assert` prefix used for some constraints has been removed + (`AssertTrue` to `True`). + +* `ApplicationTester::getDisplay()` and `CommandTester::getDisplay()` method + now return the command exit code + +PR8 to PR9 +---------- + +* `Symfony\Bundle\FrameworkBundle\Util\Filesystem` has been moved to + `Symfony\Component\HttpKernel\Util\Filesystem` + +* The `Execute` constraint has been renamed to `Callback` + +* The HTTP exceptions classes signatures have changed: + + Before: + + throw new NotFoundHttpException('Not Found', $message, 0, $e); + + After: + + throw new NotFoundHttpException($message, $e); + +* The RequestMatcher class does not add `^` and `$` anymore to regexp. + + You need to update your security configuration accordingly for instance: + + Before: + + pattern: /_profiler.* + pattern: /login + + After: + + pattern: ^/_profiler + pattern: ^/login$ + +* Global templates under `app/` moved to a new location (old directory did not + work anyway): + + Before: + + app/views/base.html.twig + app/views/AcmeDemoBundle/base.html.twig + + After: + + app/Resources/views/base.html.twig + app/Resources/AcmeDemo/views/base.html.twig + +* Bundle logical names lose their `Bundle` suffix: + + *Controllers*: `BlogBundle:Post:show` -> `Blog:Post:show` + + *Templates*: `BlogBundle:Post:show.html.twig` -> `Blog:Post:show.html.twig` + + *Resources*: `@BlogBundle/Resources/config/blog.xml` -> `@Blog/Resources/config/blog.xml` + + *Doctrine*: `$em->find('BlogBundle:Post', $id)` -> `$em->find('Blog:Post', $id)` + +* Assetic filters must be now explicitly loaded: + + assetic: + filters: + cssrewrite: ~ + yui_css: + jar: "/path/to/yuicompressor.jar" + my_filter: + resource: "%kernel.root_dir%/config/my_filter.xml" + foo: bar