usage.rst

Usage

In applications not using webpack add these two lines in your layout:

With Twig:

<script src="{{ asset('bundles/fosjsrouting/js/router.min.js') }}"></script>
<script src="{{ path('fos_js_routing_js', { callback: 'fos.Router.setData' }) }}"></script>

With PHP:

<script src="<?php echo $view['assets']->getUrl('bundles/fosjsrouting/js/router.js') ?>"></script>
<script src="<?php echo $view['router']->generate('fos_js_routing_js', array('callback' => 'fos.Router.setData')) ?>"></script>

Note

If you are not using Twig, then it is no problem. What you need is the two JavaScript files above loaded at some point in your web page.

If you are using webpack and Encore to package your assets you can use the webpack plugin included in this package

const FosRouting = require('fos-router/webpack/FosRouting');
//...
Encore
  .addPlugin(new FosRouting())

Then use it simply by importing import Routing from 'fos-router'; in your js or ts code

The plugin hooks into the webpack build and watch process and triggers the fos:js-routing:dump command automatically, once routes have been changed.

To avoid that, e.g. when building the frontend on a machine or docker image/layer, where no PHP is present, you can configure the plugin to use a static dumped routes.json and suppress automatic recompilation of the file, by passing some options to the plugin:

const FosRouting = require('fos-router/webpack/FosRouting');
//...
Encore
    .addPlugin(new FosRouting(
        { target: './assets/js/routes.json' }, // <- path to dumped routes.json
        false // <- set false to suppress automatic recompilation of the file
        )
    )

Alternatively you can use the dump command and export your routes to json, this command will create a json file into the public/js folder:

bin/console fos:js-routing:dump --format=json --target=assets/js/routes.json

If you are not using Flex, probably you want to dump your routes into the web folder instead of public, to achieve this you can set the target parameter:

# Symfony Flex
bin/console fos:js-routing:dump --format=json --target=web/js/fos_js_routes.json

Then within your JavaScript development you can use:

const routes = require('../../public/js/fos_js_routes.json');
import Routing from '../../vendor/friendsofsymfony/jsrouting-bundle/Resources/public/js/router.min.js';

Routing.setRoutingData(routes);
Routing.generate('rep_log_list');

Generating URIs

It's as simple as calling:

Routing.generate('route_name', /* your params */)

Or if you want to generate absolute URLs:

Routing.generate('route_name', /* your params */, true)

Assuming some route definitions:

With attributes:

// src/AppBundle/Controller/DefaultController.php

#[Route(path: '/foo/{id}/bar', name: 'my_route_to_expose', options: ['expose' => true])]
public function indexAction($foo) {
    // ...
}

#[Route(path: '/blog/{page}', name: 'my_route_to_expose_with_defaults', options: ['expose' => true], defaults: ['page' => 1])]
public function blogAction($page) {
    // ...
}

With YAML:

# app/config/routing.yml
my_route_to_expose:
    pattern: /foo/{id}/bar
    defaults: { _controller: AppBundle:Default:index }
    options:
        expose: true

my_route_to_expose_with_defaults:
    pattern: /blog/{page}
    defaults: { _controller: AppBundle:Default:blog, page: 1 }
    options:
        expose: true

With annotations (deprecated):

// src/AppBundle/Controller/DefaultController.php

/**
 * @Route("/foo/{id}/bar", options={"expose"=true}, name="my_route_to_expose")
 */
public function indexAction($foo) {
    // ...
}

/**
 * @Route("/blog/{page}",
 *     defaults = { "page" = 1 },
 *     options = { "expose" = true },
 *     name = "my_route_to_expose_with_defaults",
 * )
 */
public function blogAction($page) {
    // ...
}

You can use the generate() method that way:

Routing.generate('my_route_to_expose', { id: 10 });
// will result in /foo/10/bar

Routing.generate('my_route_to_expose', { id: 10, foo: "bar" });
// will result in /foo/10/bar?foo=bar

$.get(Routing.generate('my_route_to_expose', { id: 10, foo: "bar" }));
// will call /foo/10/bar?foo=bar

Routing.generate('my_route_to_expose_with_defaults');
// will result in /blog/1

Routing.generate('my_route_to_expose_with_defaults', { id: 2 });
// will result in /blog/2

Routing.generate('my_route_to_expose_with_defaults', { foo: "bar" });
// will result in /blog/1?foo=bar

Routing.generate('my_route_to_expose_with_defaults', { id: 2, foo: "bar" });
// will result in /blog/2?foo=bar

Moreover, you can configure a list of routes to expose in app/config/config.yml:

# app/config/config.yml
fos_js_routing:
    routes_to_expose: [ route_1, route_2, ... ]

These routes will be added to the exposed routes. You can use regular expression patterns if you don't want to list all your routes name by name.

Note

If you're using JMSI18nRoutingBundle for your internationalized routes, your exposed routes must now match the bundle locale-prefixed routes, so you could either specify each locale by hand in the routes names, or use a regular expression to match all of your locales at once:

# app/config/config.yml
fos_js_routing:
    routes_to_expose: [ en__RG__route_1, en__RG__route_2, ... ]

# app/config/config.yml
fos_js_routing:
    routes_to_expose: [ '[a-z]{2}__RG__route_1', '[a-z]{2}__RG__route_2', ... ]

Note that Symfony 4.1 added support for internationalized routes out-of-the-box.

You can prevent to expose a route by configuring it as below:

# app/config/routing.yml
my_very_secret_route:
    pattern: /admin
    defaults: { _controller: HelloBundle:Admin:index }
    options:
        expose: false

Router service

By default, this bundle exports routes from the default service router. You can configure a different router service if needed:

# app/config/config.yml
fos_js_routing:
    router: my_router_service

HTTP Caching

You can enable HTTP caching as below:

# app/config/config.yml
fos_js_routing:
    cache_control:
        # All are optional, defaults shown
        public: false   # can be true (public) or false (private)
        maxage: null    # integer value, e.g. 300
        smaxage: null   # integer value, e.g. 300
        expires: null   # anything that can be fed to "new \DateTime($expires)", e.g. "5 minutes"
        vary: []        # string or array, e.g. "Cookie" or [ Cookie, Accept ]