RFC-2 Move ErrorPage in to optional module

Author: @jonom Status: Pending review Version: 1.2.2 (2016-03-20)

Purpose and outcome

This RFC aims to address a few issues with the current state of error page responses and error page content management in SilverStripe CMS:

1. Flaws Statically generated error pages are under-utilised and go stale quickly.
2. Inflexibility ‘Error content’ management is not a requirement for many websites, and a different approach may be preferred where it is.
3. Confusion The ErrorPage content management model leads to a confusing CMS experience.

Since the current ErrorPage implementation is suitable for some sites but not all, this proposal recommends removing the ErrorPage class from core and moving it in to a separate optional module. This would extend upon a simpler error response model in core, and pave the way for developers to create alternate solutions for managing, displaying, and caching error response content that suits their needs better.

Community is welcome to give feedback. The proposal will be submitted to the core-committers for approval.

Motivation

Static error pages easily become stale and broken

They are generated on dev/build but only if they don’t already exist. After that they are only regenerated when re-published from the CMS. This means the static pages can easily become very out of date, and even include dev-environment content rendered when the website project was first initiated.

Static error pages are not widely utilised

On a regular SilverStripe installation directives in the .htaccess file suggest that error responses will be handled efficiently by Apache serving up a static error page. This is true for a 500 response, but all 404 responses in fact go through the full SilverStripe request cycle and a dynamic error response is generated, meaning the static 404 file is never used. In the case of a fatal error Apache serves the 500 error page because PHP has aborted the response. Hopefully this situation doesn’t happen often, but when it does it is likely that a stale error page is being served.

Inflexible error response model

• The use of ErrorPage content removes the ability to set a custom error message from code using ContentController::httpError($code, $message) ($message is ignored)
• Error responses which don’t have a corresponding ErrorPage published in the CMS will show the content for a 500 Server Error which is misleading.
• Static error pages are only generated for the default language (can anyone confirm this?) and primary Subsite.

ErrorPages confuse regular (non-technical) CMS users

• It doesn’t make sense to show error pages in the Site Tree and allow drag and drop re-ordering, since they aren’t part of a website’s menu structure or information architecture.
• Non-technical CMS users are generally not interested in editing error page content
• Non-technical CMS users read the labels in the Site Tree and think something has gone wrong, not making the connection that there is content there they can edit

Proposal

Remove ErrorPage from core and split off in to an optional module

The ErrorPage class brings with it some UX problems and flaws as outlined above, and is not needed in every CMS installation, so let’s separate it out in to an optional module. This will make the CMS experience simpler and cleaner for users who don’t need this functionality.

Provide a simple error response mechanism that can be overridden or replaced

RequestHandler::httpError() already provides a plain-text error response with default descriptions for a range of status codes, with extension points that allow you to customise the response to your liking. This means we already have a good base in place that can be built upon with modules. It may make sense to modify this base to provide a branded error page by default, using a site’s Page.ss templates.

Don’t cache error page content by default

We’re not effectively caching error page content at the moment and don’t have built-in caching for any other content so let’s leave that functionality to dedicated modules.

(Except for the 500 error page)

We can’t serve up a dynamically generated response in the event of a fatal error, so let’s provide a simple static html page for this purpose. This could be manually replaced or customised if desired to match the look of the website. This may not be ideal for all websites but it is just a starting point that can be expanded upon with modules.

Other considerations

• This RFC does not propose any solutions for fixing existing problems with ErrorPage for developers that choose to go on using it as a module. Upgrades to that module would be a good idea but are out of scope for this RFC.
• Who will be responsible for maintaining the ErrorPage module? (SilverStripe Ltd?)
• Document upgrade path
  • install ErrorPage module or remove ErrorPage instances)
  • recommend some alternative modules and pros/cons if/when available
• Update docs
• Should Installer require ErrorPage as a dependancy or a simpler alternative?

(Partial) Alternatives

Fix generation of static error pages

• How do we ensure error pages are regenerated regularly? dev/build is not done regularly and a basic SilverStripe installation doesn’t currently require cron jobs to be set up. Generating and caching pages at request time may be an option.
• How will we know we need to serve up a static 404 without going through the request process and hitting the database? If we can’t solve this problem any performance gains to be made by saving a static error page will be similar to serving up a 404 page that has been cached using partial caching.
• How to support multi-domains, translation, SSL vs non-SSL…?

These are difficult questions to answer so this doesn’t seem like a good solution.

Separate out error pages from SiteTree

ErrorPages could be visually separated at the bottom of the SiteTree, or moved to the Settings section of the CMS, to reduce confusion and clutter. However if most websites don’t actually need the ability to edit error page content in the CMS, and we’re adhering to ‘Convention over Configuration’ then this functionality should be optional in the form of a separate module.

Impact

• The ErrorPage module will need to be installed on websites where that functionality is required, including:
  • Websites that rely on a fully-themed 500 error response
  • Websites that are making use of the static 404 page (non-standard configurations)
• If the ErrorPage module is not installed, developers will likely want to install an alternative module or implement their own solution to enhance error responses beyond plain-text.