Symfony/Custom routes

From Aimeos documentation

Other languages:
English 100%

Routes are defined in the routing.yml of the Aimeos shop bundle and a set of standard routes is provided by default. Each route has at least a name, the corresponding path and some default parameter. At least the controller name is mandatory:

<route name>:
    path: <path of the route>
    defaults: { _controller: AimeosShopBundle:<controller name>:<action name> }

Each route creates links to one page of your application. The route names are important for the core library because the Symfony router needs their names for generating the correct routes for the given parameter.

Route names

The names of the standard routes are predefined in the routing.yml file. Besides the "admin" routes which are not listed here, their names are:

  • aimeos_shop_account ("my account" page for each user)
  • aimeos_shop_account_favorite (favorite products in "my account")
  • aimeos_shop_account_watch (watched products in "my account")
  • aimeos_shop_basket (standalone basket page)
  • aimeos_shop_count (product counts for the faceted search in JSON format)
  • aimeos_shop_detail (product detail page)
  • aimeos_shop_list (product list page)
  • aimeos_shop_session_pinned (pinned products in customer session)
  • aimeos_shop_suggest (list of products for search suggestions in JSON format)
  • aimeos_shop_stock (product stock information in JSON format)
  • aimeos_shop_checkout (standalone checkout process page)
  • aimeos_shop_confirm ("thank you" page after completing the order)
  • aimeos_shop_update (payment update notifications)
  • aimeos_shop_terms (terms and conditions page)
  • aimeos_shop_privacy (privacy policy page)

Adapt existing routes

For all existing routes, you can change its path and the default parameters by redefining the routes in the global app/config/routing.yml file using the same name. For example, to change the path of the "aimeos_shop_terms" to "/terms_and_conditions", you only need to use that path in the global routing.yml file:

  1. aimeos_shop_terms:
  2.     path: /terms_and_conditions
  3.     defaults: { _controller: AimeosShopBundle:Page:terms }

Similarly, changing the controller and action name to a custom one ("Terms" and "index") implemented in your application is done by adapting the "_controller" value in the "defaults" section of the route:

  1. aimeos_shop_terms:
  2.     path: /terms
  3.     defaults: { _controller: MyBundleName:Terms:index }

More details can be found in the Symfony routing documentation

Routes for multiple site, languages and currencies

Aimeos is able to manage many sites in one installation with different languages and currencies for each site. If you have such a setup with at least two sites, languages or currencies, you need to adapt your app/config/routing.yml file which contains these lines after installing the Aimeos Symfony bundle via composer:

  1. aimeos_shop:
  2.     resource: "@AimeosShopBundle/Resources/config/routing.yml"
  3.     prefix:   /

The line containing the "prefix" keyword can be used not only to add a fixed prefix string like "/shop" but also be changed to support these placeholders for the route definition:

  • {site} (unique site code from "code" field in the "mshop_locale_site" table)
  • {locale} (language ID from the "langid" field in the "mshop_locale" table)
  • {currency} (currency ID from the "currencyid" field in the "mshop_locale" table)

An example with site, language and currency would be:

  1. aimeos_shop:
  2.     resource: "@AimeosShopBundle/Resources/config/routing.yml"
  3.     prefix:   /{site}/{locale}/{currency}
  4.     defaults: { site: 'default', locale: 'en', currency: 'EUR' }

The parameters and values in the "defaults" line should be set if no values for the parameters are given via the URL. This prevents invalid links and creates links using the default values.

You can also reorder the placeholders the way you prefer like moving the "{locale}" placeholder to the front. If your shop doesn't use more than one site, language or currency, you can also leave out those placeholders. The Aimeos shop will automatically use the default values in this case. For the "site" parameter it's always "default" and for the language and currency the ones you've defined in the "Locale" tab of the administration interface. By changing the "prefix" to anything else than "/", you must also redefine the route definitions for the administration interface and add them to your routing.yml file too:

  1. aimeos_shop_admin_json:
  2.     path: /admin/do
  3.     defaults: { _controller: AimeosShopBundle:Admin:do }
  5. aimeos_shop_admin:
  6.     path: /admin/{site}/{lang}/{tab}
  7.     defaults: { _controller: AimeosShopBundle:Admin:index, site: default, lang: en, tab: 0 }

If you forget to do this, you will get an error when calling the administration interface as the placeholders can only be used once per route definition. Using e.g. the "{site}" placeholder in the "prefix" would then lead to a route definition like "/{site}/admin/{site}/{lang}/{tab}" which is invalid.

If you modify the "prefix" setting, you also have to adapt the authentication method patterns and the access control paths for the "MyAccount" page.

Add new routes

If you've implemented a new Aimeos core component which generates URLs to a new page, you have to add a new custom route. The route name can be freely chosen but for clarity, you should prefix it with "aimeos_shop_", e.g.

  1. aimeos_shop_mypage:
  2.      path: /new_page
  3.      defaults: { _controller: MyBundleName:Mycontroller:myaction }

The Aimeos core component now needs to know the name of the new route. It's then handed over to the Symfony router which will generate the correct URL using the available parameters. The route name must be configured in the app/config/config.yml file, e.g.

  1. aimeos_shop:
  2.     client:
  3.         html:
  4.             mycomponent:
  5.                 mypart:
  6.                     url:
  7.                         target: aimeos_shop_mypage

The "mycomponent" and "mypart" names must be replaced by the name of your Aimeos HTML client component and the part you've implemented.