dupot / static-generation-framework

2.0.0 2022-11-12 14:07 UTC

LGPL-3.0-only

• Michael Bertocchi

Published on Packagist.org on 2022-11-12 14:11 UTC

README

Build static websites in plain PHP: no template engine, no build pipeline, no runtime dependencies.

Dupot Static Generation Framework is a tiny PHP library for generating static HTML sites, ready to host on GitHub Pages, GitLab Pages, Netlify, an S3 bucket or any basic web server.

You write pages and components as small PHP classes, render them with regular PHP views, and write the output as .html files. That's all there is to it.

✨ Why use it?

• 🪶 Lightweight: a handful of classes and zero Composer dependencies.
• 🐘 Plain PHP: your views are .php files. You don't have to learn a new templating language.
• 🧩 Component-based: split your site into reusable pieces (header, menu, cards, footer…).
• 📄 One class per page: each page knows its filename and how it renders.
• 🚀 Host it anywhere: the output is plain HTML, so it's fast and secure, and there's no server-side code in production.
• 🔧 Fully under your control: no magic and no conventions forced on you, so it fits into any workflow (scripts, CI, GitHub Actions…).

📦 Installation

composer require dupot/static-generation-framework

Or add it to your composer.json:

{
    "require": {
        "dupot/static-generation-framework": "2.*.*"
    }
}

💡 The fastest way to start is the ready-to-use skeleton project: 👉 imikado/dupotStaticGenerationSkeleton

🚀 Quick start

1. Create a component

<?php

use Dupot\StaticGenerationFramework\Component\ComponentAbstract;
use Dupot\StaticGenerationFramework\Component\ComponentInterface;

class MenuComponent extends ComponentAbstract implements ComponentInterface
{
    public function render(): string
    {
        return $this->renderViewWithParamList(__DIR__ . '/views/menu.php', [
            'linkList' => [
                'index.html' => 'Home',
                'about.html' => 'About',
            ],
        ]);
    }
}

views/menu.php:

<nav>
    <?php foreach ($this->paramList['linkList'] as $url => $label): ?>
        <a href="<?= $url ?>"><?= htmlspecialchars($label) ?></a>
    <?php endforeach; ?>
</nav>

2. Create a page

<?php

use Dupot\StaticGenerationFramework\Page\PageAbstract;
use Dupot\StaticGenerationFramework\Page\PageInterface;

class IndexPage extends PageAbstract implements PageInterface
{
    public function getFilename(): string
    {
        return 'index.html';
    }

    public function render(): string
    {
        return $this->renderLayoutWithParamList(__DIR__ . '/layouts/default.php', [
            'title'   => 'Welcome',
            'menu'    => (new MenuComponent())->render(),
            'content' => '<h1>Hello world 👋</h1>',
        ]);
    }
}

layouts/default.php:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8">
    <title><?= htmlspecialchars($this->paramList['title']) ?></title>
</head>
<body>
    <?= $this->paramList['menu'] ?>
    <main><?= $this->paramList['content'] ?></main>
</body>
</html>

3. Generate your site

<?php

require __DIR__ . '/vendor/autoload.php';

$outputDir = __DIR__ . '/docs'; // e.g. the folder served by GitHub Pages

foreach ([new IndexPage(), new AboutPage()] as $page) {
    $page->generateTo($outputDir);
}

php generate.php

Your static site is now in docs/. Commit it, push it, and you're online. 🎉

🧱 API overview

Class / Interface	Role	Main methods
Page\PageInterface	Contract for a page	getFilename(): string, render(): string
Page\PageAbstract	Base class for pages	renderLayoutWithParamList($layoutPath, $paramList), generateTo($generationPath)
Component\ComponentInterface	Contract for a component	render(): string
Component\ComponentAbstract	Base class for components	renderViewWithParamList($viewPath, $paramList)

Inside a view or layout, the parameters you passed are available in $this->paramList.

🔗 Related projects

• dupotStaticGenerationSkeleton: a starter project built on this framework
• dupot.org: author's website

🤝 Contributing

Issues, ideas and pull requests are welcome! If you find this project useful, please consider giving it a ⭐ on GitHub; it helps other people discover it.

📄 License

Released under the GNU Lesser General Public License (LGPL). See LICENSE.

Author: Michael Bertocchi (@imikado)