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¶

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@^0.32.0"

And synchronize your recipes to the latest version:

1

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

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,
                "webpackMode": "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,
        ]);
    }
}

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!

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!