Skip to main content

build_head_includes.php

This script creates inlined-head.html, a server-side include (SSI) file that contains critical resources needed for initial page render.

Pathbuild/build_head_includes.php
LanguagePHP
Lines91

Read this when Use this page when tracing PHP asset generation, build hooks, template assembly, or maintenance scripts around build_head_includes.

Overview​

This script creates inlined-head.html, a server-side include (SSI) file that contains critical resources needed for initial page render. It inlines CSS directly into <style> tags and adds versioned <link>/<script> tags for external resources (including head.js).

The generated include file is designed to be embedded in HTML pages via Apache SSI directives (<!--#include virtual="/static/include/inlined-head.html"-->). This approach allows the same optimized head content to be shared across all pages without duplicating code in templates.

The script handles two types of includes: inlined CSS (from .css files) and external resource references (preload hints, external stylesheets/scripts) with automatic cache-busting versioning.

Key Functions/Variables​

Include Configuration​

  • $includes: Array defining resources to include in the head. Each entry is either:
    • [ 'filename.css', 'attributes' ] - CSS file to inline with optional HTML attributes
  • [ '<element ...>', null ] - Literal HTML tag for external resources (including JS)

Include List​

[
    [ 'light-mode-GENERATED.css', 'id="inlined-styles-colors"' ],
    [ 'dark-mode-GENERATED.css', 'id="inlined-styles-colors-dark" media="all and (prefers-color-scheme: dark)"' ],
    [ '<link rel="stylesheet" href="/static/css/head.css">' ],
    [ '<script src="/static/js/head.js"></script>' ],
    [ '<link rel="preload" href="/static/img/icon/icons.svg" as="image">' ]
]

Processing Logic​

  • Type detection: Regex checks determine if an entry is CSS (.css), JS (.js), or external HTML (src=/href=)
  • File path resolution: Constructs absolute filesystem paths based on type (CSS → $css_dir, JS → $js_dir, external → parse from tag)
  • Inlining: For CSS files, reads content with file_get_contents() and wraps in <style> tags
  • Versioning: For external resources, calls VersionedAssetHref() to append ?v={timestamp} query parameters

Helper Function Usage​

  • VersionedAssetHref($file_name, $file_extension): Generates versioned URLs with modification timestamps for cache busting (defined in build_functions.php)

Input/Output​

Input Files​

Inlined CSS:

  • /css/light-mode-GENERATED.css
  • /css/dark-mode-GENERATED.css

External CSS/JS (versioned):

  • /css/head.css (or head-GENERATED.css, head-VERSIONED.css - VersionedAssetHref() checks variants)
  • /js/head.js (or head-GENERATED.js, head-VERSIONED.js)

Preload hints:

  • /img/icon/icons.svg (file existence checked for versioning)

Output Files​

  • /include/inlined-head.html - Complete HTML include with inlined CSS and versioned external references

Example output structure:

<style id="inlined-styles-colors">
/* light-mode-GENERATED.css contents */
</style>
<style id="inlined-styles-colors-dark" media="all and (prefers-color-scheme: dark)">
/* dark-mode-GENERATED.css contents */
</style>
<link rel="stylesheet" href="/static/css/head.css?v=1704672000">
<script src="/static/js/head.js?v=1704668400"></script>
<link rel="preload" href="/static/img/icon/icons.svg?v=1704665800" as="image">

Usage​

Invoked by the Git pre-commit hook (build/pre-commit.hook.php) when any of its input files (light-mode-GENERATED.css, dark-mode-GENERATED.css, head-VERSIONED.css, head-GENERATED.js, or icons.svg) are staged for commit. Can also be run manually:

php /path/to/build/build_head_includes.php

No command-line arguments required. The script:

  1. Requires build_paths.php, build_variables.php, and build_functions.php
  2. Iterates through $includes array
  3. Inlines CSS file contents or versions external references
  4. Writes complete include file to /include/inlined-head.html and appends it to the shared $updated_files array (which the pre-commit hook then git adds)

Server configuration: Pages must use the .shtml extension and enable SSI processing:

# .htaccess (Apache)
Options +Includes
AddType text/html .shtml
AddOutputFilter INCLUDES .shtml

Template usage:

<head>
    <!--#include virtual="/static/include/inlined-head.html"-->
    <!-- other head elements -->
</head>
See Also