wellington meetup silverstripe 4 upgrading presentation (feb 2017)
TRANSCRIPT
Upgrading to SilverStripe 4Projects, modules, tips and tricks
22 Feb 2017 • Robbie Averill
● 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)
SilverStripe Roadmap
● Modules: now!
● Projects: now/soon (beta)
When should I upgrade?
Run a quick upgradability check!
Disclaimer: It's a QUICK check!gist.github.com/robbieaverill/cad0260414226645b404c45b2059fdf9
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
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" }}
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!
Namespacing and PSR-4People 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
Adding namespaces with upgrader
Implementing namespaces
Implementing PSR-4
Tip: don't forget to run composer validate!
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
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
● 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
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
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
● "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...
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
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
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.
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)
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
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
Useful links
● docs.silverstripe.org/en/4/changelogs/4.0.0
● github.com/silverstripe/silverstripe-upgrader
● github.com/robbieaverill/meetup-demo
● hub.github.com
● gist.github.com/robbieaverill/cad0260414226645b404c45b2059fdf9
