PHPackages                             zephyrus-framework/leaf-core - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. zephyrus-framework/leaf-core

ActiveLibrary[Framework](/categories/framework)

zephyrus-framework/leaf-core
============================

Static site generator core for Zephyrus. Build, SEO, content parsing, multi-locale support.

21↓100%PHP

Since Apr 19Pushed 1mo agoCompare

[ Source](https://github.com/ophelios-studio/zephyrus-leaf-core)[ Packagist](https://packagist.org/packages/zephyrus-framework/leaf-core)[ RSS](/packages/zephyrus-framework-leaf-core/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependenciesVersions (1)Used By (0)

Zephyrus Leaf Core
==================

[](#zephyrus-leaf-core)

Core library for building static sites with the [Zephyrus Framework](https://github.com/ophelios-studio/zephyrus). Provides the static site generator, content parsing, SEO tools, multi-locale support, and development server.

This is the **library** package. For a ready-to-use project template, see [zephyrus-framework/leaf](https://github.com/ophelios-studio/leaf).

Quick Start
-----------

[](#quick-start)

The fastest way to start a new Leaf project is with the template:

```
composer create-project zephyrus-framework/leaf my-site
cd my-site
composer dev
```

This gives you a working static site with docs, live-reload, and one-command builds out of the box.

Installation
------------

[](#installation)

If you're integrating Leaf Core into an existing Zephyrus project:

```
composer require zephyrus-framework/leaf-core
```

Architecture
------------

[](#architecture)

Leaf follows the same pattern as Zephyrus itself:

PackageTypePurpose`zephyrus-framework/leaf-core`LibraryReusable classes, updated via `composer update``zephyrus-framework/leaf`Project templateScaffold for new projects, copied on `create-project`When features are added to the core, all projects using it get them on `composer update` without manual porting.

What's Included
---------------

[](#whats-included)

### Build Pipeline

[](#build-pipeline)

- **`Leaf\BuildCommand`** - Standard build orchestrator. Handles page rendering, sitemap/robots generation, search index, and 404 handling. Supports post-build hooks for project-specific steps.
- **`Leaf\StaticSiteBuilder`** - Renders all routes through the Zephyrus application stack and writes static HTML. Supports multi-locale builds with the default locale at root.
- **`Leaf\StaticBuildResult`** - Immutable value object with build stats, errors, and the list of built pages.

### Application Bootstrap

[](#application-bootstrap)

- **`Leaf\Kernel`** - Abstract application bootstrap. Handles config loading, Latte engine setup, extension registration, and controller discovery. Projects extend this and override `createController()` for dependency injection.

### Content

[](#content)

- **`Leaf\Content\ContentLoader`** - Loads and indexes Markdown content from section/slug directory structure. Provides sidebar navigation, page ordering, and prev/next links.
- **`Leaf\Content\MarkdownParser`** - Markdown to HTML via CommonMark with GitHub Flavored Markdown, heading permalinks, front matter, and table of contents extraction.
- **`Leaf\Content\ParsedMarkdown`** - Immutable parsed document with HTML, front matter, and TOC.
- **`Leaf\Content\SearchIndexBuilder`** - Generates a JSON search index from all content files.

### SEO

[](#seo)

- **`Leaf\Seo\SitemapGenerator`** - Generates `sitemap.xml` with multi-locale `xhtml:link` hreflang alternates. Default locale URLs are at root (no prefix).
- **`Leaf\Seo\RobotsGenerator`** - Generates `robots.txt` with optional sitemap reference.

### Localization

[](#localization)

- **`Leaf\Localization\TranslationLatteExtension`** - Latte extension providing `localize()` / `i18n()` template functions and `$currentLocale`, `$defaultLocale`, `$supportedLocales` template variables.

### Development

[](#development)

- **`Leaf\DevRouter`** - PHP built-in server router with static file serving, locale prefix handling, and live-reload endpoint.
- **`Leaf\FileWatcher`** - Detects file changes for the live-reload system.

### Configuration

[](#configuration)

- **`Leaf\Config\LeafConfig`** - Typed configuration from the `leaf:` section in `config.yml`.
- **`Leaf\LeafLatteExtension`** - Injects Leaf config values as template globals (`$leafName`, `$leafBaseUrl`, `$leafProductionUrl`, etc.).

Usage
-----

[](#usage)

### Extending the Kernel

[](#extending-the-kernel)

Every Leaf project needs an `Application` class that extends `Leaf\Kernel`:

```
use Leaf\Kernel;

final class Application extends Kernel
{
    protected function createController(string $class): object
    {
        // Inject dependencies into specific controllers
        if ($class === DocsController::class) {
            return new DocsController(
                $this->contentLoader,
                $this->searchIndexBuilder,
                $this->leafConfig,
            );
        }
        return new $class();
    }
}
```

The Kernel provides these protected properties for use in `createController()`:

- `$this->contentLoader` - Content loading and navigation
- `$this->searchIndexBuilder` - Search index generation
- `$this->leafConfig` - Leaf configuration
- `$this->markdownParser` - Markdown parser
- `$this->renderEngine` - Latte template engine
- `$this->translator` - Translation service (if localization is configured)
- `$this->translationExtension` - Translation Latte extension

### Build Script

[](#build-script)

A minimal `bin/build.php`:

```
define('ROOT_DIR', dirname(__DIR__));
require ROOT_DIR . '/vendor/autoload.php';

use App\Models\Core\Application;
use Leaf\BuildCommand;

$app = new Application();
$command = new BuildCommand($app);
exit($command->run());
```

For project-specific build steps, use `onPostBuild()` and `addPaths()`:

```
$command = new BuildCommand($app);

// Add paths for parameterized routes (e.g. blog posts)
$command->addPaths(['/blog', '/blog/my-post', '/blog/another-post']);

// Run custom steps after the standard pipeline
$command->onPostBuild(function ($result, $outputDir) {
    // Generate OG images, optimize assets, etc.
    passthru('node bin/generate-og-images.js');
});

exit($command->run());
```

### Dev Server

[](#dev-server)

A minimal `bin/router.php`:

```
define('DEV_SERVER', true);
require __DIR__ . '/../vendor/autoload.php';

if ((new \Leaf\DevRouter(__DIR__ . '/..'))->handle() === false) {
    return false;
}
```

### Multi-Locale Configuration

[](#multi-locale-configuration)

In `config.yml`:

```
localization:
  locale: "en"
  supported_locales:
    - "en"
    - "fr"
  locale_path: "locale"

leaf:
  production_url: "https://example.com"
```

The default locale builds to the site root (`/`), other locales build to `/{locale}/`. The `production_url` enables automatic sitemap and robots.txt generation.

Testing
-------

[](#testing)

```
composer test
```

License
-------

[](#license)

MIT

###  Health Score

20

—

LowBetter than 13% of packages

Maintenance59

Moderate activity, may be stable

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity11

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/118052280?v=4)[ophelios](/maintainers/ophelios)[@Ophelios](https://github.com/Ophelios)

---

Top Contributors

[![dadajuice](https://avatars.githubusercontent.com/u/4491532?v=4)](https://github.com/dadajuice "dadajuice (5 commits)")

### Embed Badge

![Health badge](/badges/zephyrus-framework-leaf-core/health.svg)

```
[![Health](https://phpackages.com/badges/zephyrus-framework-leaf-core/health.svg)](https://phpackages.com/packages/zephyrus-framework-leaf-core)
```

###  Alternatives

[laravel/socialite

Laravel wrapper around OAuth 1 & OAuth 2 libraries.

5.7k104.3M822](/packages/laravel-socialite)[laravel/dusk

Laravel Dusk provides simple end-to-end testing and browser automation.

1.9k38.6M289](/packages/laravel-dusk)[pinguo/php-msf

Pinguo Micro Service Framework For PHP

1.7k4.2k](/packages/pinguo-php-msf)[nineinchnick/edatatables

Grid widget for the Yii Framework, wrapper for the DataTables jQuery plugin

173.2k](/packages/nineinchnick-edatatables)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)