Download the PHP package taujor/phpssg without Composer

💖 PHPSSG is open source and free.
If you find it useful, please consider sponsoring me to support continued development.

PHPSSG (Personal Home Page Static Site Generator)

A lightweight, PHP-native static site generator for building composable templates.
PHPSSG uses invokable component classes, output buffering, and plain PHP templates to provide a clean developer experience — no third-party templating engine required, but you are welcome to use one.

Features

• Plain PHP templates – no special syntax to learn.
• Invokable components – use components like $header().
• Component based routing – Buildable components get methods able to write the html they generate to a file.
• Hooks – Hooks are available to easily inject your own custom code to manipulate content during the component lifecycle.
• Centralized render helper – avoids repeated ob_start() / ob_get_clean().
• Nesting & composition – layouts can include multiple components.
• PHAR Support – easily ran as a phar if desired.
• Slots & data passing – inject content into templates easily.
• Incremental builds – files are rewritten only if content changes (xxh3 hash comparison).
• Caching – file paths and contents are hashed and cached to disk prioritizing thread safety.
• Native debugging – works seamlessly with standard PHP tools.
• PSR-4 compliant – fully autoloadable via Composer.
• Abstract Classes – Renderable, Composable, Buildable help define component APIs, they are fundamental to PHPSSG.
• IDE-friendly – docblocks provide autocomplete, type hints, and method signatures.
• Highly portable – works in any PHP 8.1+ environment.
• Flexible structure – There are no rules that force you to structure your project a certain way, I have made suggestions and set some reconfigurable defaults but beyond that I leave everything completely up to you.
• Fast content comparison – via xxh3 hashing.

Requirements

• PHP 8.1+ (xxh3 hashing)
• Composer (autoloading)
• PHP-DI (dependency injection)

Quick start

Clone the skeleton template repo or visit the repo and click "Use this template"

Installation

Install via Composer:

Run a local development server:

Usage

Layouts

Layouts are typically Renderables:

Components

Components are typically Renderables (like layouts) or Composables :

Title and Subtitle are Renderables (in this example) they have their own respective template files, however our Heading class simply takes these two components and "composes" them into a new component (via string concatenation in this case). Hence it does not require its own template file but can still be invoked just the same as any other presenter.

The render method of Renderable extracts variables into the template and returns the output as a string.

Pages

Pages are typically Buildables, like Composables they are self-contained, and do not need separate view templates. They inherit the compile and build methods which output html files to the build directory (public by default):

Pages often combine components and layouts. The $data argument is passed to the page during the build process. $data is then passed to components via their respective __invoke() methods. Then finally the layout wraps the combined HTML content.

Utilities

Utilities are typically helper classes that provide additional functionality to phpssg. You can use utility classes to implement things like alternative renderers (twig for example), provide custom methods to your components, etc.

This utility class can be used to locate the root of a composer project, this example is derrived from the Locate utility class used throughout this project, see the "build scripts" section for details on how Locate is used for configuration.

You can even extend an abstract class such as Renderable to support entirely different templating systems such as twig or markdown and using your extended class in your components instead of the defaults. In a future release there will be separate offically maintained integrations you can install via composer that will extend PHPSSG's core features this way, but don't let that stop you from creating your own that are specfic to your individual project.

Views

Stored in src/views (by default). Only Renderables have view templates. Composables and Buildables don't require view templates. Views are plain php templates, I recommend their directory structure mirrors that of the Renderables in your presenters/ directory for example:

Hooks

Hooks provide lifecycle entry points for customizing the behavior of your components.
They are defined in the base Composable, Renderable, and Buildable contracts, and are automatically called at key points in the rendering or build process.

Hooks are optional — override only those you need.
They are always protected and are intended for internal subclass use only.

Composable Hooks

Composable components are pure PHP objects that produce HTML by combining other components.

Example:

Renderable Hooks

Renderable components generate HTML from PHP view templates.

Example:

Buildable Hooks

Buildable components handle static file generation and support a full pre/post lifecycle around rendering and writing output.

Example:

Build scripts

This is the entry point of the application often placed in the scripts directory at the root of your project. They call on Buildable presenters to generate html using the compile or build static methods. The compile method takes a target path relative to your build directory, the generated html will be sent to this path. The second parameter supports either an array or object containing data you would like to __invoke the Buildable with. The build method simply iterates over your dataset and runs compile on each item. You can also use placeholder syntax to use any top level value in your dataset to generate unique filenames. For example:

Project Structure

There are no mandated directory names or conventions, you can decide how you like to structure your project. However I have provided some sane default directories you can see in the next section that will work with zero configuration.

Suggested Structure

There are some directories PHPSSG needs to have around, those being a views, build, and cache directory (marked as REQUIRED). You are free to reconfigure them as needed but if they are missing the project will not work as expected. The cache and it's sub-directories are automatically created during runtime if they don't already exist.

• config/ – bootstrap and environment setup.
• public/ – REQUIRED build directory, CSS, JS, and other web-facing assets.
• scripts/ – build scripts and/or other tooling.
• presenters/ – invokable PHP classes for logic (can be Buildable, Composable, or Renderable).
• presenters/components/ – reusable UI blocks typically Renderables or Composables.
• presenters/layouts/ – reusable page skeletons typically Renderables.
• presenters/pages/ – page-level composables or buildables.
• views/ – REQUIRED plain php templates.
• views/components/ – templates for Renderable components.
• views/layout/ – templates for Renderable layouts.
• utilities/ – helpers like Locate, TwigRenderer, PrettyPrint. Make them do anything!

Configuration

At the entry point of the PHPSSG application (commonly the build script) you can use the Locate class to tinker with your project layout.

As you can see above the Locate utility class provides static methods that can both override and return the configured location. Once an override is set further overrides will be ignored for the duration of the runtime, you can bypass this using Locate::reset() which will revert all changes to default.

Locate is used througout PHPSSG to get configuration data, it works lazily, inteligently setting defaults the first time it is called and caching them in memory, subsequent calls always return the cached location rather than whatever is in the $override argument or expected by default. Calling Locate::reset() clears this cache, setting each static variable to null. Then when a method of Locate is called again it will either cache and return it's defaults or use the supplied override.

Here is a list of Locate's default settings:

Default Configuration

Contributing

Contributions are welcome! Philosophy:

• Minimalism First – lightweight and simple, avoid heavy libraries.
• Developer-Friendly – components should be easy to understand and compose.
• Consistency – follow presenters/, views/, utilities/ structure.
• Backward Compatibility – avoid breaking APIs unless clearly beneficial.

Planned Features

• [x] Packagist Release - use composer to install phpssg with ease.
• [x] Hooks - add extensibility to the build process.
• [x] Caching – reduce build times for large projects.
• [x] Templates – premade templates to start projects quickly.
• [ ] Documentation Website – phpssg.com for guides and community resources.
• [ ] Tutorials – step-by-step guides on using PHPSSG effectively.