Tips and tricks for upgrading to SilverStripe 4, as of February 2017
Links:
- gist.github.com/robbieaverill/cad0260414226645b404c45b2059fdf9
- hub.github.com
- github.com/silverstripe/silverstripe-upgrader
- php-fig.org/psr/psr-2
- github.com/Seldaek/monolog
- docs.silverstripe.org/en/4/changelogs/4.0.0
- github.com/robbieaverill/meetup-demo
2. ● PHP namespaces
● Bootstrap 4 in the CMS
● ReactJS
● Public API changes - lots of them
● Quirks! E.g. dotenv
● PSR-2 style guidelines
● Controller naming: Page_Controller -> PageController
● Config API is changing! Still to come...
SilverStripe 4 Changes
(That generally affect you: a developer)
5. Run a quick upgradability check!
Disclaimer: It's a QUICK check!
gist.github.com/robbieaverill/cad0260414226645b404c45b2059fdf9
6. Projects: fork and fix!
Get involved with the open source community. It might
be a quick job, you might be surprised!
Suggested tools:
● Hub: hub.github.com
● silverstripe/upgrader:
github.com/silverstripe/silverstripe-upgrader
7. Composer
● List your forks as VCS repositories until merged
● Projects: "minimum-stability": "dev" and
"prefer-stable": true
● "extra": {
"branch-alias": {
"dev-master": "2.x-dev"
}
}
8. Modules: Get into it, now!
● The more SilverStripe 4 compatible a module is, the
more likely you and other developers will use it, and
recommend it for use to those you work for
● Upgrading a module will give you a much deeper
understanding of how it works, especially if you didn't
write it!
9. Namespacing and PSR-4
People asked, SilverStripe responded. Please welcome namespacing to the
stage!
With it comes PSR-4 compatible autoloading, which makes sense.
● Use "git mv" to configure your module for PSR-4
compatibility without losing history
● Add and implement namespaces with the upgrader
● Do these in separate commits/PRs from PSR-2 linting
13. The framework has switched to using dotenv for configuration. It's worth
mentioning now, because you won't be able to "build" without it.
File: .env
Hello dotenv, bye bye _ss_environment
14. In SilverStripe the suggested PHP style guideline to follow is
PSR-2 (which includes PSR-1).
This means spaces for indentation, brackets on new lines,
sensible spacing, etc.
You can automate most of the required changes using PHP
CodeSniffer and the PSR2 standard it ships with.
More info: php-fig.org/psr/psr-2
PHP style guidelines: PSR-1/2
15. ● In 3.x: Page_Controller
● In 4.x: PageController
Don't forget to add this to the .upgrade.yml mapping!
Move the controller to its own file now - PSR-2 requires each
class to be on its own.
Naming controllers
16. In SilverStripe 3.x you can mostly put templates wherever
you feel like.
With 4.x things are stricter:
● Default: fully qualified template location matches class
namespace
● ->renderWith('TemplateName'): still looks in root
of "templates"
SilverStripe encourages the use of fully qualified template
locations where possible, even if you don't have to move
them when you upgrade!
Naming templates
17. DataObject table names
By default a namespaced DataObject will use a backslash in the table name,
matching the namespace. To replace this, or to provide backwards compatibility,
specify private static $table_name = 'MyTableName'; on your
DataObject.
BuildTask segments
BuildTasks will use a fully qualified class name (sanitised) for the segment. You
may see dev/tasks/Robbie-MeetupDemo-Task-DoesNothingTask. To
make this simpler, add private static $segment =
'DoesNothingTask'; to your task.
Small gotchas
18. ● "ClassName" value remapping
When working with existing data (i.e. upgrade, not fresh install), if your
DataObject has a ClassName field, it will need to become fully qualified in
legacy date. Use YAML config - see the CMS module for an example.
● php-intl extension is now required
● Upgrader bugs:
Still in development too - it will occasionally replace things it shouldn't.
Doesn't update YAML configuration files (yet). This also applies to YAML
fixtures in unit test - they must be fully qualified!
More gotchas...
19. Handling files, or whatever
● Asset abstraction provides secure assets out of the
box as well as versioning and coupling with
campaigns
● The upload process changes
● The image manipulation public API has changed a
bit
● Take a look at the changelog
20. Mono-Logging!
SS_Log is still available, but it's deprecated - you shouldn't
and probably can't use it.
Instead, use Monolog (PSR-3 compatible) via the Injector:
More: github.com/Seldaek/monolog
21. Cascading themes!
As very cool feature - now you can have multiple themes
that inherit from each other! This includes looking up
resources by their base filename across any registered
theme.
22. Deprecation and removals
● All deprecation and removals are documented in the
4.0.0 changelog, which is kept up to date
● If your code complains, check for updates
● Some important backends have been updated or
replaced entirely: logging, config (shortly), localisation,
cache (soon)
23. Considerations
● Entwine being phased out in favour of ReactJS (CMS)
● Use Webpack or similar for bundling assets
● REST API modules replaced with core GraphQL
● RestfulService gone, use guzzlehttp/guzzle or similar
● Use the injector wherever you can
24. General tips
● Good unit test coverage to start with will help a lot
● Start namespacing early if you can (SS3 can handle it, to
an extent)
● Use the upgrader tool
● Bump your branch alias
● Release alpha tags for your upgraded code
