PHP helper

Installing

composer require echodial/deck

PHP 8.1 or newer, and no runtime dependencies. It is framework-agnostic on purpose — no container, no service provider, no facade — so the same class works in Keel, in Laravel, in Symfony, in WordPress, and in a single index.php.

A browser cannot read vendor/, so the assets have to be copied into a public directory, and Composer will not do it for you: it never runs scripts from a package you install, only the ones in your own composer.json. Add the publisher there:

"scripts": {
  "post-install-cmd": ["EchoDial\\Deck\\Installer::postInstall"],
  "post-update-cmd": ["EchoDial\\Deck\\Installer::postInstall"],
  "deck-publish": "EchoDial\\Deck\\Installer::publish"
},
"extra": {
  "deck": {
    "publish-to": "public/assets/deck",
    "auto-publish": true
  }
}

composer require, composer install and composer update then publish, and composer deck-publish publishes on demand. extra.deck is read from your composer.json, never from Deck's.

composer deck-publish
composer deck-publish -- public/static/deck
composer deck-publish -- --link          # symlink where the platform allows it

publish-to defaults to public/assets/deck. Change it if your document root is not public/: on cPanel and Helm it is public_html/. With auto-publish left out or false, the install and update hooks print a reminder instead of copying. The install page covers the two ways to get the files without any scripts.

The installer skips a file whose contents are unchanged rather than recopying it. That is deliberate: recopying rewrites the mtime, and the mtime is what Deck::asset() uses to bust the cache — so a churning deploy would invalidate every asset URL on every release for no reason. Symlinks fall back to a copy where the platform refuses them, which is Windows without developer mode and some containers.

Configuration

Ten options, all with defaults that work. The two worth setting explicitly are base, which nothing can guess, and root, which everything to do with cache busting depends on.

root is the one that catches people. It is the filesystem path that base is relative to — usually your document root, not the directory the class is in. Get it wrong and nothing breaks visibly: the tags still render, the URLs still work, and ?v= quietly falls back to the package version, so a deploy stops busting caches and nobody finds out until a stale stylesheet is on a customer's screen.

Methods

All static, all on EchoDial\Deck\Deck. Deck::VERSION is the package version as a string.

use EchoDial\Deck\Deck;

Deck::configure([
    'base'   => '/assets/deck',
    'root'   => __DIR__,        // this file's directory is the web root
    'extras' => true,
]);

<head>
  <meta charset="utf-8">
  <title>Orders</title>
  <?= Deck::head() ?>
</head>

<?= Deck::css() ?>
<!-- <link rel="stylesheet" href="/assets/deck/deck.min.css?v=1725900000"> -->

Deck::configure(['bundle' => true]);
echo Deck::js();
// <script src="/assets/deck/deck.bundle.min.js?v=…" defer></script>

Deck::asset('deck-icons.svg');
// '/assets/deck/deck-icons.svg?v=1725900000'

Deck::stylesheet();   // 'deck.min.css' in production

<html <?= Deck::htmlAttributes(lang: 'en', dir: 'ltr') ?>>

<html <?= Deck::htmlAttributes(lang: 'en') ?>
      <?= Deck::theme(hue: $tenant->hue, mode: $user->theme) ?>>
<!-- <html lang="en" style="--hue-brand:265" data-theme="dark"> -->

<?= Deck::icon('check-circle', 'icon icon-lg', 'Paid') ?>
<?= Deck::icon('chevron-down') ?>   <!-- decorative -->

Deck::config('base');            // '/assets/deck'
Deck::config('missing', 'fallback');

copy(Deck::distPath() . '/deck.min.css', __DIR__ . '/public/deck.min.css');

All together

A complete page. The tenant's brand colour and the user's theme come out of the database and land in the first byte of HTML, so there is no flash of the wrong colour and no second request.

<?php
use EchoDial\Deck\Deck;

Deck::configure([
    'base'   => '/assets/deck',
    'root'   => __DIR__,
    'minify' => true,
]);
?>
<!doctype html>
<html <?= Deck::htmlAttributes(lang: 'en') ?> <?= Deck::theme(hue: $tenant->hue, mode: $user->theme) ?>>
<head>
<meta charset="utf-8">
<title><?= htmlspecialchars($tenant->name) ?></title>
<?= Deck::head() ?>
</head>
<body>
  <header class="sticky-top">
    <div class="container">
      <nav class="navbar">
        <a class="navbar-brand" href="/"><?= Deck::icon('grid', 'icon icon-lg') ?> <?= htmlspecialchars($tenant->name) ?></a>
        <button class="btn btn-icon btn-ghost push" data-deck-theme aria-label="Switch theme">
          <?= Deck::icon('moon') ?>
        </button>
      </nav>
    </div>
  </header>
  <main class="container section stack stack-6">…</main>
</body>
</html>

There is a runnable version of this in the repository at public_html/php-helper.php. It deliberately requires the class by path rather than through the autoloader, so it works in a bare PHP site with nothing installed.

Things worth knowing

• Everything returns a string. Nothing echoes, nothing buffers, and nothing touches global state beyond the static configuration. The methods are safe to call in a template.
• Markup is not escaped; values are. The return values are HTML and are meant to be echoed raw. The parts that come from you — the icon name, the class, the theme, the URLs — are escaped inside.
• The configuration is static. Per request, shared across the request. In a long-running worker — Swoole, RoadRunner, Octane — it survives between requests, so configure it once at boot rather than per request, or reset it explicitly.
• It does not read the stylesheet. Nothing here parses CSS or knows what classes exist. If you want that inventory in PHP, read dist/api.json — the documentation site does exactly that.