DEV Community: Abdouni Abdelkarim

Handle your Symfony assets without WebpackEncoreBundle, ViteBundle or AssetMapper

Abdouni Abdelkarim — Wed, 08 Jan 2025 22:53:10 +0000

A little context

You actually need to handle assets in your Symfony application and you don't know how to do this ?

I'm gonna show you here one way, without using WebpackEncoreBundle, ViteBundle or AssetMapper.

However, this is not the best way to handle assets with Symfony, but maybe it's the easiest one.

So, why are you showing us this way ? 🤔

Because... sometimes, you can need to handle assets this way, for example:

you don't have many time and can't wait to learn AssetMapper
you are a young symfony developer and you don't want to spend too much time learning frontend tools like Webpack or Vite
you have a wonderful legacy project and need to migrate it step by step
you just have a few frontend assets and don't want to use a more robust solution

Create a Symfony project

Let's start by creating a fresh new Symfony project executing this command:

symfony new --webapp symfony-handle-assets

If you don't have the Symfony CLI binary, you can install it from here.
But if you don't want, you can also create a Symfony project by using Composer.

Remove Symfony AssetMapper files

We're gonna start by... removing some files.
Yeah, actually we don't need the files installed for AssetMapper, so we're gonna delete them.
But before, start by removing these libraries:

composer remove symfony/asset-mapper symfony/ux-turbo symfony/stimulus-bundle

Delete also the assets directory.
Congrats, you did it 🎉

Now, get back on our subject.💪

Our first Controller

Start the Symfony webserver by running:

symfony serve -d

Create now a new Symfony Controller by using the Symfony MakerBundle with this shiny command:

./bin/console make:controller

I named this controller FrontController, but you can name it whatever you want. I choose to not generate tests.
Thanks to the MakerBundle, we have this content:

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class FrontController extends AbstractController{
    #[Route('/front', name: 'app_front')]
    public function index(): Response
    {
        return $this->render('front/index.html.twig', [
            'controller_name' => 'FrontController',
        ]);
    }
}

We also have the associated file front/index.html.twig, in templates directory, with this content:

{% extends 'base.html.twig' %}

{% block title %}Hello FrontController!{% endblock %}

