Vvveb is an open source CMS with a built-in drag-and-drop page builder, written in PHP 8.1+. It supports MySQL, PostgreSQL, and SQLite databases.

The code uses an MVCC (Model-View-Controller-Component) architecture where SQL files define the model layer and HTML templates contain declarative data components via data-v-* attributes.

Table of Contents

Getting Started

Guide Description
Installation Web installer, CLI installer, configuration files written

Architecture & Core

Guide Description
Architecture MVCC pattern, request lifecycle, directory structure, entry points
Controller Guide Creating controllers, CRUD patterns, routing, request/response handling
Component Guide Data components, options, caching, lifecycle, events

Features

Guide Description
Caching System Page cache, object cache, component cache, template cache
Security CSRF, authentication, permissions, input filtering, SQL injection
REST API REST endpoints for all entities
GraphQL API GraphQL schema, queries, mutations, transforms

Extension

Guide Description
Plugin Introduction What plugins are, packaging and activation
Plugin Development Plugin structure, routes, controllers, components, events
Theme Development Theme structure, components, editor support, child themes
Template Engine (Vtpl) Template syntax, modifiers, components, interpolation

Model Layer

Guide Description
SqlP SQL parser, stored procedures, macros, code generation
Events Introduction Event system, registering triggers
Events List All available events you can hook into

Page Builder

Guide Description
VvvebJs Page Builder JavaScript page builder architecture
Components Creating page builder components
Inputs Custom property inputs
Events Editor events and undo manager

API & Headless

Guide Description
GraphQL Setup Enabling and configuring GraphQL
GraphQL Schema Schema types and field definitions
REST API Setup Enabling and configuring REST API

Quick Start

Development Environment

  1. Clone the repository:
git clone --recurse-submodules https://github.com/givanz/Vvveb
  1. Install dependencies:
composer install

  1. Configure database in config/db.php

  2. Point your web server to the public/ directory

  3. Open http://localhost/ - the installer will run automatically

CLI Installation

php cli.php install module=index host=127.0.0.1 user=root password=1234 database=vvveb admin[email]=admin@vvveb.com admin[password]=admin engine=mysqli

Key Entry Points

File Purpose
public/index.php Main web entry point; includes the root index.php dispatcher
index.php Framework dispatcher (sets APP, boots system/core/startup.php, serves page cache) - included by public/, admin/, rest/, graphql/ entries
admin/index.php Admin panel entry point (APP = admin)
cli.php Command-line interface
rest/index.php REST API entry point (APP = rest)
graphql/index.php GraphQL API entry point (APP = graphql)
mcp/index.php MCP (AI) API entry point (dispatched as /mcpa/* from the root index.php)

Configuration

File Purpose
config/db.php Database connection settings
config/app.php Application settings (cache driver, etc.)
env.php Environment constants (DEBUG, PAGE_CACHE, etc.)
config/app-routes.php Front-end URL routes
config/admin-menu.php Admin sidebar navigation
config/rest-routes.php REST API routes
config/graphql-routes.php GraphQL routes

Running Tests

Tests use the phpunit launcher and phpunit.xml at the project root (suites: system, model). Model-test database selection is documented in Testing.

# Run all tests
php phpunit

# Run a specific test suite ("system" or "model")
php phpunit --testsuite system
php phpunit --testsuite model

Code Quality

# PHPStan static analysis
vendor/bin/phpstan analyse

# PHP-CS-Fixer code style
php php-cs-fixer.phar fix

Architecture Overview

HTTP Request → index.php → startup.php (bootstrap)
    → FrontController::dispatch()
    → Routes::match() (URL routing)
    → FrontController::call()
        → Base::init() (auth, permissions, menu)
        → Controller::action()
        → View::render()
            → Component::loadComponents() (data-v-component-* discovery)
            → Vtpl compile (HTML → PHP)
            → Include compiled template
        → Response::output()

The key innovation is that templates drive data loading. HTML templates declare their data needs via data-v-component-* attributes, and the component system automatically discovers, executes, and caches the data queries - controllers only need to set the template.

Directory Structure

├── app/                    # Front-end application
│   ├── controller/         # Front-end controllers
│   ├── component/          # Data components (data-v-component-*)
│   ├── template/           # HTML templates
│   ├── sql/                # SQL model definitions
│   └── validate/           # Validation rules
├── admin/                  # Admin back-end
│   ├── controller/         # Admin controllers
│   ├── component/          # Admin data components
│   ├── template/           # Admin templates
│   ├── sql/                # SQL model definitions
│   └── validate/           # Validation rules
├── system/                 # Core framework
│   ├── core/               # Bootstrap, FrontController, Request, Response, View
│   ├── cache/              # Cache drivers (file, apcu, memcached, redis)
│   ├── db/                 # Database drivers (mysqli, pgsql, sqlite)
│   ├── session/            # Session drivers (php, request)
│   ├── extensions/         # Plugin and theme management
│   ├── sqlp/               # SQL parser and code generator
│   ├── vtpl/               # Template engine
│   ├── user/               # Authentication (Admin, User, Role)
│   ├── meta/               # SEO/meta handling
│   ├── media/              # Image processing
│   └── mail/               # Email sending
├── plugins/                # ~100 plugins
├── config/                 # Configuration files
├── public/                 # Web-accessible assets
│   ├── themes/             # front-end themes
│   ├── admin/              # Admin theme assets
│   ├── js/                 # JavaScript (page builder)
│   └── media/              # User-uploaded files
├── rest/                   # REST API
├── graphql/                # GraphQL API
├── storage/                # Runtime storage (cache, compiled templates, backups)
└── locale/                 # Translation files

Database Support

Driver Class Database
MySQLi Vvveb\System\Db\Mysqli MySQL 5.7+ / MariaDB 10.2+
PostgreSQL Vvveb\System\Db\Pgsql PostgreSQL 11+
SQLite Vvveb\System\Db\Sqlite SQLite 3

SQL models are defined in .sql files using a stored-procedure DSL and auto-generated into PHP classes by the SqlP parser.

System Requirements

  • PHP: 8.1 or newer (required by composer.json)
  • Extensions: mysqli or sqlite3 or pgsql, xml, pcre, zip, dom, curl, gettext, gd or imagick
  • Database: MySQL 5.7+, MariaDB 10.2+, PostgreSQL 11+, or SQLite 3

License

GNU Affero General Public License Version 3 (AGPLv3) or any later version