Laminas CDN integration

Introduction

A Laminas CDN integration can deliver public stylesheets, JavaScript, images, and other static files from edge servers closer to visitors. Application routes, controllers, and dynamic responses remain on the origin while the CDN handles repeat requests for static content.

Laminas is the open-source successor to Zend Framework. This guide shows how to define one environment-based CDN URL and expose it through a reusable view helper. The procedure was tested with Laminas MVC Skeleton 2.4.0 and laminas-mvc 3.8.0. For applications that still use Zend Framework 1 or its zf1-future community continuation, see the Zend Framework 1 CDN integration guide.

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.

Configure static asset URLs in Laminas MVC

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
```
Keep this value outside the application code so each deployment can use its own CDN Service Domain.
Open config/autoload/global.php and add a central CDN configuration value. Removing the trailing slash keeps generated asset URLs consistent:
```
<?php

return [
    'cdn' => [
        'base_url' => rtrim((string) getenv('CDN_BASE_URL'), '/'),
    ],
];
```

Create module/Application/src/View/Helper/CdnAsset.php. The helper prefixes a public asset path with the configured CDN URL and falls back to an origin-relative path when the environment value is empty:

<?php

declare(strict_types=1);

namespace Application\View\Helper;

use Laminas\View\Helper\AbstractHelper;

final class CdnAsset extends AbstractHelper
{
    public function __construct(private readonly string $baseUrl)
    {
    }

    public function __invoke(string $path): string
    {
        $assetPath = ltrim($path, '/');

        return $this->baseUrl === ''
            ? '/' . $assetPath
            : $this->baseUrl . '/' . $assetPath;
    }
}

Create module/Application/src/Factory/CdnAssetFactory.php. The factory reads the central setting and supplies it to the helper:

<?php

declare(strict_types=1);

namespace Application\Factory;

use Application\View\Helper\CdnAsset;
use Psr\Container\ContainerInterface;

final class CdnAssetFactory
{
    public function __invoke(ContainerInterface $container): CdnAsset
    {
        $config = $container->get('config');

        return new CdnAsset($config['cdn']['base_url'] ?? '');
    }
}

Register the helper in module/Application/config/module.config.php. Add the view_helpers section alongside the existing controller and view configuration:
```
'view_helpers' => [
    'aliases' => [
        'cdnAsset' => View\Helper\CdnAsset::class,
    ],
    'factories' => [
        View\Helper\CdnAsset::class => Factory\CdnAssetFactory::class,
    ],
],
```
Laminas can now resolve cdnAsset() in any view rendered by the application module.
Open the public layout, commonly module/Application/view/layout/layout.phtml, and replace static calls to basePath() with the CDN helper. For example:
```
<?= $this->headLink()
    ->appendStylesheet(
        $this->cdnAsset('css/app.css')
    ) ?>

<img
    src="<?= $this->cdnAsset('img/logo.svg') ?>"
    alt="Site logo"
>

<?= $this->inlineScript()
    ->appendFile(
        $this->cdnAsset('js/app.js')
    ) ?>
```
Use the helper for public files that the CDN should cache. Keep route URLs, forms, API requests, and other dynamic application links on the origin domain.
Update remaining literal static paths in application views so they use cdnAsset(). Clear the Laminas configuration cache after changing the setting or helper registration:
```
php bin/clear-config-cache.php
```
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

Configure static asset URLs in Laminas MVC

Verify & Troubleshoot

Contact Us