Upgrading KnpPaginatorBundle & PHP Platform Version
Keep on Learning!
If you liked what you've learned so far, dive in! Subscribe to get access to this tutorial plus video, code and script downloads.
With a Subscription, click any sentence in the script to jump to that part of the video!
Login SubscribeIf you look at the list of deprecations, a bunch of these mention the same problem: some TreeBuilder::root() thing. This is a low-level function that third-party bundles use. And if you dig through the list, this stof_doctrine_extensions comes from StofDoctrineExtensionsBundle... as does most of the other ones - like orm, and mongodb. The last one comes from KnpPaginatorBundle.
So basically... we need to upgrade both KnpPaginatorBundle and StofDoctrineExtensionsBundle.
Upgrading KnpPaginatorBundle the Lazy Way
Let's start with KnpPaginatorBundle... and try to be as lazy as possible. Copy the package name, move over, and run:
composer update knplabs/knp-paginator-bundle
My hope is that a minor upgrade - something like 2.8 to 2.9, which my composer.json version constraint allows - will be enough to fix the deprecation:
| { | |
| // ... lines 2 - 3 | |
| "require": { | |
| // ... lines 5 - 9 | |
| "knplabs/knp-paginator-bundle": "^2.7", | |
| // ... lines 11 - 43 | |
| }, | |
| // ... lines 45 - 102 | |
| } |
And... absolutely nothing happens. It didn't upgrade the library at all! Boo.
Digging into a Library's Releases
So much for the lazy way out: now we need to do some digging. Google for the bundle and find their GitHub page. PhpStorm tells me that I currently have version 2.8.0. Back on the GitHub page, click on "Releases".
Woh! The latest version is 5.0! And it says:
Added support for Symfony 5
That's what we want! So, to get a version of this library that works with Symfony 5, we need to upgrade to 5.0 of the bundle. Back in composer.json, change the version to ^5.0:
| { | |
| // ... lines 2 - 3 | |
| "require": { | |
| // ... lines 5 - 9 | |
| "knplabs/knp-paginator-bundle": "^5.0", | |
| // ... lines 11 - 42 | |
| }, | |
| // ... lines 44 - 101 | |
| } |
And yes, because we're upgrading to a new major version - heck, we're upgrading 3 new major versions - this could contain some backwards-incompatible changes that will break our app. Let's... worry about that in a little while.
Go update!
composer update knplabs/knp-paginator-bundle
Checking your config.platform.php Setting
And... this fails. Boo! Let's see: we tried to get version 5.0 of the bundle... but it requires PHP 7.2 or higher... and my PHP version is 7.3.6... but is overwritten by my config.platform.php version... which is 7.1.3.
Wow! That's a fancy way of saying that:
Version 5 of this library requires a higher version of PHP than I'm using
Except... well... that's not totally right. I'm using PHP 7.3, but in my composer.json file... if you search for config, here it is: I added a config.platform.php key set to 7.1.3:
| { | |
| // ... lines 2 - 53 | |
| "config": { | |
| // ... lines 55 - 58 | |
| "platform": { | |
| "php": "7.1.3" | |
| } | |
| }, | |
| // ... lines 63 - 101 | |
| } |
This is an optional setting and you might not have this in your app... but I do recommend adding it. It tells Composer to pretend like I'm using PHP 7.1.3 when downloading dependencies even though I'm actually using PHP 7.3.
Why would I want that? By setting this value to whatever PHP version you have on production, it will make sure you don't accidentally download any packages that work on your local machine with its higher PHP version... but explode on production.
So if our goal is to upgrade to Symfony 5, our production server will need to at least be set to Symfony 5's minimum PHP version, which is 7.2.5. And for consistency... even though it doesn't affect anything, under the require key, update this too:
| { | |
| // ... lines 2 - 3 | |
| "require": { | |
| "php": "^7.2.5", | |
| // ... lines 6 - 42 | |
| }, | |
| // ... lines 44 - 53 | |
| "config": { | |
| // ... lines 55 - 58 | |
| "platform": { | |
| "php": "7.2.5" | |
| } | |
| }, | |
| // ... lines 63 - 101 | |
| } |
Updating --with-dependencies
Ok now that Composer knows it's ok to download packages that require PHP 7.2... let's try that update command again:
composer update knplabs/knp-paginator-bundle
And... yay! Another error! I mean, another fascinating challenge that we are totally up to beating. Hmm... KnpPaginatorBundle requires something called knp-components and... basically 5.0 of the bundle requires version 2 of knp-components, but we're currently "locked" at version 1.3, which just means that version 1.3 is what is installed in our app right now.
This knp-components library is not something that we have directly in our composer.json file: it's a "transitive" dependency, which is a hipster way of saying that our app only needs it because KnpPaginatorBundle needs it.
So then... why didn't Composer just update both libraries? Because Composer is conservative: we told it to only upgrade knplabs/knp-paginator-bundle and it correctly figured out that it can't only upgrade that one package.
To fix this, run the command again but now add --with-dependencies:
Tip
We need this for our course CI, just ignore this note and follow the tutorial without executing these commands :)
sed -i 's/knp-paginator-bundle": "^2.7"/knp-paginator-bundle": "^5.0"/g' ./composer.json
composer update knplabs/knp-paginator-bundle --with-dependencies
This says: it's ok to upgrade knp-paginator-bundle and also any of its dependencies. This time... it did the trick: this upgrades from version 1 to 2 of knplabs/knp-components and from version 2 to 5 of knplabs/knp-paginator-bundle.
Checking Major Upgrade Changelogs
Awesome! Except... we need to be careful: these are major version upgrades... which means that they might contain "breaking" changes.
Go back to the GitHub homepage for KnpPaginatorBundle and look for a CHANGELOG.md file. Not every library will have this... but most do. Let's see: the breaking changes for version 3 were just removing support for old PHP versions. For version 4... it dropped support for old PHP and old Symfony versions... and for version 5, it added a return type to PaginatorAwareInterface... which is not something I'm using in my app.
So... we're good! You could repeat this for the knp-components library if you want, though since we're not using its code directly in our app, we should be good.
Ok, we've handled this knp_paginator deprecation. Next, let's update StofDoctrineExtensionsBundle to remove the rest of those pesky "tree" deprecations.
