bsRoutingPlugin

This plugin contains several bs*Route classes. Final two classes which should be used in routing.yml are bsHyperRoute and bsDoctrineHyperRoute.

These two classes extend all following classes and allows usage of all features. The extension chain is:

1. sfRequestRoute
2. bsCallbackRoute
3. bsI18nRoute
4. bsDynamicRoute
5. bsStarRoute
6. bsHyperRoute

Full featured example:

dictionary_lemma_list:
  url:           /__dictionary/:page_number/*
  class:         bsHyperRoute
  param:         { module: pcDictionaryLemma, action: list, page_number: 1 }
  requirements:  { page_number: '\d+', sf_method: [get, post] }
  options:
    dynamic:
      dictionary: { i18n: { callback: {function: "PageTable::getAllSlugsByPageRoute", params: [dictionary_lemma_list]}}}
    star:
      unknown_param: ignore # allow, ignore
      groups:
        dictionary_lemma_filter:
          dictionary_language_id: { i18n: ~, values_i18n: { callback: {function: "DictionaryLanguageTable::getAllSlugs"} } }
          reverse: { i18n: ~ , type: boolean}
          sort: { i18n: ~, values_i18n: { new: {en: new, cs: nove}, old: {en: old, cs: stare} } }
          dictionary_part_of_speech_id: { i18n: ~ }
          dictionary_categorys_list: { i18n: ~, values_i18n: { callback: {function: "DictionaryCategoryTable::getAllSlugs"} } }
          dictionary_lessons_list: { i18n: ~, values_i18n: { callback: {function: "DictionaryLessonTable::getAllSlugs"} } }
          dictionary_regions_list: { i18n: ~, values_i18n: { callback: {function: "DictionaryRegionTable::getAllSlugs"} } }

This route is parsed and processed only once and everything is cached in cache/[app]/[env]/config/config_routing.yml.php.

Routing classes

bsPatternRouting

This class extends sfPatternRouting and is used as default routing class in factories.yml.

This class adds all parameters from config key app_routing_global_url_params to all route classes. It is used e.g. in bsPersistentUrlParamsFilter to add popup parameters to url in backend in popup mode.

Route classes

bsCallbackRoute

This class replaces all callback keys in options array with values returned by callback function or method.

For example:

dictionary: { i18n: { callback: {function: "PageTable::getAllSlugsByPageRoute", params: [dictionary_lemma_list]}}}

will use php function call_user_func_array(‘PageTable::getAllSlugsByPageRoute’, array(‘dictionary_lemma_list’)) and the result after the callback can be:

dictionary: { i18n: { cs: slovnik, en: dictionary }}}

bsI18nRoute

This class deals with

1. culture detection from :sf_culture parameter or from host
2. generating urls for different cultures
3. i18n of strings in url pattern

It uses options:

i18n:
  detection: host # url or host
  hosts:
    en: [signs.zcu.cz, signs.zcu.czlocal]
    cs: [znaky.zcu.cz, znaky.zcu.czlocal]

to set how the culture detection or url generation for different cultures should be used. These options must be set for every route (but can be set for all routes globally in bsHyperRoute).

If detection is set to host then the :sf_culture parameter is not included in url and the culture is detected from hosts specified in hosts key.

If detection is set to url then the :sf_culture is automatically prepended to url pattern. Enabled languages can be limited by enabled_cultures option.

This class contains protected method applyI18n which handles i18n strings in url. This method is used by other route classes. Translation catalogue for these strings is handled by bsQuickTranslation class which stores translations in sfConfig options, e.g.:

all:
  quick_translation:
    routing:
      dictionary_lemma_filter:
        dictionary_language_id: { cs: jazyk, en: language }
        reverse: { cs: opacne, en: reverse }
        dictionary_categorys_list: { cs: kategorie, en: kategorie }
        dictionary_regions_list: { cs: region, en: region }

quick_translation defines section for catalogue used by bsQuickTranslation, routing is a namespace (bsQuickTranslation can be used not only for routing), and dictionary_lemma_filter is a group name.

If the translation is not found in specified namespace then bsQuickTranslation tries to find translation in default namespace.

This class doesn’t translate strings in url directly but provides methods which are used by other route classes.

bsDynamicRoute

This class uses bsI18nRoute to translate “dynamic” url parts prefixed by __, e.g.:

url:           /__dictionary/:page_number/*
options:
  dynamic:
    dictionary: { i18n: { cs: slovnik, sk: slovnik }}

This segment __dictionary in the url pattern will be replaced by a string which is defined in corresponding dynamic option in i18n section. If no translation is found then the prefix __ is removed and dictionary is used in url as a default.

bsStarRoute

This class handles “star” parameters, e.g.:

dictionary_lemma_list:
  url:           /__dictionary/:page_number/*
  options:
    star:
      unknown_param: ignore # allow, ignore
      groups:
        dictionary_lemma_filter:
          dictionary_language_id: { i18n: ~, values_i18n: { callback: {function: "DictionaryLanguageTable::getAllSlugs"} } }
          reverse: { i18n: ~ , type: boolean}
          dictionary_part_of_speech_id: { i18n: ~ }
          dictionary_categorys_list: { i18n: ~, values_i18n: { callback: {function: "DictionaryCategoryTable::getAllSlugs"} } }

If unknown_param is set to ignore then all parameters passed to url_for() which are not specified in options are ignored. If set to allow then all parameters which are not specified in options are added to url by symfony without any processing.

The parameters are divided into named groups (here e.g. dictionary_lemma_filter). They have no influence for resulting url.

Star parameters can be of type boolean or default one. Boolean star parameters have no value, they are in url (then the value is true) or not (then the value is false). In example see reverse parameter.

Other star parameters (non-boolean) consist of key and value (as in symfony). The keys can be translated (see i18n options, which are empty here, but this i18n array will be populated later by default values). The values can be translated too (see values_i18n in example, where translations are populated by a callback).

bsHyperRoute

This is final class which should be used in routing.yml.

It adds only handling of default options, which are specified in sfConfig for every app:

routing:
  default_options_frontend:
    i18n:
      detection: host # url or host
      hosts:
        en: [signs.zcu.cz, signs.zcu.czlocal]
        cs: [znaky.zcu.cz, znaky.zcu.czlocal]
  default_options_backend:
    i18n:
      detection: url # url or host
      enabled_cultures: [cs, en]

These options from sfConfig are merged to route options. Because of this it’s not necessary to repeat these “global” options for every route.

This functionality is similar as in bsPatternRouting but there the options are processed just-in-time, here these options are compiled and cached for every route.