Symfony CDN integration

Introduction

A Symfony CDN integration can deliver versioned CSS, JavaScript, images, and other static files from edge servers closer to application visitors. Dynamic routes remain on the Symfony origin while the CDN handles repeat requests for public assets.

This guide shows how to set up a CDN in Symfony with the native AssetMapper and Asset components. The procedure was tested with Symfony 7.4.16 and AssetMapper 7.4.15.

Before you start

This tutorial shows how to integrate a CDN service into a website. In this particular demo example we will use:
- barsoom-cdn.cdnsun.org as the CDN Service Domain, and
- https://barsoom.cdnsun.org as the website URL (i.e. barsoom.cdnsun.org is the Origin Domain).
Please visit the Services/How-To section to obtain your CDN Service Domain.
Before you take any steps please back up your files and database.
To integrate a CDN service on https:// website the CDN service must have SSL enabled.
If your website embeds custom fonts then please first enable CORS for them.
Before you take any steps please make sure that your CDN Service Domain is ready-to-use here.

Create CDN Static service

Please refer to Creating a CDN Static service for more details.

How to enable CDN in Symfony

From the Symfony project root, install AssetMapper, the Asset component, and Twig support if the application does not already include them:
```
composer require symfony/asset-mapper symfony/asset symfony/twig-pack
```
Symfony Flex creates the standard assets/ directory, config/packages/asset_mapper.yaml, and the application import map.
Add the complete HTTPS URL of the CDN Service Domain to the environment used by the application. For example, add this value to .env.local:
```
CDN_BASE_URL=https://barsoom-cdn.cdnsun.org
```
Create config/packages/assets.yaml and configure the default Symfony asset package to use that URL:
```
framework:
    assets:
        base_urls:
            - '%env(CDN_BASE_URL)%'
```
This setting applies the CDN Service Domain to URLs generated by the Twig asset() function and to AssetMapper's import map, stylesheet links, module preloads, and JavaScript entrypoint URLs.

Optional media package: To give files under public/media/ a separate CDN base path, add a named package alongside the default configuration:
```
framework:
    assets:
        base_urls:
            - '%env(CDN_BASE_URL)%'
        packages:
            media:
                base_urls:
                    - 'https://barsoom-cdn.cdnsun.org/media'
```
Generate a media URL with {{ asset('photo.jpg', 'media') }}. The named package is optional and does not change application routes.
Keep application CSS, JavaScript, and images in the mapped assets/ directory. Import the stylesheet from the application entrypoint:
```
// assets/app.js
import './styles/app.css';
```
Render the entrypoint with importmap() and generate image URLs with asset() in Twig:
```
{% block javascripts %}
    {{ importmap('app') }}
{% endblock %}

<img src="{{ asset('images/logo.svg') }}" alt="Company logo">
```
Use logical paths relative to the mapped directory. AssetMapper adds a content hash to the public filename and the configured asset package adds the CDN Service Domain.
Compile the mapped assets during the production deployment:
```
php bin/console asset-map:compile
```
The command writes the versioned files, manifest, import map, and entrypoint metadata to public/assets/. Deploy that directory with the application so the files are available from the origin path used by the CDN.
Complete the cross-origin asset setup described in the CDNsun CORS configuration guide. This is required when AssetMapper's JavaScript modules load from a different domain.
Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.

Verify & Troubleshoot

View HTML source code of your web pages to verify that you are using CDN, you should see source attribute of your images, CSS, JavaScript, etc. beginning with your CDN Service Domain.
Don't see your CDN Service Domain in the source code of your web pages? If your website is using any cache plug-in/mechanism then you might want to clear/flush its cache.
Having trouble with custom fonts? Please refer to Using custom fonts with CDN - setting CORS for more details.
Still having trouble? Check your CDN URLs using our content check tool or please refer to Debugging a CDN service for more hints.

Introduction

Before you start

Create CDN Static service

How to enable CDN in Symfony

Verify & Troubleshoot

Contact Us