exception_handler: A Ruby repository from Startouf

Custom 404 & 500 production error pages for Rails 4 & 5.

Responsive Branded Error Pages Middleware Exception Handling Fully Customizable

New Controller New Middleware Full Test Suite Fully Rails 4 & 5 Compatible

Brand new controller & middleware have made ExceptionHandler even more powerful & efficient. Now you can use ExceptionHandler with a single click → plug and play custom exception pages:

For over 3 years, ExceptionHandler has provided production-level Rails exception handling for 4xx and 5xx errors:

Since browsers only read 4xx & 5xx error codes, all Rails exceptions have to be inferred. Thus, ExceptionHandler simply has to manage how the 4xx / 5xx errors are passed to the browser.

Unlike other gems, ExceptionHandler uses a custom controller to build an @exception object. This allows us to save the exception, email it or do anything else we may need. The gem has already been a massive success and we continue to actively maintain it.

Now you can try for yourself ...

The secret lies in config.exceptions_app ↴

config.exceptions_app sets the exceptions application invoked by the ShowException middleware when an exception happens. Defaults to ActionDispatch::PublicExceptions.new(Rails.public_path)

Each time an exception is raised, ShowExceptions takes the request and forwards it to config.exceptions_app. This is expected to return a response - allowing us to inject a controller:

Because our callback maintains the request, we are able to do whatever we need before serving a response. This is a major advantage over the "default" (routes). The routes invokes Rails twice and does not persist the request.

ExceptionHandler is the only gem to provide middleware-powered exception handling. It populates our custom view with details, giving us the ability to maintain branding when exceptions are raised:

ExceptionHandler is the most EFFECTIVE and EFFICIENT gem to handle exceptions in Rails.

Once invoked, its model, controller and views work together to serve the best responses to Rails errors ...

Custom Rails Error Pages - ZERO configuration needed:

You can install it from the CLI or Gemfile - it will AUTOMATICALLY run in production.
↓ To run in development, use dev mode ↓

If you want to set it up your way, you can use these features...

Cinfiguration Options Config Dev Dev Database Email Email Views Views Locales Locales Custom Exceptions Generators

Config

From 0.4.7, ExceptionHandler manages its config from the central Rails config hash:

If you're using an engine, you don't need to use an initializer:

# lib/engine.rb
module YourModule
  class Engine < Rails::Engine

    # => ExceptionHandler
    # => Works in and out of an initializer
    config.exception_handler = {
      dev: false,
      db:  true
    }
  end

end

You only need to provide the inputs you want, for example:

# config/application.rb
config.exception_handler = { dev: true }

# config/environments/production.rb
config.exception_handler = { social: { fusion: "flutils" }}

Dev Mode

To enable ExceptionHandler in dev, enable the dev option:

This disables config.consider_all_requests_local, making Rails behave as it would in production:

Database

We also have ActiveRecord integration.

If you want to save your exceptions to db, you need to enable the db config option:

# config/application.rb
config.exception_handler = {
  db: true
}

This enables ActiveRecord::Base on the Exception class, allowing us to save to the database.

In order for this to work, your db needs the correct table.

To do this, once you've enabled the option, run rails db:migrate from your console. Our new migration system will automatically run the migration.

Email

ExceptionHandler also now sends email notifications.

If you want to receive emails whenever your application raises an error, you can do so by adding your email to the config:

# config/application.rb
config.exception_handler = {
  email: "your@email.com"
}

Please Note this requires ActionMailer. If you don't have any outbound SMTP server, SendGrid is free.

Full tutorial here

Views

From 0.7.0, we overhauled the view system:

Wiew is modular - @exception populated with locales.

Locales

0.7.5 introduced locales ...

[[ locales ]]

The ExceptionHandler view is populated by @exception.description, which pulls from the locales.

If you want custom messages, you need the following. The key is defined by the HTTP status_code

# config/locales/en.yml
en:
  exception_handler:
    not_found: "Your message here"
    unauthorized: "You need to login to continue"
    internal_server_error: "This is a test to show the %{status} of the error"

You get access to %{message} and %{status}, both inferring from @exception.

Layout

The layout has also been improved ↴

We now assign layouts to the status code of the response:

By default, 5xx errors are shown with our exception layout - this can be overridden by changing the config to use a layout of your choice. If you want to inherit the ApplicationController layout, assign the codes to nil.

Custom Exceptions

Custom Exceptions also supported in 0.7.5

Rails handles this for us - config.action_dispatch.rescue_responses ↴

You need to add to the rescue_responses hash in your app's config (mapped to status codes):

# config/application.rb
config.action_dispatch.rescue_responses["ActionController::YourError"] = :bad_request

Because HTTP can only process 4xx / 5xx errors, if Rails raises an exception, it needs to assign one of the error status codes. Default is internal_server_error - if you'd prefer your app to just return 500 errors for your custom exception, you don't need to explicitly declare them.

Generators

You can generate ExceptionHandler into your own application.

[[ Generator ]]

The following commands will copy the directories...

rails g exception_handler:views
rails g exception_handler:views -v views
rails g exception_handler:views -v controllers
rails g exception_handler:views -v models
rails g exception_handler:views -v assets
rails g exception_handler:views -v views controllers models assets

If you don't include any switches, this will copy all the folders put into your app.

Each switch defines which folders you want (EG -v views will only copy views dir).

Migrations (deprecated)

From 0.7.5, the migration generator has been removed in favour of our own migration system

You don't need to generate a migration any more.

If you set the db option in config, run rails db:migrate and the migration will be run.

To rollback, use the following:

rails db:migrate:down VERSION=000000

The drawback to this is that if you remove ExceptionHandler before you rollback the migration, it won't exist anymore. You can only fire the rollback when you have ExceptionHandler installed.

Support

Issues

Changelog

0.7.5

HTTP status layouts

New config system
Fixed controller layout issues
Streamlined middleware
New layout & interface

ExceptionHandler is now the leading custom error pages gem for Rails.
No other gem is as simple or effective at providing beautiful exception pages in production.

Download Here

Startouf/exception_handler