Phalcon CDN integration

Introduction

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

This guide shows how to configure Phalcon's native URL service with one environment variable and use that service with the Assets Manager and view templates. The procedure was tested with Phalcon 5.16.0.

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 Phalcon

Add the complete HTTPS URL of the CDN Service Domain to the environment used by the application:
```
CDN_BASE_URL=https://barsoom-cdn.cdnsun.org
```
Keeping this value outside the application code lets each environment use its own CDN Service Domain without changing controllers or view templates.
Open the application bootstrap or dependency injection configuration where the url service is registered. Configure its dynamic and static base URIs:
```
use Phalcon\Mvc\Url;

$container->setShared('url', function (): Url {
    $url = new Url();
    $url->setBaseUri('/');

    $cdnBaseUrl = getenv('CDN_BASE_URL') ?: '';
    $url->setStaticBaseUri(
        $cdnBaseUrl !== '' ? rtrim($cdnBaseUrl, '/') . '/' : '/'
    );

    return $url;
});
```
setBaseUri() keeps application routes on the origin. setStaticBaseUri() supplies the absolute base URL for static files and falls back to local paths when CDN_BASE_URL is empty.
Register local CSS and JavaScript paths with the Assets Manager, for example in a controller action:
```
$this->assets
    ->addCss('css/app.css')
    ->addJs('js/app.js');
```
Keep the files under the application's public document root. Because these are local asset paths, Phalcon generates their public URLs through the registered URL service.
Output the registered collections in the view and generate image URLs with getStatic():
```
<?php $this->assets->outputCss(); ?>
<?php $this->assets->outputJs(); ?>

<img
    src="<?= $this->url->getStatic('img/logo.svg') ?>"
    alt="Company logo"
>
```
The generated stylesheet, script, and image URLs use the CDN Service Domain while controller routes and other dynamic application URLs remain unchanged.
Update remaining literal static paths in application views to use getStatic() or the Assets Manager. Do not apply the static base URI to form actions, authentication URLs, API endpoints, or other dynamic requests.
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 Phalcon

Verify & Troubleshoot

Contact Us