{% block body %}
<style>
    .example-wrapper { margin: 1em auto; max-width: 800px; width: 95%; font: 18px/1.5 sans-serif; }
    .example-wrapper code { background: #F5F5F5; padding: 2px 6px; }
</style>

<div class="example-wrapper">
    <h1>Hello {{ controller_name }}! ✅</h1>

    This friendly message is coming from:
    <ul>
        <li>Your controller at <code>/Users/abdounikarim/Web/poc/poc-symfony-handle-assets/src/Controller/FrontController.php</code></li>
        <li>Your template at <code>/Users/abdounikarim/Web/poc/poc-symfony-handle-assets/templates/front/index.html.twig</code></li>
    </ul>
</div>
{% endblock %}

Start by updating our FrontController to go on / and remove the controller_name variable, we are not gonna use it:

<?php

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class FrontController extends AbstractController{
    #[Route('/', name: 'app_front')]
    public function index(): Response
    {
        return $this->render('front/index.html.twig');
    }
}

Update also the associated template content, here front/index.html.twig:

{% extends 'base.html.twig' %}

{% block title %}Hello FrontController!{% endblock %}

{% block body %}
<style>
    .example-wrapper { margin: 1em auto; max-width: 800px; width: 95%; font: 18px/1.5 sans-serif; }
    .example-wrapper code { background: #F5F5F5; padding: 2px 6px; }
</style>

<div class="example-wrapper">
    <h1>Hello from Symfony without WebpackEncoreBundle, ViteBundle or AssetMapper ! 👋</h1>

    This friendly message is coming from:
    <ul>
        <li>Your controller at <code>/Users/abdounikarim/Web/poc/poc-symfony-handle-assets/src/Controller/FrontController.php</code></li>
        <li>Your template at <code>/Users/abdounikarim/Web/poc/poc-symfony-handle-assets/templates/front/index.html.twig</code></li>
    </ul>
</div>
{% endblock %}

The controller_name variable has been removed and the h1 tag has been updated.

Handle our assets

Get back to work, create now a app.css file in the css directory (create also this directory in the public existing one) with this content:

body{
    color: #F5F5F5;
    background-color: #999999;
}

I also added the link to this previous file on our base.html.twig template:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title>{% block title %}Welcome!{% endblock %}</title>
        <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 128 128%22><text y=%221.2em%22 font-size=%2296%22>⚫️</text><text y=%221.3em%22 x=%220.2em%22 font-size=%2276%22 fill=%22%23fff%22>sf</text></svg>">
        {% block stylesheets %}
            <link href="{{ asset('css/app.css') }}" type="text/css">
        {% endblock %}

        {% block javascripts %}
        {% endblock %}
    </head>
    <body>
        {% block body %}{% endblock %}
    </body>
</html>

Do the same by creating a JavaScript file, I called it app.js and add it in a js directory in public with this wonderful content:

console.log('Hello Symfony from our JavaScript file!🚀');

Here, a simple console.log, but you can put here what you want. Don't forget to add the link in the base.html.twig template:

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8">
        <title>{% block title %}Welcome!{% endblock %}</title>
        <link rel="icon" href="data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 128 128%22><text y=%221.2em%22 font-size=%2296%22>⚫️</text><text y=%221.3em%22 x=%220.2em%22 font-size=%2276%22 fill=%22%23fff%22>sf</text></svg>">
        {% block stylesheets %}
            <link rel="stylesheet" href="{{ asset('css/app.css') }}" type="text/css">
        {% endblock %}

        {% block javascripts %}
            <script src="{{ asset('js/app.js') }}"></script>
        {% endblock %}
    </head>
    <body>
        {% block body %}{% endblock %}
    </body>
</html>

If you try to access to your homepage, you should have a wonderful ugly design 🤮

Here, we just add CSS and JavaScript files on our base.html.twig template. It means that these files are gonna be used in all of our application, you can put in here all of your common application code.

Yeah, but if I want to have CSS and JavaScript files which contains only code used in specific page, how can I do this ?

Follow the guide 😅

Start by creating a new index.css file, in our css directory(in public) :

ul{
    list-style-type: none;
}
code{
    color: #FFFFFF;
    background-color: #000000 !important;
}

Nothing special here, just a boring CSS code, free to you to add your own code.

Open now your index.html.twig template, and override the stylesheets block and add a link to our fresh CSS file:

{% extends 'base.html.twig' %}

{% block title %}Hello FrontController!{% endblock %}

{% block stylesheets %}
    <link rel="stylesheet" href="{{ asset('css/index.css') }}" type="text/css">
{% endblock %}

{% block body %}
<style>
    .example-wrapper { margin: 1em auto; max-width: 800px; width: 95%; font: 18px/1.5 sans-serif; }
    .example-wrapper code { background: #F5F5F5; padding: 2px 6px; }
</style>

<div class="example-wrapper">
    <h1>Hello from Symfony without WebpackEncoreBundle, ViteBundle or AssetMapper!👋</h1>

    This friendly message is coming from:
    <ul>
        <li>Your controller at <code>/Users/abdounikarim/Web/poc/poc-symfony-handle-assets/src/Controller/FrontController.php</code></li>
        <li>Your template at <code>/Users/abdounikarim/Web/poc/poc-symfony-handle-assets/templates/front/index.html.twig</code></li>
    </ul>
</div>
{% endblock %}

Refresh your browser page, and... we broke our wonderful design 😭.

How can we do now, we lost the previous style ? Are you kidding us ? 😠

Don't panic, there is a simple way to get back the parent style, you just have to use the {{ parent() }} function:

{% extends 'base.html.twig' %}

{% block title %}Hello FrontController!{% endblock %}

{% block stylesheets %}
    {{ parent() }}
    <link rel="stylesheet" href="{{ asset('css/index.css') }}" type="text/css">
{% endblock %}

{% block body %}
<style>
    .example-wrapper { margin: 1em auto; max-width: 800px; width: 95%; font: 18px/1.5 sans-serif; }
    .example-wrapper code { background: #F5F5F5; padding: 2px 6px; }
</style>

<div class="example-wrapper">
    <h1>Hello from Symfony without WebpackEncoreBundle, ViteBundle or AssetMapper!👋</h1>

    This friendly message is coming from:
    <ul>
        <li>Your controller at <code>/Users/abdounikarim/Web/poc/poc-symfony-handle-assets/src/Controller/FrontController.php</code></li>
        <li>Your template at <code>/Users/abdounikarim/Web/poc/poc-symfony-handle-assets/templates/front/index.html.twig</code></li>
    </ul>
</div>
{% endblock %}

Try again to refresh your browser page, the design must be almost the same as before, but don't dream, it's still wonderfully ugly.😅

Do the same for JavaScript now, create an index.js file in the js directory(in public):

console.log('Hello Symfony from our index.js file!🚀');

Don't forget to add the link in the index.html.twig template:

{% extends 'base.html.twig' %}

{% block title %}Hello FrontController!{% endblock %}

{% block stylesheets %}
    {{ parent() }}
    <link rel="stylesheet" href="{{ asset('css/index.css') }}" type="text/css">
{% endblock %}

{% block body %}
<style>
    .example-wrapper { margin: 1em auto; max-width: 800px; width: 95%; font: 18px/1.5 sans-serif; }
    .example-wrapper code { background: #F5F5F5; padding: 2px 6px; }
</style>

<div class="example-wrapper">
    <h1>Hello from Symfony without WebpackEncoreBundle, ViteBundle or AssetMapper!👋</h1>

    This friendly message is coming from:
    <ul>
        <li>Your controller at <code>/Users/abdounikarim/Web/poc/poc-symfony-handle-assets/src/Controller/FrontController.php</code></li>
        <li>Your template at <code>/Users/abdounikarim/Web/poc/poc-symfony-handle-assets/templates/front/index.html.twig</code></li>
    </ul>
</div>
{% endblock %}

{% block javascripts %}
    {{ parent() }}
    <script src="{{ asset('js/index.js') }}"></script>
{% endblock %}

You see, we can handle assets easily with our Symfony application 😉

Again, it's not the best way to do this, but... you now the drill.

And... please, don't ever deliver a project with a terrible design like this. And if you do it, whatever is the situation, never talk about this article 🤐

Happy coding 😀

Hello from Symfony

Abdouni Abdelkarim — Tue, 31 Dec 2024 11:27:21 +0000

Create a Symfony project

Let's start by creating a fresh new Symfony application using Symfony CLI. Open a terminal and run:

symfony new poc-symfony

The project name poc-symfony here is not important, you can choose whatever you want as project name.

I’m using here Symfony CLI to create a new Symfony application.

If you don’t want to use it, you can use the famous Composer tool as an alternative to create the application:

composer create-project symfony/skeleton poc-symfony

Read this doc to know more about using Composer to create Symfony application.

Start the integrated Symfony server:

symfony serve -d

The -d option is used to run the server as a daemon, in the background. To stop it, you can run:

symfony server:stop

If you didn't installed the Symfony CLI, you can use the built-in PHP web server by running:

php -S localhost:8000 -t public/

By default, the port used is the 8000. Open now your application in your favorite browser at the given URL (https://localhost:8000 by default).

You now have something like this in your browser:

Our goal here : create our first Symfony Controller and render our first template with Twig to show Hello from Symfony!👋

First, install the twig package by running:

composer require twig

Thanks to Symfony Flex, we have also a few files who were added to our project.

Create now our first PHP file which will be our first Symfony Controller. I'm gonna create a new file called HomeController.php (in src/Controller directory, you can name it whatever you want) with this content:

<?php

declare(strict_types=1);

namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

final class HomeController extends AbstractController
{
    #[Route('/', name: 'home')]
    public function home(): Response
    {
        return $this->render('home/index.html.twig');
    }
}

Nothing special here, the HomeController is extending the Symfony AbstractController, and use the render method from it to return a Response from the HTTPFoundation Component.

We have a route matching the / pattern, with name home. The associated method is also named home, and return a twig template.

The twig template content contains this:

{% extends 'base.html.twig' %}

{% block body %}
    <h1>Hello from Symfony!👋</h1>
{% endblock %}

We just extends the base.html.twig file and customize the content in the body block.
Refresh your page and voilà 🎉

Congratulations, you made it 👏

Testing our application

Testing time 🛎️
It’s time to test our application.

You don't test your application ? You are too good to add tests ?

Your choice, but I prefer to add some to make sure everything works as expected.

Let's add a new pack for testing by running:

composer require --dev symfony/test-pack

Again, thanks to Symfony Flex, we have a few more files installed with a default configuration working.

Create now a PHP file for test. I called this file HomeControllerTest (in tests/Controller directory):

<?php

declare(strict_types=1);

namespace App\Tests\Controller;

use Symfony\Bundle\FrameworkBundle\Test\WebTestCase;

final class HomeControllerTest extends WebTestCase
{
    public function testHomepage(): void
    {
        $client = static::createClient();
        $client->request('GET', '/');

        $this->assertResponseIsSuccessful();
        $this->assertSelectorTextContains('h1', 'Hello from Symfony!👋');
    }
}

This simple test can help us check everything works in our application.

Run the tests:

./bin/phpunit

Congrats, the test pass, you rock 🤘

Dockerize our application

Let's now dockerize our application.

For this project, i'm gonna use a famous template as a base for our application: https://github.com/dunglas/symfony-docker

This template has two environments : dev and prod. That's perfect for our needs. I'm just gonna remove useless files.

Start by creating a compose.yaml (the old filename was docker-compose.yaml):

services:
  php:
    image: ${IMAGES_PREFIX:-}app-php
    restart: unless-stopped
    environment:
      SERVER_NAME: ${SERVER_NAME:-localhost}, php:80
    volumes:
      - ./:/app
      - caddy_data:/data
      - caddy_config:/config
    ports:
      # HTTP
      - target: 80
        published: ${HTTP_PORT:-80}
        protocol: tcp
      # HTTPS
      - target: 443
        published: ${HTTPS_PORT:-443}
        protocol: tcp
      # HTTP/3
      - target: 443
        published: ${HTTP3_PORT:-443}
        protocol: udp

volumes:
  caddy_data:
  caddy_config:

This configuration will be common to our two environments.

Create now a compose.override.yaml file, which will be our default configuration for our dev env:

services:
  php:
    build:
      context: .
      target: frankenphp_dev
    volumes:
      - ./frankenphp/Caddyfile:/etc/caddy/Caddyfile:ro
      - ./frankenphp/conf.d/app.dev.ini:/usr/local/etc/php/conf.d/app.dev.ini:ro
    environment:
      XDEBUG_MODE: "${XDEBUG_MODE:-off}"
    extra_hosts:
      - host.docker.internal:host-gateway
    tty: true

There is the compose.prod.yaml content, for our prod env:

services:
  php:
    build:
      context: .
      target: frankenphp_prod
    environment:
      APP_SECRET: ${APP_SECRET}

Don't forget to create a Dockerfile, for our custom docker image:

#syntax=docker/dockerfile:1.4

# Versions
FROM dunglas/frankenphp:1-php8.3 AS frankenphp_upstream

# The different stages of this Dockerfile are meant to be built into separate images
# https://docs.docker.com/develop/develop-images/multistage-build/#stop-at-a-specific-build-stage
# https://docs.docker.com/compose/compose-file/#target


# Base FrankenPHP image
FROM frankenphp_upstream AS frankenphp_base

WORKDIR /app

VOLUME /app/var/

# persistent / runtime deps
# hadolint ignore=DL3008
RUN apt-get update && apt-get install -y --no-install-recommends \
    acl \
    file \
    gettext \
    git \
    && rm -rf /var/lib/apt/lists/*

RUN set -eux; \
    install-php-extensions \
    @composer \
    apcu \
    intl \
    opcache \
    zip \
    ;

# https://getcomposer.org/doc/03-cli.md#composer-allow-superuser
ENV COMPOSER_ALLOW_SUPERUSER=1

###> recipes ###
###< recipes ###

COPY --link frankenphp/conf.d/app.ini $PHP_INI_DIR/conf.d/
COPY --link --chmod=755 frankenphp/docker-entrypoint.sh /usr/local/bin/docker-entrypoint
COPY --link frankenphp/Caddyfile /etc/caddy/Caddyfile

ENTRYPOINT ["docker-entrypoint"]

HEALTHCHECK --start-period=60s CMD curl -f http://localhost:2019/metrics || exit 1
CMD [ "frankenphp", "run", "--config", "/etc/caddy/Caddyfile" ]

# Dev FrankenPHP image
FROM frankenphp_base AS frankenphp_dev

ENV APP_ENV=dev XDEBUG_MODE=off

RUN mv "$PHP_INI_DIR/php.ini-development" "$PHP_INI_DIR/php.ini"

RUN set -eux; \
    install-php-extensions \
    xdebug \
    ;

COPY --link frankenphp/conf.d/app.dev.ini $PHP_INI_DIR/conf.d/

CMD [ "frankenphp", "run", "--config", "/etc/caddy/Caddyfile", "--watch" ]

# Prod FrankenPHP image
FROM frankenphp_base AS frankenphp_prod

ENV APP_ENV=prod
ENV FRANKENPHP_CONFIG="import worker.Caddyfile"

RUN mv "$PHP_INI_DIR/php.ini-production" "$PHP_INI_DIR/php.ini"

COPY --link frankenphp/conf.d/app.prod.ini $PHP_INI_DIR/conf.d/
COPY --link frankenphp/worker.Caddyfile /etc/caddy/worker.Caddyfile

# prevent the reinstallation of vendors at every changes in the source code
COPY --link composer.* symfony.* ./
RUN set -eux; \
    composer install --no-cache --prefer-dist --no-dev --no-autoloader --no-scripts --no-progress

# copy sources
COPY --link . ./
RUN rm -Rf frankenphp/

RUN set -eux; \
    mkdir -p var/cache var/log; \
    composer dump-autoload --classmap-authoritative --no-dev; \
    composer dump-env prod; \
    composer run-script --no-dev post-install-cmd; \
    chmod +x bin/console; sync;

That's almost it for our Docker configuration files.

We just need a few more files for our PHP configuration for our Docker PHP service.

Again, i'm just gonna past here some configuration files for FrankenPHP, but you can easily find them in the associated repository.

There is our custom configuration for Caddy (FrankenPHP is based on the Caddy web server), this file is named frankenphp/Caddyfile:

{
    {$CADDY_GLOBAL_OPTIONS}

    frankenphp {
        {$FRANKENPHP_CONFIG}
    }
}

{$CADDY_EXTRA_CONFIG}

{$SERVER_NAME:localhost} {
    log {
        # Redact the authorization query parameter that can be set by Mercure
        format filter {
            request>uri query {
                replace authorization REDACTED
            }
        }
    }

    root * /app/public
    encode zstd br gzip

    {$CADDY_SERVER_EXTRA_DIRECTIVES}

    # Disable Topics tracking if not enabled explicitly: https://github.com/jkarlin/topics
    header ?Permissions-Policy "browsing-topics=()"

    php_server
}

Now, add some custom for our PHP configuration, first for frankenphp/conf.d/app.ini:

expose_php = 0
date.timezone = UTC
apc.enable_cli = 1
session.use_strict_mode = 1
zend.detect_unicode = 0

; https://symfony.com/doc/current/performance.html
realpath_cache_size = 4096K
realpath_cache_ttl = 600
opcache.interned_strings_buffer = 16
opcache.max_accelerated_files = 20000
opcache.memory_consumption = 256
opcache.enable_file_override = 1

This is a common configuration, for our environments.

Now, our dev configuration, the file is named frankenphp/conf.d/app.dev.ini:

xdebug.client_host = host.docker.internal

A good xdebug configuration, for debugging in dev 😉.

And last, for our prod configuration (frankenphp/conf.d/app.prod.ini):

opcache.preload_user = root
opcache.preload = /app/config/preload.php

We have almost finished, let's also add a frankenphp/docker-entrypoint.sh:

#!/bin/sh
set -e

if [ "$1" = 'frankenphp' ] || [ "$1" = 'php' ] || [ "$1" = 'bin/console' ]; then
    if [ -z "$(ls -A 'vendor/' 2>/dev/null)" ]; then
        composer install --prefer-dist --no-progress --no-interaction
    fi

    setfacl -R -m u:www-data:rwX -m u:"$(whoami)":rwX var
    setfacl -dR -m u:www-data:rwX -m u:"$(whoami)":rwX var
fi

exec docker-php-entrypoint "$@"

Last thing, we need to add a library to handle the worker mode for FrankenPHP, install it with composer:

composer require runtime/frankenphp-symfony

Don't forget to add his associated configuration (frankenphp/worker.Caddyfile):

worker {
    file ./public/index.php
    env APP_RUNTIME Runtime\FrankenPhpSymfony\Runtime
}

Congratulations, you now have dockerized your Symfony application 👏

You can now build your images:

docker compose build --no-cache

Start your containers in dev mode:

docker compose up -d

And in prod:

docker compose -f compose.yaml -f compose.prod.yaml up -d

If you have some troubles, you can check the docker logs:

docker compose logs -f

You can also run again your tests in your Docker container and make sure they still pass:

docker compose exec php bin/phpunit

I created a repository where you can find all of this code and associated commands here : https://github.com/abdounikarim/poc-symfony

I hope this article helped you in some way, maybe by learning something 😇

Happy coding 😀