Tempest-Pico

Components for Tempest Framework with Pico CSS + UnoCSS

Documentation

Tempest-Pico is still a work in progress, but I will try to keep it up to date.

Why?

Goal of this Project is to create a Base to quickly build mostly static websites, used by a very small community. It is built on top of Tempest v2 (I still need PHP 8.4).

My own "modern PHP" Framework was written in PHP5 and ported 2015 to Hack, but Hack is dead and I need to switch back to PHP again. Around 10 Years I only use PHP for small scripts and to fix WordPress sites, so I'm a bit rusty and not really up to date with modern PHP Tools. So fell free to give me feedback like "Hey, you should use this library." or "This is not how you should do it, you should do it like this!".

In the long run, I like to replace some WordPress sites with Tempest. Unfortunately, Tempest own View system is not really suitable for me, thats why I created my own "HTML View Tree Builder" on top of it. It is not battle-tested, but it solved some Issus I had. I'm happy with it so far.

Take a look at the Components code to see how I use it, maybe it is also useful for you.

Well, the next is (mostly) generated by Copilot for itself… But why not use it?

Tempest Pico — Copilot Instructions

Quick Start

Tech Stack: PHP 8.4, Tempest Framework (v2), HtmlViewTree, UnoCSS, Pico CSS, PHPUnit, PHPStan (level 7)

Yohn's Fork of PicoCSS is used - see https://yohn.github.io/PicoCSS/ and https://github.com/Yohn/PicoCSS/

HtmlViewTree: a alternative to string-based template engines, see Html View Tree Builder below.

QA Workflow:

composer qa           # fmt + phpunit + lint (use this before PRs)
composer phpunit      # Run tests with detailed output
composer fmt          # Format with mago
composer lint         # Lint with mago (auto-fixes)
pnpm unocss --watch   # Watch CSS during development

Key Namespaces:

PHPStan: Level 7 strict checking on src/, app/, tests/

Type Hints and common abbreviations

Project Principles

1. Semantic HTML/CSS First

2. IDE & Static Analysis Clarity

3. Component Architecture

4. Html View Tree Builder

Common Tasks

Add a New Component

  1. use src/Components/Accordion.php and src/Components/Table.php as reference
  2. Create src/Components/*.php (logic + dependencies)
  3. Create src/Components/*.view.php (only needs: <?= $this->toHtml();)
  4. Implement IsComponent and extend Component
  5. Use it in other components or controllers
  6. Add the class::name to src/Components/Doc.php::COMPONENTS

Add Examples, short Documentation and Tests for a Component

Add a Helper Function

Run Tests Before PR

composer qa

This ensures:

Debug HtmlViewTree Issues

Architecture Overview

src/
  Components/         # Reusable UI components
    *.php             # Logic
    *.view.php        # Render (returns HtmlString)
    Examples/         
      *.php           # Example (used in Tests)
      *.md            # Notes / Documentation
  Layout/             # Page layout (header, nav, footer) and configs
    Page/             # Base Html for pages
  Page/               # Route handlers / page builders / Controllers
  Support/
    Html/             # HTML View Tree Builder, Helper
      Exception/      # Custom exceptions (InvalidTag, VoidWithContent, etc.)
      functions.php   # Helper functions / Shortcuts
tests/                # Test code (PhpUnit)

Key Files & References

PHPStan Common Fixes

❌ "Undefined type 'TempestPico\Support\Html\Exception\InvalidTag'"

Fix: Create the exception class in src/Support/Html/Exception/InvalidTag.php:

<?php declare(strict_types=1);
namespace TempestPico\Support\Html\Exception;

class InvalidTag extends HtmlBuilderException implements HasContext {
    public function __construct(private string $tag) {
        parent::__construct("The HTML tag {$tag} is unknown.");
    }
    public function context(): array {
        return ['tag' => $this->tag];
    }
}

Then import it:

use TempestPico\Support\Html\Exception\InvalidTag;

❌ "Cannot access offset on mixed"

Fix: Add explicit array type hints:

/** @var array<string, string> $config */
$config = $arr->toArray();

PHPUnit & Testing

Deployment & Static Generation

# Generate static HTML (GitHub Pages)
./tempest static:generate --verbose
pnpm unocss

# Clean after deploy
./tempest static:clean --force

Git Workflow

Current Branch: POC--View-Tree-Builder → PR #1 (View Tree Builder)

Before pushing:

  1. Run composer qa (must pass)
  2. Verify no PHPStan errors: vendor/bin/phpstan analyse
  3. Commit with short meaningful message using a Git Emoji

Tips for AI Agents