TYPO3 v9’s New Extension Scanner Makes Planning Upgrades Easier
One beauty of an open source CMS like TYPO3 is how it enables you to create tailored solutions on top of an extensible code base, which is constantly being improved in each successive version. The new Extension Scanner included with TYPO3 v9 helps you analyze websites and applications to better plan and estimate upgrades to keep up with those improvements. It’s a timesaver in terms of getting all the information you need in one place to make a more accurate estimate. And there’s a standalone scanner for older versions, too! It is the perfect compliment to our project review service, which provides a quality assessment and can help you make your sites more secure, performant, and scalable.
The TYPO3 Extension Scanner—standalone or built into v9 core—provides dedicated documentation for every change from version 7 to 8, and from version 8 to 9 (and the most important changes from version 6 to 7). It says what was changed, the issue number, and it gives an idea of what is important to be aware of in the change in terms of fixing and preparing for an upgrade.
From one upgrade to the next, TYPO3’s APIs improve and new features are added at the same time as old methods are deprecated. This does mean that upgrades have to be carefully planned. To get ready for one, you have to inspect the code base to plan what work needs to be done.
The Extension Scanner provides a status check on custom code like extensions. It helps developers identify calls to outdated or deprecated methods. The Extension Scanner helps create a more accurate estimate of the work, time (and therefore money) an upgrade might cost. For example:
The Extension Scanner could identify a task that takes you 30 seconds to fix, and you might find you have 100 such tasks.
It also might happen that functionality has been deprecated and removed and you need to rewrite to migrate to something new and making those changes will likely involve hours of work. For instance, the Extension Scanner might reveal calls to legacy and deprecated database API (TYPO3_DB). Now we have a QueryBuilder in place.
The Extension Scanner will tell you things like whether the APIs in use are all up-to-date. It doesn't evaluate quality such as faults in the software architecture—code organization; how much it has been extended or modified, and so on. However, the Extension Scanner does provide information to help you make a qualified value judgment.
In addition to helping out with upgrades, the Extension Scanner will also be useful when you transfer a project between developers. No matter how experienced we are as developers, none of us have the full CMS feature set in our heads. You might run across some uncommon scenario for the very first time in a project. Now you can get a pointer to exactly where the solution is in the source code, and what needs to be changed.
Overall, having the Extension Scanner in place will be a time saver compared to how it was before.
I’ve noticed an overall design trend in the last few years since TYPO3 v8 and now with v9—the core itself can deliver the bulk of most projects. People use and configure core as much as possible, for everything from handling image management to contact forms. They use fewer third-party extensions than they used to, usually only a few per project. Then, to create project-specific functionality, they write their own implementation and logic. So essentially, the bulk of a TYPO3 upgrade project will involve updating custom code.
I like upgrading TYPO3 sites. It’s a straightforward process, now made even better. To start the upgrade, replace TYPO3 core and follow the steps to prepare your installation. Then go directly to the Upgrade Wizard (part of the Install Tool) by calling its URL and let it walk you through the necessary steps.
When you're done with the migration part in the Upgrade Wizard, go to the website front end and open it. If it works, GREAT. If it doesn’t work ... you might have a problem. In a nutshell, the next few steps would be checking deprecation and error logs, adjusting source code and configuration, executing all test suites and completing the whole process with manual test plans.
Before the Extension Scanner, that was where the workflow led to for upgrading custom code. You checked what worked, found what was broken, and fixed it. In the past, you could access the documentation of changes from the TYPO3 CMS Changelog or the “What’s new” slides, but it was up to you to identify what was relevant for your particular project. Now, the Extension Scanner helps you identify what most likely needs to be fixed.
Access the Extension Scanner by going to the Install Tool > Module "Upgrade" > "Scan Extension Files.” When you click “Scan All”, the scan begins.
The results report what you should look at in a defined color scheme:
Red means usage of breaking or removed code has been detected.
Orange means that usage of deprecated code has been detected.
Green means the code is fine and no faults have been found.
When you drill down you’ll see another indicator, whether or not it’s a “strong” or “weak” match. A strong match means it’s highly likely you need to make a change. As Christian Kuhn explains in the video below, “Quickly looking at the code will tell you [if] it’s not a true match.”
Keep in mind the Extension Scanner is a helper, and the documentation explains the caveats and how it works. The Extension Scanner is based on static program analysis and because of that, false positives and negatives are impossible to avoid. For example, if your custom code includes the same string as a property that has been deprecated, it will be marked as deprecated. But that does help you identify and make the changes needed to avoid this problem the next time! After you make your changes, you can rescan your project.
In this video, Christian “Lolli” Kuhn demonstrates how the Extension Scanner works. This was in the earliest version of TYPO3 v9; the user interface has changed a little since then.
The Extension Scanner in TYPO3 v9 core only includes information about changes between v8 and v9. You’re probably wondering about upgrading from earlier versions of TYPO3? TYPO3 v7 is moving to ELTS, now is a good time to be planning that upgrade.
I’ve released the scanner as a stand-alone tool and we’ve made it work for other versions. At the time of writing this article, core still uses its own implementation. This package on GitHub should become the official Extension Scanner, and core will make use of that in time.
When the Extension Scanner first came out, I was working on TYPO3 GmbH’s Project Review service. During project reviews, we don’t manually comb through each project’s source code, we built tools to help automate the reviews. These tools also evaluate quality, such as the size of your code classes and how coupled they are to other components.
You can download the result of an example project review here if you’re curious how those work.
My main motivation in extracting the scanner from TYPO3 core and making it work as a standalone was numerous requests from agencies to evaluate how much would it take to upgrade projects from v6 to v9 or v7 to v8. And what about upgrading version 8 to version 10 (when it’s released)?
To build it, my colleagues went through all the changes that happened between v7 and v8. To handle version 6, we only included the important changes that developers had to do. For every change, they linked a dedicated documentation file. This says what was changed, the issue number, and it gives an idea of what is important to be aware of in the change in terms of fixing or preparing for upgrade.
Find the Extension Scanner for older versions of TYPO3 on Github.
Afterward, Michiel Roos used that to make the console version of the Extension Scanner, available on GitHub. His tool is ideal for people who prefer a command-line interface.
For the next steps, we’d love to see a PHPStorm plugin which would make use of the Extension Scanner, and give a better picture of how the code works by identifying what is connected. That would eliminate the weak matches. So if you know how to write IntelliJ plugins, contact us!
The custom code you write on top of TYPO3 is what makes it an ideal government portal in one case and an attractive travel site in another. To keep pace with the developments in browsers and web trends, each version of TYPO3 introduces new features, and deprecates others. Estimating and planning upgrades is part of moving forward to update and improve your websites and applications.
TYPO3 v9 is the best release of TYPO3 yet. Okay, okay ... we might say that with each new version, but we’re really excited about where TYPO3 is heading. The time to update and upgrade your sites is now. The Extension Scanner will help you plan your work.
The Extension Scanner came out early in the release process with TYPO v9.0. But I can’t speculate if the Extension Scanner helped because we don’t have usage data (yet). Anecdotally, I have the feeling the adoption rate is better with TYPO3 v9. And they were making real websites that were live already even before the LTS release. If you’ve used the Extension Scanner to help upgrade, we’d love to hear about it in the comments.
Need any help upgrading your sites or evaluating projects? Try TYPO3 v9’s Extension Scanner. Contact us to help you modernize your sites with a project review.
December 21st, 2018
Hey Oliver, Thanks for writing an excellent article on a scanner. Indeed, Scanner is one of the wonderful features of TYPO3 v9, just like heaven for TYPO3 developer during upgrade TYPO3 project. Suggestion In future, it would be great to integrate 'code quality review' kind of feature within TYPO3 core. We can consider finding bad smell code by checking PHP and TYPO3 Standards. In this automation of code review, we can save lots of time to check each code manually; I hope you understand what I mean. Example like; - https://www.sonarqube.org/ - https://ter-sonarqube.marketing-factory.de/projects?sort=-analysis_date Thank you very much for dedication and efforts to the TYPO3 community :) Cheers, Sanjay
December 20th, 2018
I am using the new scanner already for a while, it can be indeed a great time saver. Thumbs up, also for the video.