Symfony 2.3 upgrade summary
Long awaited, Symfony 2.3 upgrade has been merged six days ago and it introduces much more than just vendors update.
Thanks to the improvements done to the framework and Doctrine integration, we were able to make another step towards top flexibility.
I'd like to thank all the participants for the ideas and suggestions, especially Molchanov Ivan.
He carried out new listener which allows to include default entities in the bundles and extend them easily in your own application.
You can read about this and other features in the summary below.
"Entity" and "Document" classes are gone
With the new compiler passes available, I got rid of all the
Document classes. From now, no matter which database storage you are using, please extend the
Model class directly.
Appropriate mapping will be loaded automatically, turning the model classes into ODM documents or ORM entities, depending on your driver setting.
Thanks to the new Doctrine listener which hooks into the
event, we are able to provide default entities in all bundles.
This makes the installation much easier, as you do not have to define new classes,
just to map an ID field and configure it in
In case you want to override a model in any bundle, simply extend the Model class and define only your custom mappings. The listener will automatically turn the default entities into mapped super classes.
A more detailed guide how to override models can be found in the documentation.
It was possible before, but had several disadvantages. We had to keep hacky entities like
DefaultProduct and Sylius always wanted to create database tables for
them, even if they were not used. Also, overriding core models required
copying some of the mappings, now everything is moved by the framework.
Cart and Order merge
Previously, the Cart and Order model were separate, and we were performing a transformation at the end of the checkout. Unfortunately, this introduced a lot of duplications.
SyliusCartBundle now works on top of SyliusSalesBundle. This coupling is acceptable because sales bundle is only about super-flexible Order model with items and adjustments (for taxes/discounts/shipping charges). The cart bundle extends this functionality with adding/removing items logic and actions.
This simplifies a lot of checkout logic in the main application, as well as the codebase in general.
Documentation should be updated accordingly in the following days.
New shipping engine
The new shipping engine deserves a separate article and it will get one. Below you can see very general summary of the changes.
Constructing a full Shipment model (with all the items) can be an overhead when you simply want to calculate a cost of shipping few products.
Our shipping cost calculators (
CalculatorInterface) required the
ShipmentInterface as an argument. Currently, any model can be used for the
calculation, only requirement is to implement the new
ShippingSubjectInterface. Obviously, the default shipment interface inherits from it.
The new interface contains several methods which should return the information about the potential or real shipment. It also allowed us to implement weight based cost calculators and new rules.
If you ever integrated our promotions system, you should already be familiar with this concept.
Basically, every Rule model holds a name of the RuleChecker and appropriate configuration.
Every shipping method can hold a collection of rules. When you want to display the available shipping methods to the user, a special service goes through all the methods. It uses the RuleCheckers to validate if given ShippingMethod is capable of transporting the particular ShippingSubjectInterface instance.
Each checker can have a configuration schema. It is used to display a form when creating new ShippingMethod.
It may sound complex, but it is really simple and allows almost unlimited flexibility because you can implement your own checkers!
A documentation PR has been opened and should be merged soon.
Decoupling Assortment Bundle
Sylius products catalog is inspired by the Spree project and supports product options, variations, attributes and prototypes. In many cases, you need much less than that and the additional options and variants engine only complicates your work, when you require only simple product model with properties.
Thanks to the flexibility of Symfony 2.3, I decoupled the original SyliusAssortmentBundle into two new bundles - SyliusProductBundle and SyliusVariableProductBundle.
The first bundle provides the basic product model with attributes and prototypes.
The second one works as an extension layer. You simply need to enable it in the Kernel and you will get options and variants support, without any configuration!
I also believe that the names are clearer now. Many people searching for products catalog were missing the old bundle because of the naming.
Overriding validation got easier
Thanks to the work of Sasa Stamenkovic and me, all validation mappings and forms in the bundles use "sylius" as the default group.
Before this change, you were pretty much stuck with the validation rules shipped with Sylius.
From now on, you can configure the used validation group for each model and use your own mappings.
A more detailed guide how to override validation can be found in the documentation.
Upgrade to the latest phpspec
Few BC breaks were involved, but I got all the specs updated and we're now using the phpspec 2.0.0 BETA4.
With the Symfony 2.3 upgrade finalized, we can move forward with pending features. Last week I've also done some documentation improvements and implemented checkout events.
Expect another blog post next Friday and I hope you enjoyed this read!