Virtuemart

VirtueMart Plugin Development

Overview

VirtueMart is an open-source e-commerce component for Joomla, the PHP content management system. VirtueMart runs as a Joomla component (com_virtuemart) and extends through the Joomla plugin system, inheriting Joomla's MVC architecture, database abstraction, user management, and access control. All VirtueMart extensions are Joomla plugins or modules that interact with VirtueMart's API, models, and event trigger points.

VirtueMart 3.x and 4.x support PHP 7.4+ (PHP 8.1 recommended for VM4), MySQL 5.7+ or MariaDB 10.2+, and require Joomla 3.x (VM3) or Joomla 4.x/5.x (VM4). The template engine is Joomla's built-in PHP template system with VirtueMart-specific view overrides. VirtueMart maintains its own database tables (prefixed #__virtuemart_) alongside Joomla's core tables, and provides its own model layer, table classes, and configuration system.

Understanding both the Joomla plugin architecture and VirtueMart's internal API is essential for extension development. VirtueMart plugins are Joomla plugins that implement VirtueMart-specific trigger methods and extend VirtueMart base classes.

For Joomla component architecture, view overrides, and Joomla-VirtueMart integration patterns, see references/joomla-integration.md.

Extension Types

VirtueMart defines four primary plugin types, each serving a specific functional domain. All are implemented as Joomla plugins in the corresponding plugin group.

Payment Plugins (vmpayment)

Payment plugins integrate payment gateways into the VirtueMart checkout flow. Each plugin extends the vmPSPlugin base class (Payment/Shipment Plugin) and implements trigger methods for order confirmation, payment response handling, and notification callbacks. Payment plugins handle redirect-based flows (PayPal, Stripe Checkout), server-to-server API calls, and IPN/webhook notifications.

Payment plugins reside in Joomla's plugin directory under the vmpayment group: plugins/vmpayment/my_payment/. Each plugin includes a PHP class file, an XML manifest, language files, and optionally SQL installation scripts and template overrides.

Shipment Plugins (vmshipment)

Shipment plugins calculate shipping rates and manage shipping method availability based on destination, weight, cart contents, and custom rules. They extend vmPSPlugin and implement shipment-specific trigger methods. Shipment plugins appear in VirtueMart's shipping method configuration and are selected by customers during checkout.

Custom Field Plugins (vmcustom)

Custom field plugins extend product data with additional fields, options, and behaviors. They allow store owners to add configurable product attributes (color selectors, text inputs, file uploads, related products, specifications) without modifying core templates. Custom fields attach to products through the admin product editor and render in the storefront product detail view.

Shopper Plugins (vmshopper)

Shopper plugins extend user/customer data and behavior. They add custom fields to the shopper registration and profile forms, implement custom validation, and integrate with external CRM or membership systems. Shopper plugins trigger during account creation, profile updates, and checkout address handling.

For detailed plugin type implementations, trigger events, and configuration patterns, see references/plugin-architecture.md.

Joomla Plugin System

VirtueMart plugins are standard Joomla plugins with VirtueMart-specific plugin groups and trigger events. Understanding the Joomla plugin lifecycle is fundamental.

Plugin Groups

Joomla organizes plugins into groups. VirtueMart defines its own groups:

• vmpayment -- Payment gateway plugins.
• vmshipment -- Shipping method plugins.
• vmcustom -- Custom product field plugins.
• vmshopper -- Shopper/user field plugins.
• vmcalculation -- Tax and calculation rule plugins.
• vmcoupon -- Coupon and discount plugins.

XML Manifest

Every Joomla plugin requires an XML manifest file that declares metadata, file lists, configuration parameters, language files, and installation scripts. The manifest controls what appears in the Joomla Plugin Manager and VirtueMart's plugin configuration. The manifest uses the <extension> root element with type="plugin" and the group attribute set to the VirtueMart plugin group (e.g., group="vmpayment"). Configuration parameters defined in the manifest's <config> section appear in the Joomla Plugin Manager and in VirtueMart's per-method configuration UI.

For the complete manifest format and custom field types, see references/plugin-architecture.md.

Trigger Events

VirtueMart fires trigger events at key points in the e-commerce lifecycle. Plugin methods named after these triggers execute automatically when the corresponding event occurs. The Joomla event dispatcher calls all enabled plugins in the relevant group.

For a comprehensive list of payment plugin trigger events and their lifecycle, see references/payment-plugins.md.

Plugin Structure

Plugin Class

Every VirtueMart plugin class extends vmPSPlugin (for payment and shipment) or the appropriate VirtueMart base class. The base class provides helper methods for configuration access, table operations, logging, and response handling. The constructor must call parent::__construct($subject, $config), configure logging, define table fields via getTableSQLFields(), and set configurable parameters via setConfigParameterable(). Each plugin also implements getVmPluginCreateTableSQL() to define its per-method transaction storage table.

