CakePHP CDN integration

Introduction

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

This guide shows how to configure CakePHP's native asset base URLs with one environment variable. The procedure was tested with CakePHP 5.4.1.

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 CakePHP

  1. 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 the value outside application templates so development, staging, and production can use different CDN Service Domains without changing view files.

  2. Open config/app.php. After the existing imports and before the returned configuration array, normalize the environment value by removing any trailing slash: 
    $cdnBaseUrl = rtrim((string)env('CDN_BASE_URL', ''), '/');

return [
    // Existing application configuration
];
  3. In the existing App configuration, replace the default imageBaseUrl, cssBaseUrl, and jsBaseUrl values with: 
    'App' => [
    // Existing App configuration
    'imageBaseUrl' => $cdnBaseUrl !== ''
        ? $cdnBaseUrl . '/img/'
        : 'img/',
    'cssBaseUrl' => $cdnBaseUrl !== ''
        ? $cdnBaseUrl . '/css/'
        : 'css/',
    'jsBaseUrl' => $cdnBaseUrl !== ''
        ? $cdnBaseUrl . '/js/'
        : 'js/',
],

    The local values remain as fallbacks when CDN_BASE_URL is not set. Application routes and other dynamic URLs are unaffected.

  4. Keep stylesheets in webroot/css/, JavaScript in webroot/js/, and images in webroot/img/. Generate their URLs through CakePHP's native HtmlHelper methods: 
    <?= $this->Html->css('app') ?>
<?= $this->Html->script('app', ['defer' => true]) ?>
<?= $this->Html->image('logo.svg', [
    'alt' => 'Company logo',
]) ?>

    CakePHP prepends the corresponding absolute asset base URL. These calls therefore generate URLs under the CDN Service Domain while retaining the normal /css/, /js/, and /img/ paths.

  5. Update remaining literal static asset paths in application templates to use the matching HtmlHelper method. Do not use the asset settings for controller routes, form actions, authentication URLs, or other dynamic application requests.
  6. Open the public site and confirm that the frontend remains styled normally and static assets load from the CDN Service Domain.
    Styled CakePHP application loading CSS, JavaScript, and an image through 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.
    Frontend HTML proof that static assets are loaded from the 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.

Contact Us

            _____     _____   
    ___    |  ___||  /  ___|| 
   /   ||  | ||__   | // __   
  | [] ||  | ||__   | \\_\ || 
   \__ ||  |_____||  \____//  
    -|_||  `-----`    `---`   
     `-`