README

The Vinou Site-Builder is a PHP library that combines PHP routing configured in YAML files with Twig template rendering. It provides a data processing pipeline to call registered processors and pipe results directly into Twig templates.

Table of contents

• Typical project structure
• Installation
• Route configuration
  1. General route parameters
  2. Sitemap configuration
  3. dataProcessing
  4. Extend a parent route
  5. Global content (additionalContent)
  6. Registered processors
  7. Register your own processor
• Settings
• Template override hierarchy
• Twig filters
• Structured data (JSON-LD)
• Classlist
• Provider

Typical project structure

The complete example project is available in Examples/Project/.

Installation

composer require vinou/site-builder
cp -R vendor/vinou/site-builder/Examples/Project/config ./
cp -R vendor/vinou/site-builder/Examples/Project/web ./

Required after installation:

• Set Vinou authid and token in config/settings.yml — find them in Vinou Office
• Set SMTP credentials in config/mail.yml

Typical optional setup:

• Add project routes to config/routes.yml
• Configure Vinou constants in public/index.php

Minimal public/index.php:

<?php
require_once __DIR__ . '/../vendor/autoload.php';

define('VINOU_ROOT', realpath('./'));
define('VINOU_MODE', 'Shop');
define('VINOU_CONFIG_DIR', '../config/');

$session = new \Vinou\ApiConnector\Session\Session();
$session::setValue('language', 'de');

$site = new \Vinou\SiteBuilder\Site();
$site->setRouteFile('routes.yml');
$site->loadTheme('my-theme', 'Theme/MyTheme/');
$site->run();

Route configuration

1. General route parameters

2. Sitemap configuration for a route

Use sitemap as an array on routes with a URL wildcard to generate one sitemap entry per item:

weine/{path_segment}:
  template: 'Wines/Detail.twig'
  pageTitle: 'Wein-Details'
  public: true
  sitemap:
    function: getWinesAll
    params:
      lazy: false
      pageSize: 500
    dataKey: 'wines'
  dataProcessing:
    wine: getWine

3. Use dataProcessing

Each entry in dataProcessing calls a function in a processor and stores the result under the given key in the Twig context.

Shorthand — calls an API-Connector function directly:

dataProcessing:
  wines: getWinesAll
  wineries: getWineriesAll

Full syntax:

dataProcessing:
  wines:
    function: getWinesAll
    params:
      pageSize: 50
      orderBy: topseller DESC
      cluster:
        - type
        - taste_id
        - vintage

Combining data with formatter/mergeData:

dataProcessing:
  wines:
    function: getWinesAll
  bundles:
    function: getBundlesAll
  items:
    processor: formatter
    function: mergeData
    useRouteData: false
    useData:
      - wines
      - bundles

mergeData flattens sub-arrays into one list and sets object_type per entry (e.g. wines, bundles).

Full parameter reference:

4. Extend a parent route

Setting extend: true on a project route causes it to deep-merge (array_replace_recursive) with the existing route definition from the theme instead of replacing it entirely. Only the keys you define are overridden; all other settings are inherited.

# config/routes.yml
weine:
  extend: true
  pageTitle: 'Unser Weinshop'      # overrides theme value
  dataProcessing:
    text:                           # added on top of theme dataProcessing
      function: getText
      params:
        identifier: 'weine'

Without extend: true, the project route replaces the theme route completely.

5. Global content (additionalContent)

additionalContent is defined in settings.yml (typically in the theme) and runs on every page before route-specific dataProcessing. Results are available in all templates.

# Theme/MyTheme/Configuration/settings.yml
additionalContent:
  categories:
    function: getCategoriesAll
    params:
      orderBy: sorting ASC
  client: getClient
  paymentMethods:
    function: getAvailablePayments
    key: payments

To skip specific items on a route, use excludeContent:

# config/routes.yml
kontakt:
  template: 'Pages/kontakt.twig'
  excludeContent: [categories]
  dataProcessing:
    captcha:
      processor: mailer
      function: loadCaptcha

6. Registered processors

7. Register your own processor

Create a processor class:

<?php
namespace YourVendor\YourNamespace\Processors;

class YourProcessor extends \Vinou\SiteBuilder\Processors\AbstractProcessor {

    public function dataMagic($data = null) {
        // transform data here
        return $data;
    }

}

Register it in index.php before calling $site->run():

$site = new \Vinou\SiteBuilder\Site();
$site->render->loadProcessor('myprocessor', new \YourVendor\YourNamespace\Processors\YourProcessor());
$site->run();

Use it in a route:

my-route:
  template: 'Pages/template.twig'
  dataProcessing:
    result:
      processor: myprocessor
      function: dataMagic
      params:
        foo: bar

Settings

Settings are loaded from YAML files and merged in this order (later wins):

1. Theme: YourTheme/Configuration/settings.yml
2. Project: config/settings.yml

The theme controls whether SiteBuilder built-in defaults are loaded:

system:
  load:
    defaultRoutes: false    # disable SiteBuilder's bundled routes
    defaultSettings: false  # disable SiteBuilder's bundled settings

Global settings reference (settings key):

Geo blocking (settings.geoBlocking):

settings:
  geoBlocking:
    allowedCountries: [de]   # allow list: every other known country is blocked
    countries: []            # block list, e.g. [dk] (wins if a code is in both lists)
    paths: [weine, weinpakete, produkte, kategorie, suche, warenkorb, checkout, client]  # '*' = whole site
    exceptions: [impressum, datenschutz, agb, widerruf, system]  # always reachable
    countryHeader: ~         # optional country header of the host/CDN, e.g. HTTP_CF_IPCOUNTRY

