Skip to content

Athena::Framework::Bundle::Schema::FormatListener#

Configuration related to the ATH::Listeners::Format listener.

If enabled, the rules are used to determine the best format for the current request based on its Accept header.

ATH::Request::FORMATS is used to map the request's MIME type to its format.

Configuration Properties

enabled#

type:

Bool

default:

false

If false, the format listener will be disabled and not included in the resulting binary.

rules#

type:

Array(T)

default:

[]

The rules used to determine the best format. Rules should be defined in priority order, with the highest priority having index 0.

Example#

ATH.configure({
  framework: {
    format_listener: {
      enabled: true,
      rules:   [
        {priorities: ["json", "xml"], host: "api.example.com", fallback_format: "json"},
        {path: /^\/image/, priorities: ["jpeg", "gif"], fallback_format: false},
        {path: /^\/admin/, priorities: ["xml", "html"]},
        {priorities: ["text/html", "*/*"], fallback_format: "html"},
      ],
    },
  },
})

Assuming an accept header with the value text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8,application/json, a request made to /foo from the api.example.com hostname; the request format would be json. If the request was not made from that hostname; the request format would be html. The rules can be as complex or as simple as needed depending on the use case of your application.

This property consists of an array of objects with the following properties:

path#

type:

Regex | ::Nil

default:

nil

Use this rules configuration if the request's path matches the regex.

host#

type:

Regex | ::Nil

default:

nil

Use this rules configuration if the request's hostname matches the regex.

methods#

type:

Array(String) | ::Nil

default:

nil

Use this rules configuration if the request's method is one of these configured methods.

priorities#

type:

Array(String) | ::Nil

default:

nil

Defines the order of media types the application prefers. If a format is provided instead of a media type, the format is converted into a list of media types matching the format.

fallback_format#

type:

String | Bool | Nil

default:

json

If nil and the path, host, or methods did not match the current request, skip this rule and try the next one. If set to a format string, use that format. If false, return a 406 instead of considering the next rule.

stop#

type:

Bool

default:

false

If true, disables the format listener for this and any following rules. Can be used as a way to enable the listener on a subset of routes within the application.

prefer_extension#

type:

Bool

default:

true

Determines if the accept header, or route path _format parameter takes precedence. For example, say there is a routed defined as /foo.{_format}. When false, the format from _format placeholder is checked last against the defined priorities. Whereas if true, it would be checked first.