For complete plugin class implementation with code examples, see references/plugin-architecture.md.

Language Files

Provide language files in Joomla's INI format for both the plugin interface (.ini) and system display (.sys.ini). Language keys follow the pattern PLG_<GROUP>_<PLUGIN_NAME>_<KEY>. Place language files in language/en-GB/ under the plugin directory.

Configuration Parameters

Plugin configuration parameters defined in the XML manifest are stored in Joomla's #__extensions table and accessible through $this->params or VirtueMart's payment method settings. VirtueMart extends Joomla's parameter handling with per-payment-method configuration -- each payment method instance can have different settings (e.g., different API keys for different storefronts).

Development Setup

Local Installation

1. Install PHP 7.4+ (PHP 8.1 recommended) with extensions: mysqli, curl, gd, json, mbstring, xml.
2. Install MySQL 5.7+ or MariaDB 10.2+.
3. Install Apache with mod_rewrite or Nginx.
4. Download and install Joomla 4.x or 5.x from the official site.
5. Install VirtueMart as a Joomla component through Extensions > Install or from the VirtueMart download package.
6. Configure VirtueMart's store settings, currencies, and shopper groups through the VirtueMart admin panel.

Plugin Development Workflow

• Create the plugin directory structure under plugins/vmpayment/ (or the appropriate plugin group directory).
• Write the XML manifest, PHP class file, and language files.
• Install the plugin through Joomla's Extension Manager (Extensions > Manage > Install) or by uploading a ZIP archive.
• Enable the plugin in Joomla's Plugin Manager (Extensions > Plugins).
• Configure the payment/shipment method in VirtueMart admin (VirtueMart > Payment Methods or Shipment Methods).
• Enable Joomla debug mode (Global Configuration > System > Debug System) and VirtueMart's logging for development diagnostics.
• Test the full checkout flow in the storefront to verify trigger events fire correctly.

Key VirtueMart Tables and Models

VirtueMart maintains its own database tables alongside Joomla's core tables. All VirtueMart tables use the #__virtuemart_ prefix (where #__ is Joomla's configured table prefix).

Core Tables

• #__virtuemart_products -- Product master data (SKU, prices, dimensions, stock).
• #__virtuemart_orders -- Order headers (customer, status, totals, currency).
• #__virtuemart_order_items -- Order line items (product, quantity, price).
• #__virtuemart_order_histories -- Order status change history.
• #__virtuemart_paymentmethods -- Configured payment methods and their settings.
• #__virtuemart_shipmentmethods -- Configured shipment methods.
• #__virtuemart_vmusers -- VirtueMart-specific user/shopper data extending Joomla users.
• #__virtuemart_categories -- Product categories.
• #__virtuemart_customs -- Custom field definitions.
• #__virtuemart_product_customfields -- Custom field values assigned to products.

VirtueMart Models

VirtueMart uses its own model layer (VmModel) for data access. Load models via VmModel::getModel('orders'), VmModel::getModel('product'), etc. Models handle data retrieval, filtering, pagination, and business logic. Always use VirtueMart models instead of direct database queries to ensure proper access control, multi-vendor scoping, and data consistency.

For database access patterns and Joomla's JDatabase query builder, see references/joomla-integration.md.

Anti-Patterns

• Direct database queries bypassing VmModel. Use VmModel::getModel() for data access. Direct queries skip access control, data transformations, and multi-vendor scoping.
• Ignoring Joomla's plugin lifecycle. Always call parent::__construct($subject, $config) in the constructor. Skipping parent initialization breaks event dispatching and parameter loading.
• Hardcoding table names. Use #__virtuemart_ with Joomla's table prefix system. Never hardcode jos_virtuemart_ or assume a specific prefix.
• Storing configuration outside Joomla's parameter system. Use the XML manifest <config> section and $this->params. File-based or custom-table configuration breaks Joomla's Plugin Manager interface and multi-site installations.
• Skipping payment verification callbacks. Always implement plgVmOnPaymentNotification() for server-to-server payment confirmation. Relying solely on client-side redirects allows order manipulation.
• Ignoring multi-vendor context. VirtueMart supports multi-vendor stores. Scope queries and data access to the appropriate vendor ID when applicable.

Reference Files

• Plugin Architecture -- VirtueMart plugin types (vmpayment, vmshipment, vmcustom, vmshopper), plugin directory structure, XML manifest, trigger events, configuration parameters, table creation
• Joomla Integration -- Joomla component/plugin architecture, VirtueMart view/template overrides, Joomla modules for VirtueMart data, ACL integration, JTable/JDatabase access
• Payment Plugins -- Payment plugin lifecycle, plgVmConfirmedOrder(), plgVmOnPaymentResponseReceived(), plgVmOnPaymentNotification(), order status updates, refund handling, redirect flows