Both lists empty = off. Blocked pages answer with HTTP 451 (GeoBlocked.twig), adding items to the basket via ajax with 403. The country comes from countryHeader or the local DB-IP database in config/geoip/ (vendor/bin/vinou geoip:update, e.g. in the CI build). Fail-open: without database, for private IPs or unknown countries nothing is blocked.

Template override hierarchy

SiteBuilder uses Twig's FilesystemLoader with an ordered list of directories. The first matching template wins.

Default search order:

1. public/Resources/Templates/ — project
2. public/Resources/Partials/ — project
3. public/Resources/Layouts/ — project
4. Theme/Resources/Layouts/ — theme
5. Theme/Resources/Partials/ — theme
6. Theme/Resources/Templates/ — theme

A template in public/Resources/Templates/Wines/List.twig will silently override Theme/Resources/Templates/Wines/List.twig.

The same priority applies to route loading:

1. SiteBuilder built-in routes (lowest priority, loaded as base)
2. Theme routes (override SiteBuilder)
3. Project config/routes.yml (highest priority)

Twig filters

All filters are registered by \Vinou\SiteBuilder\Tools\Render.

Structured data (JSON-LD)

The Twig function structuredData() renders schema.org data as a <script type="application/ld+json"> tag. The data is built in \Vinou\SiteBuilder\Tools\StructuredData; the theme only decides where it is placed (the Vinou shop theme uses Partials/General/Head.twig).

Request values (domain, path, client, customer) come from the template context. Merchants (customer.type == 'merchant') use the winery as brand. Texts are encoded with JSON_HEX_TAG, so HTML from the API cannot close the tag.

Optional setting:

settings:
  seo:
    logo: /Assets/Images/logo.png   # webroot-relative or absolute URL

Classlist

Admin panel

The SiteBuilder ships with a built-in admin panel at /system. It is activated automatically when the project settings contain admin credentials and provides a HTMX-driven single-page interface for managing settings, users, redirects, routes, mail configuration, and system state.

Activation

Site::loadAdminPanel() registers the panel routes when either of the following keys is present in config/settings.yml:

# Option A — legacy single-password (useful for initial bootstrap)
system:
  password: 'my-password'

# Option B — multi-user (production)
system:
  users:
    - email: admin@example.com
      password: '$2y$10$…'   # bcrypt hash, auto-generated on first save via the panel

Both keys can coexist temporarily during the bootstrap process. Once system.users is populated, system.password can be removed.

Login flow

Single-password mode (no system.users):

1. Enter password.
2. If system-level TOTP is configured (system.totp_secrets): redirect to /system/totp.
3. Otherwise: panel access granted.

Multi-user mode (system.users present):

1. Enter email + password.
2. Account has no totp_secrets → redirected to /system/totp/first-setup (forced; cannot be skipped).
3. Account has totp_secrets → redirected to /system/totp (TOTP verification).
4. Correct TOTP code → panel access granted.

Session keys used during the flow:

Security

Bootstrap workflow for new projects

1. Add system.password: 'bootstrap' to config/settings.yml to activate the panel.
2. Log in (single-password mode, no email field shown).
3. Open the Benutzer tab → create the first user (email + password).
4. Log out, log in as the new user.
5. The forced first-time 2FA screen appears — scan the QR code and enter the confirmation code.
6. Delete system.password from config/settings.yml. The panel stays active because system.users is now populated.

URL structure

Panel tabs

Settings whitelist

The Settings panel only displays and allows editing of keys listed in SETTINGS_WHITELIST:

private const SETTINGS_WHITELIST = ['additionalContent', 'settings', 'vinou'];

All other top-level keys (system, shop, etc.) are never exposed or writable through the panel UI.

User data structure

system:
  users:
    - email: admin@example.com
      password: '$2y$10$…'           # bcrypt
      totp_secrets:
        - name: 'My iPhone'
          secret: 'ABCDEFGHIJKLMNOP' # base32-encoded TOTP secret
        - name: 'Backup key'
          secret: 'QRSTUVWXYZ234567'

Each user manages their own totp_secrets. The system-level totp_secrets / totp_secret keys are only used in legacy single-password mode.

Template structure

Admin/Panel.twig           Shell: <head> with CSS, HTMX, qrcodejs; navigation; #section-content
Admin/Sections/
  Settings.twig            Settings editor (section.settings, section.projectPaths)
  Users.twig               User list + edit forms + own TOTP management
                           (section.users, section.currentEmail, section.totpApps, …)
  Redirects.twig           Redirect CRUD (section.redirects)
  Routes.twig              Route tree (section.routes)
  Mail.twig                SMTP + form config (section.mailConfig)
  System.twig              Cache cards + PHP checks + Vinou packages
                           (section.environment, section.vinouPackages)

qrcodejs is loaded once in Panel.twig's <head> to avoid HTMX script-loading race conditions.

Static assets

CSS (admin.css) and JS (htmx.min.js) are served via a PHP closure from vendor/vinou/site-builder/Resources/Public/. SCSS source: Resources/Sass/Admin/panel.scss.

Provider

This library is developed by Vinou GmbH.

Vinou GmbH
Justus-von-Liebig-Straße 9e
55232 Alzey
E-Mail: kontakt@vinou.de
Phone: +49 6131 6245390