Today, the Symfony crew has released Symfony 1.3 and 1.4. I recently deployed a pretty basic 1.2 app, and decided to try upgrading it to 1.3, and then on to 1.4, just to see if these "easy upgrade" claims were as advertised.
I will be following the 1.2 to 1.3/1.4 Upgrade Instructions below, so you should read over them before we get started.
If you're not using version control, now might be a good time to learn. I am using Subversion for this specific project, but suggest you look at git. The rest of this post will give examples using Subversion for keeping your project up to date.
Let's create a new branch from our trunk to handle upgrading to 1.3.
Checkout your new branch to your development environment and let's get started.
Many core plugins were recently updated for 1.3, so check the plugin repository for a 1.3 branch. (Some plugins may work without modification, but this is a case-by-case basis.)
Your plugins may not be as well maintained. Depending on how critical your plugin functionality, you may not be able to continue upgrading at this time.
In my case, I was only using the sfFormExtraPlugin plugin to add some a multi-choice options to my forms.
Our Symfony core files live in
symfony1_3/lib/vendor/symfony. I had manually installed the core files from a ZIP archive when I started developing the project, so they were not yet using svn:externals.
We will remove the old 1.2 files and install the core files from the central 1.3 repository branch. By referencing the 1.3 branch, every time we execute
svn up, our Symfony core libraries are updated to the newest version. This may or may not be the best solution in your case. If you do not want your core libraries automatically updated, reference one of Symfony's RELEASE tags.
Since the application I developed is not a critical application, I chose to live on the edge and reference the 1.3 branch.
svn commit . -m "Remove Symfony 1.2 core libraries. Install Symfony 1.3 core libraries via svn:externals." svn up
You can try to update your plugins via the traditional
plugin:upgrade yourPluginNameHere, or check the plugin repository for a 1.3 branch or 1.3-compatible development in the trunk.
sfWidgetFormPlugin has a 1.3 branch, so again, let's remove the old plugin and link up the new one. My previous version was installed via the traditional
php symfony plugin:install sfFormExtraPlugin command, so it should first be uninstalled, deleted, then linked up with an
svn commit . -m "Update sfFormExtraPlugin to 1.3-compatible branch." svn up
Repeat this process for all of your plugins that have new versions available.
Running this command will automatically upgrade your code base to Symfony 1.3.
Assuming you are using Doctrine as your ORM, Symfony 1.3/1.4 also upgrades Doctrine from 1.0 to 1.2. You will need to manually check your code against the upgrade documentation for Doctrine 1.0 to 1.1 Upgrade and Doctrine 1.1 to 1.2 Upgrade.
In my project, I was using a few non-static methods that had been changed to static methods in Doctrine 1.2.
With all our code updated, it's time to run the gauntlet of updating our forms, filters and models.
Load up the dev environment for your application in your browser and cross your fingers :) Check the Web Debug bar and see that you're running on Symfony 1.3.0 and the version of your ORM.
Assuming everything works, commit back to SVN.
Now that our project is up to date with Symfony 1.3, we need to prepare to move it to Symfony 1.4. Fabien recently added an amazingly helpful command project:validate that checks your code for use of deprecated code that has been removed for Symfony 1.4. Running the command against your project gives a list of deprecated classes in use and their location.
Since I started writing this project on Symfony 1.2.8, and this is a relatively straightforward project, there is not much to change. If you started from 1.0 or 1.1, there is undoubtedly a lot more code to change.
Most of the deprecated code above appears in the
/base/ directory of the Doctrine-generated code, which will be fixed when we regenerate our models/forms/filters.
project:validate found one use of
EventForm.class.php. Since I redefined my Event form in the
EventForm::configure() method, I need to find the fix for using this deprecated class.
After checking the Deprecated Code page for 1.3, the
*Many() form widgets have been deprecated.
sfWidgetFormDoctrineChoiceMany has been consolidated into the
sfWidgetFormDoctrineChoice class by adding the option
array('multiple' => true) to denote a multi-select.
Since I was using a deprecated form widget, I also double-checked the widget's validator for the same field. [sfValidatorDoctrineChoiceMany] has not been deprecated. Instead, it calls its parent
configure() method in its parent class
sfValidatorDoctrineChoice, and sets the option
multiple to true.
Sounds very similar to the explanation above, doesn't it? Why the developers chose to deprecate the widget and not the validator, I'm not sure. Regardless, I chose to change
sfValidatorDoctrineChoiceMany just to stay consistent with my form widget.
sfCompat10Plugin is also deprecated in Symfonry 1.4, so we must
remove all references to it. In my case, I had excluded it from loading in myproject/config/ProjectConfiguration.class.php.
At this point, we have removed all deprecated code and are ready to upgrade our project to Symfony 1.4! Commit our latest changes.
Once again, you should check if your plugins have Symfony 1.4 versions, and update their
svn:external references to their 1.4 branches.
If you plugin does not have a 1.4 version, the 1.3 version may work without modification. If the
project:validate task does not return any deprecated code used in plugins, you may be clear.
plugins #Update your repo URLs to their 1.4 branches
With our Symfony core libraries referenced via
svn:externals, we also need to update that reference to the Symfony 1.4 branch.
Now regenerate our forms, filters and models.
And assuming everything works, commit everything back to our development branch!
Congratulations! You are now working with the latest version of Symfony 1.4!
Well that was rather painless! You may or may not agree depending on how much legacy code you are maintaining :)
Congratulations to Fabien Potencier, Fabien Lange, Jonathan Wage, Kris Wallsmith and everyone who submitted patches to make this release possible!
With your new Symfony 1.4 install, why not start learning some of the more advanced tutorials in the Symfony 2009 Advent Calendar?comments powered by Disqus