Vvveb\Component\Product\Variants) lists the variants of a product (combinations of option values, e.g. size × color) with variant-specific prices, images and URLs.
Activate the component by adding:
data-v-component-product-variants
Component Options
Add options as HTML attributes using the data-v-* syntax.
| Option | Attribute | Description | Default |
|---|---|---|---|
| start | data-v-start |
Starting offset | 0 |
| limit | data-v-limit |
Number of variants (null = all) |
null |
| site_id | data-v-site_id |
Site ID | Current site |
| language_id | data-v-language_id |
Language ID | Current language |
| product_id | data-v-product_id |
Product ID, from URL by default | url |
| parent_id | data-v-parent_id |
Filter by parent | null |
| search | data-v-search |
Filter by text | null |
| name | data-v-name |
Filter by variant name | null |
| url | data-v-url |
Filter by variant URL | null |
Component Properties
Variants render inside data-v-variant repeatables with nested data-v-value entries for the option-value combination. Fields include variant name, sku, price / price_formatted (tax-aware), image, url / full-url and stock data. The component also exposes count and the product_variant list.
HTML Example
<div data-v-component-product-variants>
<div data-v-variant>
<span data-v-variant-name></span>
<span data-v-variant-price_formatted></span>
</div>
</div>
Vvveb\Component\Fields) renders custom field values for posts, products, users, orders and taxonomy items. The type option selects the entity; without a valid type the component returns an empty array. Caching is disabled ($cacheExpire = 0).
Activate the component by adding:
data-v-component-fields
Component Options
Add options as HTML attributes using the data-v-* syntax.
| Option | Attribute | Description | Default |
|---|---|---|---|
| start | data-v-start |
Starting offset | 0 |
| limit | data-v-limit |
Number of fields to display | 100 |
| site_id | data-v-site_id |
Site ID | Current site |
| language_id | data-v-language_id |
Language ID | Current language |
| type | data-v-type |
Entity type: post, product, user, order, taxonomy_item (required) |
null |
| subtype | data-v-subtype |
Field subtype filter | null |
| post_type | data-v-post_type |
Post type context | null |
| product_id | data-v-product_id |
Filter by product, from URL by default | url |
| post_id | data-v-post_id |
Filter by post, from URL by default | url |
| user_id | data-v-user_id |
Filter by user, from URL by default | url |
| order_id | data-v-order_id |
Filter by order, from URL by default | url |
| taxonomy_item_id | data-v-taxonomy_item_id |
Filter by category/tag, from URL by default | url |
| field_id | data-v-field_id |
Filter to specific field IDs (array) | null |
| field_group_id | data-v-field_group_id |
Filter by field group | null |
Component Properties
Each field is wrapped in an element marked with data-v-field. The component decodes the settings JSON into name/type and exposes the stored value (JSON-decoded when it holds an object). Nested sub-fields render inside data-v-subfields / data-v-subfields-field.
HTML Example
<div data-v-component-fields data-v-type="product" data-v-product_id="url">
<div data-v-field>
<span data-v-field-name>Field name</span>
<span data-v-field-value>Field value</span>
</div>
</div>
Notes
typemust be one ofpost,product,user,order,taxonomy_item; any other value returns nothing.- Entity ID options (
product_id,post_id, …) default tourl, i.e. they are read from the page GET parameters on detail pages.
Vvveb\Component\Product\Subscriptions) lists the subscription plans attached to a product (recurring purchase options shown next to the one-time price).
Activate the component by adding:
data-v-component-product-subscriptions
Component Options
Add options as HTML attributes using the data-v-* syntax.
| Option | Attribute | Description | Default |
|---|---|---|---|
| start | data-v-start |
Starting offset | 0 |
| limit | data-v-limit |
Number of subscriptions | 7 |
| site_id | data-v-site_id |
Site ID | Current site |
| language_id | data-v-language_id |
Language ID | Current language |
| product_id | data-v-product_id |
Product ID, from URL by default | url |
| parent_id | data-v-parent_id |
Filter by parent | null |
| search | data-v-search |
Filter by text | null |
Component Properties
Each subscription renders inside a data-v-subscription repeatable with plan name, billing period, price / price_formatted and trial fields. The component also exposes count.
HTML Example
<div data-v-component-product-subscriptions>
<div data-v-subscription>
<span data-v-subscription-name></span>
<span data-v-subscription-price_formatted></span>
</div>
</div>
Notes
- For the standalone subscription-plan catalogue see the product-subscription-plans component (
data-v-component-product-subscription-plans).
Vvveb\Component\Product\Filters) lists filter definitions for a product (faceted-search filter values). Note: there is no dedicated product/filters.tpl template file, so rendering uses the generic data-v-* attribute binding for the returned filter records.
Activate the component by adding:
data-v-component-product-filters
Component Options
Add options as HTML attributes using the data-v-* syntax.
| Option | Attribute | Description | Default |
|---|---|---|---|
| start | data-v-start |
Starting offset | 0 |
| limit | data-v-limit |
Number of filters | 100 |
| site_id | data-v-site_id |
Site ID | Current site |
| language_id | data-v-language_id |
Language ID | Current language |
| product_id | data-v-product_id |
Product ID, from URL by default | url |
| search | data-v-search |
Filter by text | null |
| image_size | data-v-image_size |
Filter image size | thumb |
Component Properties
Filter records with name, value and image fields, bound with generic data-v-filter-* attributes.
HTML Example
<div data-v-component-product-filters>
<div data-v-filter>
<span data-v-filter-name></span>
</div>
</div>
Vvveb\Component\Product\Category) displays a single product category. It extends the base category component (Vvveb\Component\Category) without changing options, so it auto-detects the category from the page URL on product category pages.
Activate the component by adding:
data-v-component-product-category
Component Options
Same as the category component:
| Option | Attribute | Description | Default |
|---|---|---|---|
| taxonomy_item_id | data-v-taxonomy_item_id |
Category ID, from URL by default | url |
| slug | data-v-slug |
Category slug, from URL by default | url |
| type | data-v-type |
Taxonomy type | null |
| post_type | data-v-post_type |
Post type | null |
| language_id | data-v-language_id |
Language ID | Current language |
| site_id | data-v-site_id |
Site ID | Current site |
Component Properties
Single-category fields through data-v-category-*: name, slug, content, image, image_url, url, full-url, count.
HTML Example
<div data-v-component-product-category>
<h1 data-v-category-name></h1>
<div data-v-category-content></div>
</div>
Vvveb\Component\Product\Subscription\Plans) lists subscription plans for a product from the subscription catalogue (billing cycles available for recurring orders).
Activate the component by adding:
data-v-component-product-subscription-plans
Component Options
Add options as HTML attributes using the data-v-* syntax.
| Option | Attribute | Description | Default |
|---|---|---|---|
| start | data-v-start |
Starting offset | 0 |
| limit | data-v-limit |
Number of plans | 7 |
| site_id | data-v-site_id |
Site ID | Current site |
| language_id | data-v-language_id |
Language ID | Current language |
| product_id | data-v-product_id |
Product ID, from URL by default | url |
| parent_id | data-v-parent_id |
Filter by parent | null |
| search | data-v-search |
Filter by text | null |
Component Properties
Each plan exposes the subscription-plan record fields (name, billing frequency, price / price_formatted, trial data).
HTML Example
<div data-v-component-product-subscription-plans>
<div data-v-plan>
<span data-v-plan-name></span>
<span data-v-plan-price_formatted></span>
</div>
</div>
Vvveb\Component\Content\Categories) is the post-scoped twin of the categories component: it lists categories-type taxonomy items for post post types (blog categories). For product taxonomies use product-categories instead.
Activate the component by adding:
data-v-component-content-categories
Component Options
Add options as HTML attributes using the data-v-* syntax.
| Option | Attribute | Description | Default |
|---|---|---|---|
| start | data-v-start |
Starting offset | 0 |
| limit | data-v-limit |
Number of categories | 7 |
| site_id | data-v-site_id |
Site ID | Current site |
| language_id | data-v-language_id |
Language ID | Current language |
| order | data-v-order |
Sorting rules, overridable from URL | url fallback price asc |
| taxonomy_id | data-v-taxonomy_id |
Filter by taxonomy ID | null |
| post_id | data-v-post_id |
Show only categories assigned to a post | null |
| parent_id | data-v-parent_id |
Filter by parent (0 = top-level) |
null |
| search | data-v-search |
Filter by text | null |
| type | data-v-type |
Taxonomy type | categories |
| post_type | data-v-post_type |
Post type | post |
| parents_only | data-v-parents_only |
Only parent categories | false |
| parents_children_only | data-v-parents_children_only |
Only parents that have children | false |
| parents_without_children | data-v-parents_without_children |
Only parents without children | false |
Component Properties
Same as the categories component: data-v-cats container with data-v-cat repeatables exposing name, slug, url, image, count, and nested children.
HTML Example
<div data-v-component-content-categories data-v-limit="7">
<div data-v-cats>
<div data-v-cat>
<a href="" data-v-cat-url><span data-v-cat-name></span></a>
</div>
</div>
</div>
Vvveb\Component\Product\Options) lists the selectable options of a product (dropdowns, radios, checkboxes, file uploads) with their values and price modifiers. It is used on product pages to render the option selectors.
Activate the component by adding:
data-v-component-product-options
Component Options
Add options as HTML attributes using the data-v-* syntax.
| Option | Attribute | Description | Default |
|---|---|---|---|
| start | data-v-start |
Starting offset | 0 |
| limit | data-v-limit |
Number of options (null = all) |
null |
| site_id | data-v-site_id |
Site ID | Current site |
| language_id | data-v-language_id |
Language ID | Current language |
| product_id | data-v-product_id |
Product ID, from URL by default | url |
| product_variant_id | data-v-product_variant_id |
Pre-select values for a variant | null |
| parent_id | data-v-parent_id |
Filter by parent option | null |
| search | data-v-search |
Filter by text | null |
| image_size | data-v-image_size |
Option-value image size | thumb |
Component Properties
Options render inside data-v-option repeatables with nested data-v-value repeats for the selectable values. Fields include option name, type (select, radio, checkbox, …), required flag, and per-value name, price / price_formatted modifiers and images. The component also exposes count.
HTML Example
<div data-v-component-product-options>
<div data-v-option>
<label data-v-option-name></label>
<div data-v-value>
<span data-v-value-name></span>
<span data-v-value-price_formatted></span>
</div>
</div>
</div>
Vvveb\Component\Content\Tags) lists tags-type taxonomy items for posts (blog tags cloud / tag index).
Activate the component by adding:
data-v-component-content-tags
Component Options
Add options as HTML attributes using the data-v-* syntax.
| Option | Attribute | Description | Default |
|---|---|---|---|
| start | data-v-start |
Starting offset | 0 |
| limit | data-v-limit |
Number of tags | 7 |
| page | data-v-page |
Page number | 1 |
| language_id | data-v-language_id |
Language ID | Current language |
| count | data-v-count |
Include post counts | null |
| order | data-v-order |
Sorting rules, overridable from URL | url fallback price asc |
| type | data-v-type |
Taxonomy type | tags |
| post_type | data-v-post_type |
Post type | post |
| id_manufacturer | data-v-id_manufacturer |
Legacy filter | null |
| id_category | data-v-id_category |
Legacy filter | null |
| parents_only | data-v-parents_only |
Only parent tags | false |
| parents_children_only | data-v-parents_children_only |
Only parents with children | false |
| parents_without_children | data-v-parents_without_children |
Only parents without children | false |
Component Properties
Tags render inside data-v-tags / data-v-archive repeatables with name, slug, url and count fields.
HTML Example
<div data-v-component-content-tags data-v-limit="20">
<div data-v-tags>
<div data-v-archive>
<a href="" data-v-archive-url><span data-v-archive-name></span></a>
</div>
</div>
</div>
Vvveb\Component\Product\Attributes) lists attribute values for a product (specification table: e.g. color, size, material).
Activate the component by adding:
data-v-component-product-attributes
Component Options
Add options as HTML attributes using the data-v-* syntax.
| Option | Attribute | Description | Default |
|---|---|---|---|
| start | data-v-start |
Starting offset | 0 |
| limit | data-v-limit |
Number of attributes | 100 |
| site_id | data-v-site_id |
Site ID | Current site |
| language_id | data-v-language_id |
Language ID | Current language |
| product_id | data-v-product_id |
Product ID, from URL by default | url |
| search | data-v-search |
Filter by text | null |
| image_size | data-v-image_size |
Attribute image size | thumb |
Component Properties
Attributes render inside the data-v-attributes repeatable with attribute name, value, and image fields.
HTML Example
<div data-v-component-product-attributes>
<div data-v-attributes>
<span data-v-attributes-name></span>
<span data-v-attributes-value></span>
</div>
</div>
Vvveb\Component\Product\Manufacturers) lists product manufacturers (brands) with pagination and category filtering.
Activate the component by adding:
data-v-component-product-manufacturers
Component Options
Add options as HTML attributes using the data-v-* syntax.
| Option | Attribute | Description | Default |
|---|---|---|---|
| start | data-v-start |
Starting offset | 0 |
| limit | data-v-limit |
Number of manufacturers | 7 |
| page | data-v-page |
Page number | 1 |
| count | data-v-count |
Include product counts, overridable from URL | 4 |
| manufacturer_id | data-v-manufacturer_id |
Filter by manufacturer ID | null |
| category_id | data-v-category_id |
Filter by category ID | null |
| order | data-v-order |
Sorting rules, overridable from URL | url fallback price asc |
| type | data-v-type |
Record type filter | tags |
| filter | data-v-filter |
Extra filter value | null |
| parents_only | data-v-parents_only |
Only parents | false |
| parents_children_only | data-v-parents_children_only |
Only parents with children | false |
| parents_without_children | data-v-parents_without_children |
Only parents without children | false |
Component Properties
Each manufacturer renders inside a data-v-manufacturer repeatable with name, slug, image and url fields.
HTML Example
<div data-v-component-product-manufacturers data-v-limit="12">
<div data-v-manufacturer>
<a href="" data-v-manufacturer-url><span data-v-manufacturer-name></span></a>
</div>
</div>
Request Lifecycle
HTTP Request
│
▼
index.php (entry point)
│
├── env.php (environment constants)
├── system/core/startup.php (bootstrap: autoloader, error handlers, DB config)
│
▼
System\Core\start()
│
├── Sites::getSiteData() - resolve current site
├── Plugins::loadPlugins() - load active plugins
│
▼
FrontController::dispatch($site)
│
├── Routes::init() + Routes::match($uri) - URL routing
│ (cached per site/app, extensible via Event::trigger)
│
▼
FrontController::call($class, $action, $file)
│
├── include base.php (admin or app base controller)
├── include controller file
├── new $controllerClass()
├── FrontController::di($controller) - inject Request, Response, View, Session
├── $controller->init() - language, currency, permissions, menu, site settings
├── View::template('module/action.html')
├── $controller->$action()
│ │
│ ├── Sets $this->view->property = data (available in template)
│ └── Returns: false (no template), array (JSON), string (override template)
│
▼
View::render()
│
├── Component::getInstance() - discover and execute data-v-component-* attributes
│ ├── generateRequiredComponents() - parse HTML template DOM
│ ├── loadComponents() - execute each component, fetch data, cache results
│ └── Store in $view->_component[name][index]
│
├── checkNeedRecompile() - recompile HTML template to PHP if changed
├── Vtpl engine compiles HTML → PHP template
└── include compiled template (accesses $view properties + $view->_component)
│
▼
Response::output() → HTTP Response
Directory Structure
├── app/ # Front-end application
│ ├── controller/ # Front-end controllers
│ ├── component/ # Front-end components (data-v-component-*)
│ ├── template/ # Front-end HTML templates
│ ├── sql/ # Front-end SQL model definitions
│ └── validate/ # Front-end validation rules
├── admin/ # Admin back-end
│ ├── controller/ # Admin controllers
│ ├── component/ # Admin components
│ ├── template/ # Admin HTML templates
│ ├── sql/ # Admin SQL model definitions
│ └── validate/ # Admin validation rules
├── install/ # Web installer
├── 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, Auth)
│ ├── meta/ # SEO/meta handling
│ ├── media/ # Image processing
│ ├── mail/ # Email sending
│ └── import/ # Data import utilities
├── config/ # Configuration files
├── plugins/ # plugins
├── public/ # Web-accessible assets
│ ├── themes/ # front-end themes
│ ├── admin/ # Admin theme assets
│ ├── js/ # JavaScript (builder.js, etc.)
│ ├── css/ # Stylesheets
│ └── media/ # User-uploaded files
├── rest/ # REST API entry point
├── graphql/ # GraphQL API entry point
├── mcp/ # MCP (AI) integration
├── storage/ # Runtime storage (cache, compiled templates, backups)
└── locale/ # Translation files
Entry Points
| Entry Point | URL | APP Constant | Purpose |
|---|---|---|---|
index.php |
/ |
app |
Front-end website (also dispatches /rest/*, /graphql/*, /mcpa/* by URI prefix) |
public/index.php |
/ (web root) |
app |
Web-accessible front controller, includes ../index.php |
admin/index.php |
/admin/ |
admin |
Admin panel |
install/ |
/install/ |
install |
Web installer (used when the app is not installed yet) |
rest/index.php |
/rest/ |
rest |
REST API |
graphql/index.php |
/graphql/ |
graphql |
GraphQL API |
mcp/index.php |
/mcpa/* |
admin |
MCP (AI) integration (dispatched from the root index.php, runs with DISPATCH disabled) |
cli.php |
CLI | varies | Command-line interface |
The APP constant determines which application directory (app/, admin/, …) is active. The root index.php sets it from the request URI (or forces install when the app is not installed yet), then system/core/startup.php bootstraps the framework.
Autoloading
Vvveb uses a custom autoloader (Vvveb\System\Core\autoload(), registered via spl_autoload_register() in system/core/startup.php). It maps Vvveb\* namespaces to file paths with camelToUnderscore() conversion (each uppercase letter becomes _lowercase) and falls back to a lowercased path:
Vvveb\System\Core\FrontController→system/core/front_controller.phpVvveb\Controller\Product\Products→{APP}/controller/product/products.php(APPselectsapp/vsadmin/, plugin controllers are remapped perAPP)Vvveb\Component\Posts→app/component/posts.phpVvveb\Sql\ProductSQL→ auto-generated fromadmin/sql/{mysqli,pgsql,sqlite}/product.sql(engine-specific subfolder, compiled tostorage/model/) -Vvveb\Sql\Plugins\*models resolve toplugins/{slug}/sql/{engine}/*.sql
Special roots apply: Vvveb\System\*, Vvveb\Plugins\* and Vvveb\Sql\Plugins\* load from the project root, Vvveb\App\* from app/, Vvveb\Admin\* from admin/, everything else from the active APP directory.
Database Drivers
Vvveb supports three database engines via a driver pattern:
| Driver | Class | Engine |
|---|---|---|
| MySQLi | Vvveb\System\Db\Mysqli |
MySQL/MariaDB |
| PostgreSQL | Vvveb\System\Db\Pgsql |
PostgreSQL 11+ |
| SQLite | Vvveb\System\Db\Sqlite |
SQLite 3 |
The Vvveb\System\Db facade creates driver instances via Db::getInstance() using the DB_ENGINE constant set in startup.php from config/db.php.
Configuration
Configuration uses a flat PHP file system with dot-notation access:
// Read
$value = \Vvveb\config('db.default.host');
$value = \Vvveb\getSetting('site', 'name');
// Write (persists to file)
\Vvveb\setConfig('app.cache.driver', 'apcu');
\Vvveb\setSetting('site', 'name', 'My Site');
Config files live in config/ and return PHP arrays. They are loaded on-demand and cached in memory. The Config class handles loading, saving, and dot-notation navigation.
Key configuration files:
| File | Purpose |
|---|---|
config/db.php |
Database connection settings |
config/app.php |
Application settings (cache driver, 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 |
config/sites.php |
Multi-site definitions |
config/plugins.php |
Per-site plugin status |
config/mail.php |
Email/SMTP settings |
Event System
The event system provides publish-subscribe extensibility at every major lifecycle point:
// Register a listener
\Vvveb\System\Event::on('Vvveb\Component\Products', 'results', 'my-plugin', function($results) {
$results['product'] = array_filter($results['product'], fn($p) => $p['status']);
return [$results]; // listeners must return their parameters wrapped in an array
}, 1000);
// Trigger (called by framework)
\Vvveb\System\Event::trigger('Vvveb\Component\Products', 'results', $results);
// Remove listener
\Vvveb\System\Event::off('Vvveb\Component\Products', false, 'my-plugin');
Important Listeners must return all received parameters wrapped in an array (e.g.
return [$results];). If a listener returnsnullthe original parameters pass through unchanged, but any modifications are lost. Callbacks with a lower priority run first; the default priority is1000.
Events are stored per namespace and name, ordered by priority with ksort() (lower values run first) and keyed by listener id: $events[$namespace][$name][$priority][$id]. Use Event::getEvents() to inspect registered listeners.
Key lifecycle events:
| Event | When Fired |
|---|---|
FrontController::call (after) |
After controller action execution |
View::compile / compile:after |
Before/after template compilation |
View::render |
Before template rendering |
Routes::init |
When routes are compiled, before caching |
ComponentBase::__construct |
After component options are resolved |
Component class results |
After component fetches data |
Base::init-menu |
After admin menu is built |
Page Cache
When enabled (PAGE_CACHE in env.php), full-page caching serves static HTML for anonymous visitors:
- On first request,
PageCache::startCapture()begins output buffering (wired in rootindex.php) - The full page is rendered normally
PageCache::saveCache()writes the output topublic/page-cache/{host}/{path}.html- only for HTTP 200 responses that passcanSaveCache()(anonymous: no logged-in user/admin)- Subsequent requests serve the cached file directly via
getCache() - A lock/stale file pair guards concurrent regeneration; non-200 responses clean up locks and stale files
A request is cacheable (canCache()) only when: APP is app, no POST data, none of the user/cart/admin/nocache cookies are set, and the URL passes validUrl() - no ?, &, \ or .., max 4 path levels, and not under /user, /cart, /checkout or /feed. Logged-in sessions therefore bypass (not invalidate) the cache; invalidation happens explicitly via CacheManager::clearPageCache() (called when settings, plugins, themes or content are saved).
Template Engine (Vtpl)
Vtpl compiles theme HTML plus .tpl selector rules into PHP. Theme files declare data needs with data-v-component-* attributes and bind values with data-v-* attributes; the matching rules in app/template/components/*.tpl wire each attribute to the component's result array:
<!-- Theme HTML: declare the component and bind its fields -->
<div data-v-component-products data-v-limit="4" data-v-type="product">
<div data-v-product>
<h2 data-v-product-name>Product name</h2>
<span data-v-product-price_formatted>$100</span>
<a href="" data-v-product-url>View</a>
</div>
</div>
<!-- Conditional rendering, `category` is the current menu item -->
<span data-v-menu-item-name data-v-if="category.img">Has image</span>
<span data-v-menu-item-name data-v-if-not="category.type = 'text'">Documentation</span>
# app/template/components/products.tpl (excerpt): repeatable + catch-all binding
@product = [data-v-component-products] [data-v-product]
@product|deleteAllButFirstChild
@product [data-v-product-*]|innerText = $product['@@__data-v-product-(*)__@@']
Compiled templates are stored in storage/compiled-templates/ and recompiled when source files change (View::checkNeedRecompile()).
Security Model
- Single public entry point: Only
public/index.phpis exposed. All controller logic is outside the web root. - CSRF protection: per-session tokens (
admin/controller/base.phpgeneratessession csrf,checkCsrf()validates it on admin form posts, 403 on mismatch); theme forms carry<input type="hidden" name="csrf" data-v-csrf>. - Input filtering: All
$_GET,$_POST,$_COOKIE,$_FILESare recursively filtered throughRequest::filter(). - SQL injection prevention: SqlP uses parameterized queries with bound parameters.
- Password hashing:
password_hash()withPASSWORD_DEFAULT(auto-rehash on cost/algorithm changes, seeVvveb\System\User\Auth). - Permission system: allow/deny rules evaluated by
Vvveb\System\User\Role::has()and checked on controller actions. - Brute force protection: the admin login (
admin/controller/user/login.php) caps failed attempts per account and responds with "Too many login attempts, try again in one hour!".
Multi-Site Support
Vvveb supports multiple sites from a single installation. Sites are defined in config/sites.php keyed by host pattern (e.g. '* * *', 'blog *'), each entry carrying host, theme, state, site_id (plus optional template/path):
// config/sites.php (excerpt) - keys are host patterns
return [
'* * *' => [
'name' => 'admin',
'host' => '*.*.*',
'theme' => 'landing',
'state' => 'live',
'site_id' => 1,
],
];
Each site has its own:
- Theme configuration
- Plugin activation status
- Settings (stored with
site_idforeign key) - Language and currency
The Sites class (Sites::getSiteData($site_id, $path)) resolves the current site from the request hostname. Note plugins load after site resolution only for non-admin apps (Plugins::loadPlugins() is skipped when APP === 'admin').
Localization
Vvveb uses PHP's gettext extension (or a PHP fallback) for translations. Translation files are stored in locale/. Content can be translated via the admin's multi-language support, with each post/product having content in multiple languages.
Base Classes
Front-End Controller
namespace Vvveb\Controller;
class Base {
public Request $request; // Vvveb\System\Core\Request
public Response $response; // Vvveb\System\Core\Response
public View $view; // Vvveb\System\Core\View
public Session $session; // Vvveb\System\Session
protected array $global = []; // Global template data (language, locale, ...)
}
All four properties are injected by FrontController::di() before init() is called.
Admin Controller
The admin base controller (admin/controller/base.php) extends the same pattern but adds:
- CSRF token generation and validation (
checkCsrf(), 403 on mismatch) - Admin authentication via
Admin::current() - Permission checking via
$this->permission()(denies with "Your role does not have permission to access this action!") - Admin menu building from
config/admin-menu.php(cached in object cache underadmin-menu) - Site switching support
- Language and currency resolution
- Plugin loading
Creating a Controller
Front-End Controller
Create a file in app/controller/ following the module path convention:
// app/controller/product/product.php
namespace Vvveb\Controller\Product;
class Product extends \Vvveb\Controller\Base {
public function init(): void {
// Optional: runs before the action method
// Load site settings, check maintenance mode, etc.
}
public function index(): ?string {
// The action method. Return:
// null/false - use default template (product/product.html)
// string - use a different template
// array - output as JSON
$this->view->title = 'Product Page';
$this->view->product_id = $this->request->get['product_id'] ?? null;
return null; // Uses product/product.html template
}
}
This controller is accessible at URLs matching the route pattern for product/product/index.
Admin Controller
// admin/controller/product/products.php
namespace Vvveb\Controller\Product;
class Products extends \Vvveb\Controller\Base {
public string $type = 'product';
public string $list = 'product';
public string $module = 'product';
public function index(): void {
$model = model('product');
$results = $model->getAll($this->request->get);
$this->view->set($results);
$this->view->status = [
0 => __('Inactive'),
1 => __('Active'),
];
}
}
Admin controllers are accessed via query parameter: ?module=product/products.
CRUD Pattern
For standard CRUD operations, use the built-in Crud controller or CrudTrait:
namespace Vvveb\Controller\Product;
class Products extends \Vvveb\Controller\Crud {
public string $type = 'product';
public string $list = 'product';
public string $module = 'product';
// Provides: index(), save(), delete() automatically
}
The Crud trait reads POST data, instantiates the SQL model, and calls add(), edit(), or delete() automatically.
Listing Pattern
For paginated list views, extend Listing:
namespace Vvveb\Controller\Order;
class Orders extends \Vvveb\Controller\Listing {
public string $type = 'order';
public string $list = 'order';
public string $module = 'order';
public function index(): void {
parent::index(); // Handles pagination, row URLs
// Additional data
$this->view->status = getSetting('order', 'status');
}
}
Template Assignment
Controllers set data on $this->view which becomes available in the template:
// Set individual properties
$this->view->title = 'Page Title';
$this->view->posts = $results['post'];
// Set multiple properties at once
$this->view->set($results);
// Set a JSON response instead of rendering a template
return $this->results;
// Override the template file
return 'custom/template.html';
// Disable template rendering entirely (for API responses)
return false;
Request Data
Access request data through $this->request:
// GET parameters
$page = $this->request->get['page'] ?? 1;
// POST data (already filtered)
$name = $this->request->post['name'] ?? '';
// Check request method
if ($this->request->getMethod() === 'post') { ... }
// Check if AJAX
if ($this->request->isAjax()) { ... }
// File uploads
$file = $this->request->files['upload'];
Response Control
// Set response type
$this->response->setType('json');
// Set HTTP status
$this->response->setStatus(404);
// Add headers
$this->response->addHeader('X-Custom', 'value');
// Redirect
$this->response->redirect('/new-url');
// Output data as JSON
$this->response->output($data);
Session Usage
// Read
$value = $this->session->get('key');
// Write
$this->session->set('key', $value);
// Delete
$this->session->delete('key');
Error Handling
// 404 Not Found
\Vvveb\System\Core\FrontController::notFound();
// Add validation errors (displayed in admin)
$this->view->errors[] = __('Name is required');
// Add success messages
$this->view->success[] = __('Saved successfully');
Routing
Front-End Routes
Routes are defined in config/app-routes.php:
/routes['/product/{slug}'] = ['module' => 'product/product/index'];
/routes['/blog/{slug}'] = ['module' => 'content/post/index'];
/routes['/cart/add/#product_id#'] = ['module' => 'cart/cart/add'];
Pattern types (see Vvveb\System\Routes regex constants):
{name}- matches a string segment, captured as$this->request->get['name']#name#- matches a numeric segment (\d+), captured the same way{name{min,max}}/#name{min,max}#- same with length limits*- wildcard
Admin Routes
Admin uses query-string routing: ?module=controller/action¶m=value
URL Generation
URLs are generated with \Vvveb\url() by passing the module name (controller/action); the router picks a matching route pattern for that module and fills its placeholders with the given parameters:
// Generate a front-end URL from a module name
$url = \Vvveb\url('product/product/index', ['product_id' => 123, 'slug' => 'my-product']);
// e.g. results in /product/my-product when a matching pattern exists
// Admin URLs use query-string modules
$url = \Vvveb\url('product/products/index');
If no route pattern matches (e.g. missing parameters), a fallback query-string URL is returned.
Note Pass the module name, not the URL pattern:
\Vvveb\url('/product/{slug}', ...)does not resolve because patterns are not lookup keys.
Plugin Controllers
Plugins add controllers under plugins/{slug}/admin/controller/ and plugins/{slug}/app/controller/ (the folder selects the context), both using the Vvveb\Plugins\<Name>\Controller namespace:
// plugins/contact-form/admin/controller/message.php
namespace Vvveb\Plugins\ContactForm\Controller;
class Message extends \Vvveb\Controller\Base {
public function index(): void {
$this->view->data = 'Hello from plugin';
}
}
Plugin routes are registered via events in the plugin's plugin.php.
Prerequisites: worker/site in test mode, storage/ writable (Payum tokens),
cron endpoint reachable (renewals, trial counters, order expiry).
PayPal recurring (Payum, PayPal Express)
- Configure
PayPal_Expresswith sandbox API username/password/signature andtestModechecked. - Buy a subscription product as a logged-in test user with a personal sandbox buyer account.
- Expect: redirect to sandbox PayPal → approve → return creates the
recurring profile; order moves to the success status; the core
subscription row claims
PayPal_Express-<index>:I-...and goes active. - In admin, pause then resume the subscription: profile suspends/reactivates in the sandbox merchant account, local status follows.
- Cancel: profile cancels immediately; local row goes cancelled.
- Expire: profile bills until term end (
cancel_at_period_end); thecustomer.subscription.deleted-equivalent IPN flips the row to cancelled. - Swap: change
AMTviaswapSubscription(used by plan propagation).
Mollie (test mode)
- Use a
test_...api key; buy with any method (e.g. iDEAL + test issuer). - Expect: hosted checkout → return marks the order paid, cart empties, confirmation mails.
- Cancel on Mollie's page: lands on the failed page with "Payment was cancelled!", order keeps the error status, cart intact for retry.
- Refund from Mollie's dashboard: webhook path stores the refund and updates the order; local refund is inbound-only (no outbound refund button).
Stripe (test mode)
- Use
sk_test_.../pk_test_..., test card4242 4242 4242 4242. - One-time Elements: approve →
/stripe-returnverifies the intent, creates the order and confirms. Replay the return URL: must land closed on the failed page (snapshot consumed, no duplicate order). - Subscriptions: approve → subscription row links
stripe:sub_.... Advance a test clock past the trial/period: webhook creates exactly one renewal order per invoice (re-fire the event to prove idempotency), trial counters refresh. invoice.payment_failed: row syncs to failed plus a dunning log note.- Admin cancel/pause/resume/swap hit the live subscription; failures keep local status untouched with the API message shown.
- Zero-decimal check: repeat a one-time purchase in JPY - charged amount must equal the cart total, not ×100.
Double-submit and failure paths (all gateways)
- Double-click Place Order: exactly one order (single-use
submit_token; the duplicate lands on confirmation). - Decline the payment (e.g. Stripe
4000 0000 0000 0002): stay on checkout with the gateway message, cart intact, no confirmation mail. - Kill the session mid-off-site-flow: return lands on the failed page, no orphan paid-without-order state (verify against the gateway dashboard).
Cron
Hit the cron endpoint and confirm order-expire cancels only stale
not_paid/awaiting online-method orders (bank-transfer/COD untouched) and
subscription-subscription refreshes trial_left without touching billing.
defined('REST') || define('REST', true) in env.php). To disable it, define REST as false:
defined('REST') || define('REST', true);
Authentication
Authentication is done with HTTP Authorization or Bearer tokens using any admin user credentials that has REST role permissions.
curl -H 'Authorization: Bearer mytoken' 'https://demo.vvveb.com/rest/posts/hello-world-1'
curl --user demo:demo 'https://demo.vvveb.com/rest/posts/hello-world-1'
Permissions
Permission can be controlled from admin user roles and can be set for both resource and action.
Open API
Open Api documentation is provided by the Open Api plugin https://plugins.vvveb.com/product/openapi
Next.js starter
Simple sample blog built with Next.js with REST Api https://github.com/givanz/nextjs-headless-rest-vvveb
]]>This documentation outlines the primary data structures and types available for querying and mutations within the Vvveb CMS environment.
Core Commerce Types
Product (product)
The central entity for the storefront. It contains physical attributes, pricing, and associations with content and taxonomies.
| Field | Type | Description |
|---|---|---|
product_id |
ID |
Unique identifier for the product. |
|
| model | String | Product model identifier.
|
| sku | String | Stock Keeping Unit.
|
| price | Float | The current price of the product.
|
| old_price | Float | The original price (useful for showing discounts).
|
| stock_quantity | Int | Number of items currently in stock.
|
| image | String | Path to the main product image.
|
| weight | Float | Physical weight for shipping calculations.
|
| variants | [ProductVariantType] | Available variations (size, color, etc.).
|
| contents | [ProductContentType] | Localized names and descriptions.
|
Cart (cart)
Represents a user's active shopping session.
| Field | Type | Description |
|---|---|---|
cart_id |
Id |
Unique identifier for the cart. |
|
| products | [CartProductType] | List of items currently in the cart.
|
| totals | [TotalType] | Breakdown of subtotal, tax, and shipping.
|
| total_price | Float | The grand total amount.
|
| total_formatted | String | Currency-formatted total string.
|
| checkout_url | String | Direct link to the checkout page.
|
Content & Blogging
Post (post)
Used for blog articles, news, or generic CMS pages.
| Field | Type | Description |
|---|---|---|
post_id |
ID |
Unique identifier for the post. |
|
| status | String | The post status (e.g., "published", "draft").
|
| comment_count | Int | Total number of approved comments.
|
| created_at | String | Timestamp of post creation.
|
| contents | [PostContentType] | Multi-language content (title, body, slug).
|
| seo | [SeoType] | Metadata for search engine optimization.
|
Media (media)
Represents uploaded assets like images and videos.
| Field | Type | Description |
|---|---|---|
media_id |
ID |
Unique identifier. |
|
| file | String | The file path or URL.
|
| type | String | MIME type or category (image, video, etc.).
|
Orders & Customers
Order (order)
A finalized transaction containing snapshot data of the purchase.
-
Identifiers: Includes
order_id,invoice_no, andcustomer_order_id. -
Customer Info: Stores
first_name,last_name,email, andphone_number. -
Shipping/Billing: Comprehensive address fields including
address_1,city,post_code, andcountry_id. -
Financials: Tracks
payment_method,shipping_method,total, andcurrency_id. -
Associations: Links to
products,shipments,subscriptions, andvouchers.
️ System & Configuration
-
Localization: Supported via
language(codes, locales, RTL support) andcurrency(symbols, decimal places, exchange values). -
Geography:
countrydata including ISO codes and status. -
Administration:
admintype manages backend users, includingrole_id,auth_tokens, andfailed_logins. -
Marketing:
couponmanagement (discount types, usage limits, date ranges) andnewsletter_listmanagement. -
Customization:
fieldandfield_groupallow for extensible data models across posts and products.
Pro Tip: Localized Content
Most primary entities (Product, Post, Category) do not store names directly. Instead, they use a contents array (e.g., ProductContentType) which maps content to a specific language_id. Always query the contents field to retrieve the correct translation for your frontend.
]]>
Payment methods (Vvveb\System\PaymentMethod)
system/payment-method.php is the contract every gateway plugin implements
(plugins/*/payment.php). Only three methods are abstract:
getMethod(&$checkoutInfo, $options)- availability + display data, orfalseinit()/setMethod()- cart total/tax bookkeeping
Everything else has a return false default stub, so simple offline methods
(bank transfer, COD) stay tiny and nothing fatals on a missing operation.
Operation results
Transaction methods return bool, except authorize()/purchase() which may
also return a redirect result:
return $this->redirect($url); // ['status' => 'redirect', 'redirect' => $url]
true- success, core continues (mail, cart empty, confirmation).false- failure. Set the reason first with$this->fail('...'); checkout stays on the page with the message and keeps the cart.- redirect array - off-site gateway (PayPal, Mollie, 3DS). Never redirect or
exitinside the method - core persists payment data and redirects, so order creation, events and mail stay in one place.
Inspect details via Payment::getError() / Payment::getRedirectUrl().
Capabilities
$method->supports('refund') reports whether the concrete class overrides an
operation - no per-method declarations needed. Admin buttons (capture, refund,
void) and Payment::createCard()/webhook() dispatch honor it.
Shared helpers (protected)
toCents($total),idempotencyKey($checkoutInfo)- pass the key as the gateway transaction reference so retried submits don't double-charge.storedPaymentData()/storePaymentData($info, $data, $statusId = null)- array-or-JSON tolerant, persists to the order whenorder_idis present.verifyHmac($payload, $signature, $secret)- webhook signature checks.
Webhooks
Each plugin keeps its own route but implements the shared shape:
verify signature → apply update idempotently → plain OK/JSON ack so the
gateway stops retrying. Failures must never break the HTTP 200 response.
Shipments and multi-package quotes
ship() records one order_shipment row per package (idempotent per
method+tracking) instead of returning a blind true; checkout aborts with
the method error when it fails, before any charge. The admin order page
renders the rows; carrier booking fills tracking numbers later.
Carriers split cart lines into shipping groups by shipping class (one
default group preserves single-package behavior), quote each package
through the cached rate layer, and sum the totals - a group that fails
falls the whole method back to its flat rate so pricing stays coherent.
AbstractCarrier::groupItems() is the pure, unit-tested seam; flat,
weight and pickup methods stay single-package. Every package carries an
explicit origin resolved per group (explicit origins map, then the
AbstractCarrier::origin event, then the fulfilment warehouse, then the
site address). Warehouses (order/warehouses admin) hold name + address
and product assignments; cart lines are tagged with their warehouse
(tagWarehouses(), default = first active) and grouped per warehouse, so
multi-origin quoting and shipment origins work out of the box.
The method contract mirrors payments (supports('ship'), getError()),
and the dispatcher gained getMethodInstance() plus an optional cart.
Live carriers (UPS OAuth2, FedEx OAuth2, DHL key, USPS key) implement
rating/tracking/address/pickup behind per-carrier settings with flat-rate
fallback; each honors a test_mode sandbox endpoint. Rate parsers are
fixture-tested with stubbed HTTP (CarrierRateTest), so only live
credentials stand between here and verified live quotes.
Partial capture and refund
capture()/refund() honor an amount checkout key (partial
capture/refund); absent means full. The admin order page exposes amount
inputs prefilled with the ledger-derived remaining total and rejects
over-amounts server-side. Stripe and Omnipay thread the override;
Payum capture and subscription-invoice refunds are full-only and fail
closed when a partial is requested. Every partial writes its own ledger
row, so the Transactions timeline is the audit trail.
Subscriptions
Core subscription rows are gateway-agnostic. Unlike one-shot Omnipay
drivers, Payum supports recurring billing natively: PayPal Express
recurring profiles (CreateRecurringPaymentProfile,
ManageRecurringPaymentsProfileStatus, UpdateRecurringPaymentProfile) and
Stripe subscriptions (CreateSubscription, plus SDK cancel/pause/resume/swap).
The payum plugin implements the full subscription contract for both
(SUPPORTS_SUBSCRIPTIONS), including a billing-agreement checkout branch
and a payum-recurring return action that claims the pending core row. Rows provisioned at a gateway
store a gateway:id pair in payment_method (e.g. stripe:sub_1).
Lifecycle operations
cancelSubscription, pauseSubscription, resumeSubscription,
swapSubscription (plus createSubscription) default to false on the base;
Stripe implements cancel/pause/resume/swap. Context carries
gateway_subscription_id (see gatewaySubscriptionId()).
Vvveb\System\SubscriptionManager::gatewayOperation($op, $row, $order) runs
the gateway call first and returns an error string on failure - callers
(admin order/subscription, customer user/subscription) only change local
status when it returns null. Rows without a gateway reference keep the legacy
local-only behavior. Lifecycle actions require POST (+CSRF customer-side).
The customer portal self-serves pause/resume/cancel plus plan swap (price
ensured from the plan mapping, no new trial) and skip-a-payment (next date
pushed one interval at the gateway and locally via
SubscriptionManager::addInterval()).
Checkout provisioning
Checkout creates pending core rows for every subscription line, for any
method. Stripe claims them (via local_subscription_id metadata) instead of
inserting duplicates; manual methods stay pending until confirmed.
Elements return flow
The Elements form leaves the store before any order exists, so
plugins/stripe/index/client snapshots the checkout form, and
/stripe-return verifies the Setup/PaymentIntent server-side, creates the
order, links subscription rows race-safely both ways, and confirms. The
displayed amount composes trial prices, recurring amounts and one-time
lines. Guest checkouts that opt into registration get an account with a
random password plus a reset link; account problems never fail the paid
order. Snapshots are consumed, so replays land closed. Both the Elements return
and renewal orders fire the checkout add:after event, so inventory
deduction, gift-card debit, accounting, tax, fraud and marketing listeners
run uniformly on every order path (admin manual orders stay out - they
start lineless and merchant-managed). Core warehouses are fulfilment
origins for shipping; the inventory plugin's locations remain the stock
ledger - separate systems, bridged by the shared order event.
Order statuses
Default / Pending / Success / Error payment statuses mirror the Omnipay plugin (defaults awaiting 2, paid 4, canceled 5). Success drives order creation, captures and renewals; errors are now recorded on failed capture/refund/void where previously nothing was written. Note: capture success previously wrote status 2 and now writes the success status.
Link autofill
Link by Stripe (one-click autofill in the payment form) is on by default
and can be switched off with the plugin's Link setting, which passes
wallets: {link: 'never'} to Elements. Stripe still requires Link to be
turned off in the dashboard (Settings > Payments) for full account-wide
removal.
Express wallets
One-time checkouts offer Apple Pay / Google Pay through Stripe's Payment
Request Button (hidden for subscription carts and when the wallet is
unavailable). The wallet sheet collects contact and shipping details, the
existing /stripe-client endpoint mints the PaymentIntent plus snapshot,
and the same return URL verifies and orders. The sheet total is the cart
total at button time; wallet-address shipping differences are recorded on
the order rather than re-charged.
Renewals and dunning
Stripe's invoice.payment_succeeded webhook creates an idempotent renewal
order (per-invoice log marker, totals from the invoice, lines cloned from the
original order). invoice.payment_failed climbs a 4-attempt dunning ladder (day 0/1/3/7)
shared between webhook and the daily subscription-dunning cron pass via
structured log notes - retries pay open invoices (already-paid ones report
success without double-charging), recoveries flip back to active, and
exhausted ladders cancel at the gateway. Manual-method rows stay out of
automatic dunning. Mixed carts bill one-time lines onto the first subscription invoice
(syncOneTimeInvoiceItems(), reconciled per order/cart reference so retries
can't double-bill).
Stripe Elements return flow
The Elements form leaves the store before any order exists, so
plugins/stripe/index/client snapshots the checkout form into
stripe_pending, and /stripe-return verifies the Setup/PaymentIntent
server-side, creates the order, links subscription rows (race-safe both ways
via linkSubscriptionOrder() + metadata stamping) and confirms. The snapshot
is consumed - replays land closed on the failed page.
Deliberate non-goals
- Plan-definition edits propagate intervals on explicit save (new price + swap of active gateway subs), but nothing auto-fires - gateway prices are immutable, so this stays an intentional admin action.
expire()stops billing at term end for provisioned rows, locally expiring immediately; the gateway webhook flips the row to cancelled at term end.- Guest Elements one-time orders skip account auto-registration (no credential survives the off-site round-trip).
data-v-component-* attributes. The template declares what data it needs, and the component system automatically discovers, executes, and caches the results.
How Components Work
- Discovery: During template compilation, the system parses the HTML for
data-v-component-*attributes - Execution: Each component class is instantiated with its options, and
results()is called - Caching: Results are cached per component + options hash
- Injection: Results are stored in
$view->_component[name][index]and available in the template
Creating a Component
Define the Component Class
// app/component/products.php
namespace Vvveb\Component;
use Vvveb\System\Component\ComponentBase;
use Vvveb\System\Event;
use Vvveb\System\Images;
use Vvveb\Sql\ProductSQL;
class Products extends ComponentBase {
public int $cacheExpire = 3600; // Cache for 1 hour, 0 = no cache
public static array $defaultOptions = [
'limit' => 4,
'page' => 1,
'type' => 'product',
'status' => 1,
'manufacturer_id' => null,
'taxonomy_item_id' => null,
'order_by' => null,
'direction' => null,
];
public function results(): array {
$products = new ProductSQL();
$results = $products->getAll($this->options);
// Format prices and images (see app/component/product.php for a full example)
$currency = \Vvveb\System\Cart\Currency::getInstance($this->options);
foreach ($results['product'] as &$product) {
$product['price'] = $currency->format($product['price']);
$product['image'] = Images::image($product['image'], 'product');
$product['url'] = \Vvveb\url('product/product/index', ['product_id' => $product['product_id'], 'slug' => $product['slug']]);
}
// Allow plugins to modify results
list($results) = Event::trigger(__CLASS__, __FUNCTION__, $results);
return $results;
}
public function request(array &$results, int $index = 0): array {
// Called per-request (after cache). Use for dynamic per-request tweaks.
// Mark active category, strip password-protected content, etc.
return $results;
}
}
Declare in Template
<!-- Simple usage with defaults -->
<div data-v-component-products></div>
<!-- With options (only names listed in the class's $defaultOptions are accepted) -->
<div data-v-component-products
data-v-limit="8"
data-v-taxonomy_item_id="5"
data-v-order_by="price"
data-v-direction="asc">
</div>
<!-- Dynamic options from URL -->
<div data-v-component-products
data-v-manufacturer_id="url">
</div>
<!-- Dynamic with fallback (falls back to 12 when the URL has no limit) -->
<div data-v-component-products
data-v-taxonomy_item_id="url"
data-v-limit='["url", 12]'>
</div>
Use in Template
<div data-v-component-products data-v-limit="8">
<div data-v-product>
<h3 data-v-product-name>Product name</h3>
<span data-v-product-price_formatted>$100</span>
<a href="" data-v-product-url>View</a>
</div>
</div>
Each data-v-product block repeats per product; the rules in app/template/components/products.tpl bind every data-v-product-* attribute to the matching result field.
Component Options
Default Options
Define $defaultOptions in your component class. These are merged with any data-v-* attributes from the template:
public static array $defaultOptions = [
'limit' => 12,
'status' => 1,
'order_by' => null,
'direction' => null,
'type' => null,
];
Only attributes whose names appear in $defaultOptions are accepted - unknown data-v-* attributes are ignored (Component::parseComponentElement()). Global context (site_id, language_id, currency, user_id, …) is merged into the defaults automatically, and empty site_id/language_id/currency_id/user_id/user_group_id fall back to the current request values.
Option Types
| Template Attribute | Value Type | Example |
|---|---|---|
data-v-limit="8" |
Integer | data-v-limit="8" |
data-v-status="1" |
Mixed | data-v-status="1" |
data-v-type="post" |
String | data-v-type="post" |
data-v-manufacturer_id="url" |
From URL | Reads $_GET/$_REQUEST['manufacturer_id'] (supports url.field dotted form) |
data-v-limit='["url", 5]' |
With fallback | [url, 5] - URL param or default 5 (PHP-side form is 'limit' => ['url', 5]) |
data-v-options='{"key":"val"}' |
JSON | Decoded to array |
URL Parameter Binding
When an option value is 'url', it's automatically resolved from the current request:
// Template: data-v-category_id="url"
// URL: /category/electronics?category_id=5
// Resolved: $this->options['category_id'] = 5
// With fallback: data-v-category_id='["url", 1]'
// If not in URL: $this->options['category_id'] = 1
Caching
Components support automatic caching via the Cache system:
class Products extends ComponentBase {
public int $cacheExpire = 3600; // 1 hour (0 = no cache)
public function cacheKey(): ?string {
return null; // Disable caching entirely
// Or return a custom key
}
}
Cache Behavior
- Cache hit: Returns cached results directly
- Cache expired: If within the stale window, serves stale data while regenerating in background
- Concurrent requests: Uses lock files with retry/wait to prevent thundering herd
- Cache key: Generated from class name + serialized options hash
When to Disable Caching
public int $cacheExpire = 0; // No caching
// Or
public function cacheKey(): ?string {
return null; // Disable caching
}
Use cacheExpire = 0 when:
- Component shows user-specific data (e.g., cart, wishlist)
- Component shows real-time data (e.g., stock levels)
- Component data changes frequently and must be fresh
Component Lifecycle
1. ComponentBase::__construct($options)
├── Merge $options with $defaultOptions
├── Resolve URL-bound options
├── Fire Event::trigger(__CLASS__, '__construct', $this->options)
└── $this->di($this) - inject request, view, session
2. Component::loadComponents() (called by View::render)
├── Check cache (Cache::getMulti)
├── If cache hit → use cached results
├── If cache miss → call $obj->results()
│ ├── Execute SQL model query
│ ├── Format data (images, prices, URLs)
│ └── Fire Event::trigger(__CLASS__, 'results', $results)
├── Store in $view->_component[name][index]
└── Call $obj->request() on each component
3. Template rendering
└── Access via $view->_component[name][index]
Available Components
See the code-reference for the full documented list (45 components: shop, products, content, users, navigation). Common front-end examples (app/component/): posts, products, product, categories, category, cart, checkout/payment, checkout/shipping, product/options, product/variants, content/tags, user/wishlist, menu, currency, breadcrumb, fields. Admin components (admin/component/) include posts, products, users, orders, comments, languages, sites, stats, notifications, among others - they serve the admin templates rather than themes.
Plugin Components
Plugins can register components with the prefix data-v-component-plugin-{plugin-name}-{namespace}:
<div data-v-component-plugin-contact-form-contact-form></div>
The Component Engine
The Component class (system/component/component.php) is the singleton orchestrator:
// Manually trigger component loading (rarely needed)
$component = \Vvveb\System\Component\Component::getInstance($view);
Component Discovery
generateRequiredComponents() parses the HTML template DOM:
- Processes
data-v-copy-fromattributes (template inheritance) - Queries XPath for all
data-v-component-*attributes - Extracts component name and options from
data-v-*attributes - Validates options against
$defaultOptions - Caches definitions to
.componentfiles
Component Results Storage
Results are stored in the View object:
// In template:
$products = $view->_component['products'][0];
$posts = $view->_component['posts'][0];
$categories = $view->_component['categories'][0];
Each component instance gets its own index, allowing multiple instances of the same component on one page.
Events
Components fire events that plugins can hook into:
// After results are fetched
\Vvveb\System\Event::on('Vvveb\Component\Products', 'results', 'my-plugin', function($results) {
// Modify products before they reach the template
$results['product'] = array_filter($results['product'], fn($p) => $p['featured']);
return [$results]; // listeners must return their parameters wrapped in an array
}, 1000);
// After component is constructed
\Vvveb\System\Event::on('Vvveb\Component\Products', '__construct', 'my-plugin', function($options) {
// Modify options before query execution
$options['limit'] = min($options['limit'], 20);
return [$options];
}, 1000);
Component object is used to define the html blocks that can be added and edited on the page.
To add a component you need to use Vvveb.Components.add method or extend an existing component, like a base component with Vvveb.Components.extend
For example image component extends _base component and is defined as
Vvveb.Components.extend("_base", "html/image", {
nodes: ["img"],
name: "Image",
html: '<img src="../libs/builder/icons/image.svg" height="128" width="128">',
image: "icons/image.svg",
properties: [{
name: "Image",
key: "src",
htmlAttr: "src",
inputtype: FileUploadInput
}, {
name: "Width",
key: "width",
htmlAttr: "width",
inputtype: TextInput
}, {
name: "Height",
key: "height",
htmlAttr: "height",
inputtype: TextInput
}, {
name: "Alt",
key: "alt",
htmlAttr: "alt",
inputtype: TextInput
}]
});
Base component does not extend any existing component and is using Vvveb.Components.add being defined as
Vvveb.Components.add("_base", {
name: "Element",
properties: [{
name: "Id",
key: "id",
htmlAttr: "id",
inputtype: TextInput
}, {
name: "Class",
key: "class",
htmlAttr: "class",
inputtype: TextInput
}]
});
In this way any component that extends _base component inherits two properties id and class used to edit the corresponding html attributes.
Note: _base component is loaded for any html node that has no specific component assigned, for example when clicking on a regular span node.
Component definition
Component object can have the following keys
- name - Used to display the name on the components list in the left panel.
- image - Image url to display in the components list.
- html - When dropping the component on the page this html is used to insert it in the page.
- nodes - An array with dom node names to allow the editor to detect the Component when clicking on the corresponding node, example
nodes: ["h1", "h2","h3", "h4","h5","h6"],ornodes: ["img"], - classes - An array with class names to allow the editor to detect the Component when clicking on the corresponding node, example
classes: ["btn", "btn-link"] - classesRegex - An array with regexs used for class names to allow the editor to detect the Component when clicking on the corresponding node, example
classesRegex: ["col-"],this regex is used by Grid Component to detect bootstrap columns such as col-md-3 or col-sm-6. - attributes - An array with attributes names to allow the editor to detect the Component when clicking on the corresponding node, example
attributes: ["data-component-maps"],this attribute is used by maps component. - afterDrop - function (node) {} A function that is called after the element is droped, the node of the new element is passed as parameter, for example map component uses this function to change the html of the node fom a image of a map with the actual map iframe for performance reasons when dragging.
- init - function (node) {} A function that is called after the Component properties are loaded and displayed in the right panel , the node of the new element is passed as parameter, for example video component that supports youtube, vimeo and html5 uses this event to hide vimeo and html5 inputs when a youtube video is detected.
- beforeInit - function (node) {} A function that is called before Component properties are displayed , the node of the new element is passed as parameter, this can be useful to dinamically change component properties for example Select Input or Grid component that needs to load a variable number of inputs based on child nodes uses this event to alter component properties and add the necessary properties for each child node.
- onChange - function (node, property, value) This event is called when a component input in the right panel is changed, the first parameter is the dom node that is edited, second parameter property is the name of the property that has changed (the key attribute of the property), value is the new value of the property. Usually each input has it's own onChange event but because the component onChange event is triggered for all inputs can be usefull when using a common function to process all input changes. This event is usefull when changing complex features, for example the map component uses it to compose a new google maps url by adding all component properties such as latitude, longitude and zoom etc.
- properties - A collection of inputs and corespponding configuration for each, to allow the Component to be edited.
A complete Component definition with all possible keys
Vvveb.Components.extend("_base", "html/image", {
name: "Image",
image: "icons/image.svg",
html: '<img src="../libs/builder/icons/image.svg" height="128" width="128">',
nodes: ["img"],
classes: ["btn", "btn-link"],
attributes: ["data-component-maps"],
afterDrop: function (node) {},
init: function (node) {},
beforeInit: function (node) {},
onChange: function (node, property, value) {},
properties: [{
name: "Id",
key: "id",
htmlAttr: "id",
inputtype: TextInput
}
});
Component properties
Component properties are used to define the inputs that are used to edit the component.
properties: [{
name: "Id",
key: "id",
htmlAttr: "id",
inputtype: TextInput
}, {
name: "Class",
key: "class",
htmlAttr: "class",
inputtype: TextInput
}]
A property can have the following keys
- name - Used as label for the input.
- key - Unique identifier for the input, this is pased on component onChange event second parameter property.
- inputtype - The input type used for the property, any Input object such as TextInput, SelectInput, ToggleInput, ColorInput etc from inputs.js can be used.
- htmlAttr - If htmlAttr is specified then the value is used to edit the coresponding html attribute, the input is filled automatically with the initial value of the attribute and updated automatically when the input is changed, no need to use onChange event, for example htmlAttr: "id",
- style - If htmlAttr is set to style then the property key is used as the css property to be edited, in the example below background-color css property is edited directly using ColorInput that will display a color picker.
- class - If htmlAttr is set to class and the property has validValues key then all classed that are contained in validValues array are removed before adding the new value, this can be usefull when having a select input to choose a unique class from a set. For example in the example below bootstrap container component uses validValues to allow either container or container-fluid class to be added from a select.
properties: [
{
name: "Background Color",
key: "background-color",
htmlAttr: "style",
inputtype: ColorInput,
},
{
name: "Type",
key: "type",
htmlAttr: "class",
inputtype: SelectInput,
validValues: ["container", "container-fluid"],
data: {
options: [{
value: "container",
text: "Default"
}, {
value: "container-fluid",
text: "Fluid"
}]
} name: "Class",
key: "class",
htmlAttr: "class",
inputtype: TextInput
}]
- onChange - function(node, value) This event is triggered when the input is changed (this can depend on Input definition, check inputs.js) you can use this when htmlAttr or style is not enough.
- init - function(node) This function is called when the input is initialized, this can be used for example to load the input with a different value than default. For example when editing width css property and using a NumberInput you need to use init to remove the px from "100px" to set the value for NumberInput correctly.
{
name: "Width",
key: "width",
htmlAttr: "style",
parent:"",
inputtype: NumberInput,//can also be replaced with RangeInput
data: {
value: "320",//default
min: "50",
max: "1024",
step: "10"
},
init: function (node)//use init because number input does not ignore "px"
{
return parseInt($(node).css("width"));//remove px
}
}
- data - Some Inputs need aditional data, for example ToggleInput needs values for on and off states, or SelectInput needs data:{options: [{}]} for values For example using toggle to set disabled to true or false for a bootstrap button
//ToggleInput
{
name: "Disabled",
key: "disabled",
htmlAttr: "disabled",
inputtype: ToggleInput,
data: {
on: "disabled-true",
off: "disabled-false"
}
}
//SelectInput
{
name: "Size",
key: "size",
htmlAttr: "class",
inputtype: SelectInput,
validValues: ["btn-lg", "btn-sm"],
data: {
options: [{
value: "",
text: "Default"
}, {
value: "btn-lg",
text: "Large"
}, {
value: "btn-sm",
text: "Small"
}]
}
}
- child - Sometimes you need to edit a node that is inside the parent node, for this you can use child property the value must be the css selector for the child element. For example bootstrap progress bar component has two divs, one for background and one for the progress to use a input to change the progress div instead of the background div, child is set as child:".progress-bar".
{
name: "Animated",
key: "animated",
child:".progress-bar",
htmlAttr: "class",
validValues: ["", "progress-bar-animated"],
inputtype: ToggleInput,
data: {
on: "progress-bar-animated",
off: "",
}
}
- parent - Same as child but used to edit parent elements, when only parent is set with no selector then the parentNode is used, if a css selector is used then the selector is used to find parent node (this uses jQuery.parents())
Component group
For a component to be visible in the left panel and to be used for drag and drop it needs to be added to a component group, you can do this by including it in the Vvveb.ComponentsGroup array using the group name as a key.
For example Widgets component group has the following definition.
Vvveb.ComponentsGroup['Widgets'] = ["widgets/googlemaps", "widgets/video"];
Inputs objects are used to edit component properties
For example TextInput extends Input object and is defined as
var TextInput = $.extend({}, Input, {
events: {
"keyup": ['onChange', 'input'],
},
setValue: function(value) {
$('input', this.element).val(value);
},
init: function(data) {
return this.render("textinput", data);
},
}
);
Inputs also require a template that is defined as a