Since its creation, JavaScript has always been focused on creating innovative User Experiences. It lets developers create the most intuitive and usable User Experience possible for a specific problem.

In practice however, building great User Experiences with JavaScript is difficult. It takes time to choose reliable packages, to configure them, to integrate them in your pages, and to make your front-end code interact with the rest of your infrastructure.

This problem is not new: it looks a whole lot like the state of Symfony in PHP before Symfony Flex. We need a Symfony Flex equivalent for JavaScript: a tool to build amazing User Experiences as quickly as we can now setup an HTTP client, a Mailer or an administration panel.

That's Symfony UX.

Symfony UX: building highly interactive applications by leveraging JavaScript giants

Symfony UX is a series of tools to create a bridge between Symfony and the JavaScript ecosystem. It stands on the shoulders of JavaScript giants: npm, Webpack Encore and Stimulus.

Symfony UX is not tied to any specific JavaScript framework: you can still use React, Vue or Angular if you love them. It is also opinionated, based on standard HTML and can be progressively adopted in existing applications.

Symfony UX consists of three main components:

  1. a Symfony integration for Stimulus to provide a new organization for JavaScript code in applications
  2. updates to Symfony Flex and Symfony Webpack Encore to automatically configure JavaScript code shipped by PHP packages
  3. a series of core UX packages designed to be reliable and composable to create amazing interfaces quickly

Example: displaying charts in PHP using Symfony UX Chart.js

Chart.js example in Symfony UX

A good example of the power of Symfony UX is the new Symfony UX Chart.js component. This component relies on the Chart.js library internally.

To use Symfony UX, first update your Symfony Flex and Webpack Encore dependencies:

1
2
composer update symfony/flex
yarn upgrade "@symfony/webpack-encore@^1.0.0"

And synchronize your recipes to the latest version:

1
composer recipes:install symfony/webpack-encore-bundle --force -v

Note

Synchronizing your recipes may override some code of your application. Check manually the result of the command to choose what to keep!

Once updated, Symfony Flex will react to each PHP package you install that contains JavaScript code. For instance, you can now install the Chart.js component:

1
$ composer require symfony/ux-chartjs
1
2
3
4
5
6
Using version ^1.0 for symfony/ux-chartjs
./composer.json has been updated

Synchronizing package.json with PHP packages
Don't forget to run npm or yarn to refresh your Javascript dependencies!
...

Symfony Flex has just synchronized the package.json file of your project with the Chart.js PHP package you installed. You will now find in this file a new JavaScript module:

1
2
3
4
5
6
7
// package.json
{
    "devDependencies": {
	    ...
        "@symfony/ux-chartjs": "file:vendor/symfony/ux-chartjs/Resources/assets"
    }
}

Symfony Flex also updated a new assets/controllers.json file in your project. This file references all the Stimulus controllers provided by installed Symfony UX packages to let Webpack Encore add them to your JavaScript built files:

1
2
3
4
5
6
7
8
9
10
11
12
// assets/controllers.json
{
    "controllers": {
        "@symfony/ux-chartjs": {
            "chart": {
                "enabled": true,
                "fetch": "eager"
            }
        }
    },
    "entrypoints": []
}

Because of these changes, you should now install the new JavaScript dependencies and compile the new files:

1
2
yarn install --force
yarn encore dev

And... that's it! By leveraging Symfony Flex, Symfony UX Chart.js was installed and configured both as a Symfony bundle in PHP, and as a JavaScript library compiled into your application's built files.

This means you can now build a chart using the bundle:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
// ...
use Symfony\UX\Chartjs\Builder\ChartBuilderInterface;
use Symfony\UX\Chartjs\Model\Chart;

class HomeController extends AbstractController
{
    /**
     * @Route("/", name="homepage")
     */
    public function index(ChartBuilderInterface $chartBuilder): Response
    {
        $chart = $chartBuilder->createChart(Chart::TYPE_LINE);
        $chart->setData([
            'labels' => ['January', 'February', 'March', 'April', 'May', 'June', 'July'],
            'datasets' => [
                [
                    'label' => 'My First dataset',
                    'backgroundColor' => 'rgb(255, 99, 132)',
                    'borderColor' => 'rgb(255, 99, 132)',
                    'data' => [0, 10, 5, 2, 20, 30, 45],
                ],
            ],
        ]);
    
        $chart->setOptions([/* ... */]);

        return $this->render('home/index.html.twig', [
            'chart' => $chart,
        ]);
    }
}

Once created in PHP, a chart can be displayed using Twig:

1
2
3
4
{{ render_chart(chart) }}

{# You can pass HTML attributes as a second argument to add them on the <canvas> tag #}
{{ render_chart(chart, {'class': 'my-chart'}) }}

All options and data are provided as-is to Chart.js. You can read
Chart.js documentation to discover them all.

Discover all the packages of Symfony UX on github.com/symfony/ux!

You can also read Fabien's keynote slides and Titouan's talk slides to get a full overview on the initiative!

Let's build an amazing ecosystem together

Symfony UX is an initiative: its aim is to build an ecosystem. To achieve this, we need your help: what other packages could we create in Symfony UX? What about a library that automatically adds an input mask to the text fields of your Symfony forms? Or the ability to make the EntityType render with AJAX auto-completion? Anything you do in JavaScript could be done streamlined as a UX package.

We have some ideas and we will release more packages in the coming days. The rest is on us: let's create an amazing ecosystem together!

Published in #Symfony