Last indexed: 13 December 2025 (dd8fb9)

Plugin and Extension System

Purpose and Scope

This document explains the plugin and extension architecture that enables third-party modules to extend GP247/Shop functionality without modifying core code. The system supports three primary plugin types: shipping methods, payment gateways, and order total calculations (tax, discounts, fees). Social login plugins are also supported but follow a different integration pattern.

This page covers plugin discovery, lifecycle management, convention-based interfaces, and integration points within the checkout flow. For order processing logic after plugin execution, see Order Processing and Email Notifications. For configuration system that controls plugin enablement, see Configuration-Driven System Behavior.

Plugin Types and Database Storage

The system recognizes four extension categories, each stored in the admin_config table with specific type/code combinations:

Plugin Type	Database Code	Purpose	Primary Method
Shipping	`code='shipping'`	Calculate and display shipping options	`getInfo()`
Payment	`code='payment'`	Process payment transactions	`processOrder()`
Total	`code='total'`	Calculate order totals (tax, discount, fees)	`processDataTotal()`
Social Login	Plugin-specific	OAuth authentication integration	Various

Plugins are enabled/disabled by configuration entries. Each enabled plugin has a corresponding configuration key (e.g., $PaymentMethod_cash) that must be set to active status.

Sources: src/Controllers/ShopCartController.php177-213

Plugin Discovery System

The system discovers and loads plugins dynamically at runtime using a two-step resolution process:

Discovery Flow:

Database Query: gp247_extension_get_via_code(code: 'shipping') retrieves enabled plugins for a specific type src/Controllers/ShopCartController.php177
Local Sources: gp247_extension_get_all_local(type: 'Plugins') returns filesystem paths for installed plugins src/Controllers/ShopCartController.php178
Namespace Resolution: gp247_extension_get_namespace(type: 'Plugins', key: $module['key']) constructs the fully-qualified class name src/Controllers/ShopCartController.php182
Convention Check: System appends \AppConfig to namespace and verifies class exists src/Controllers/ShopCartController.php183
Method Verification: Uses method_exists() to confirm required methods are present src/Controllers/ShopCartController.php186

Sources: src/Controllers/ShopCartController.php176-213

Plugin Lifecycle

Plugins progress through four distinct lifecycle stages during checkout:

Stage 1: Discovery

Occurs in _getCheckout() method when checkout page loads. System queries database for enabled plugins of each type.

Sources: src/Controllers/ShopCartController.php176-213

Stage 2: Loading

For each discovered plugin:

Namespace constructed: App\Plugins\{$key}\AppConfig
Class instantiated: new $moduleClass()
Defensive checks prevent fatal errors if plugin malformed

Sources: src/Controllers/ShopCartController.php182-190

Stage 3: Display

getInfo() method called to retrieve display information for checkout view:

Plugin title and description
Configuration options
Pricing information

Sources: src/Controllers/ShopCartController.php186-188 src/Controllers/ShopCartController.php200 src/Controllers/ShopCartController.php211

Stage 4: Execution

When order is submitted in addOrder() method:

Payment plugin's processOrder() method invoked
Handles payment processing, API calls, redirects
Returns response or delegates to completeOrder()

Sources: src/Controllers/ShopCartController.php669-676

Stage 5: Callback (Optional)

Payment plugins may implement endApp() callback for post-order tasks:

Webhook registration
External API notifications
Transaction logging

Sources: Mentioned in high-level architecture Diagram 5

Convention-Based Architecture

Plugins follow strict naming conventions. The system does not use interfaces or abstract classes; instead relies on convention and defensive checks:

Required Structure

App/Plugins/{PluginKey}/
├── AppConfig.php # Required: Main configuration class
├── Controllers/
│ └── FrontController.php # Optional: For payment processing
└── {AdditionalFiles} # Optional: Views, helpers, etc.

AppConfig Class Requirements

All plugins must provide an AppConfig class with:

Minimum Required:

Namespace: App\Plugins\{PluginKey}
Class name: AppConfig
Method: getInfo() returning array of display data

Payment Plugins:

Additional method: processOrder() in Controllers\FrontController
Optional method: endApp() for callbacks

Total Plugins:

Method: processDataTotal($data) returning calculated totals

Defensive Programming Pattern

System uses defensive checks to prevent fatal errors:

This pattern allows graceful degradation if plugin is incomplete or misconfigured.

Sources: src/Controllers/ShopCartController.php184-189 src/Controllers/ShopCartController.php672

Checkout Integration Points

The checkout process integrates plugins at multiple controller methods:

Step 3: Display Plugins (_getCheckout)

Shipping, payment, and total plugins loaded and passed to view:

View receives: $shippingMethod, $paymentMethod, $totalMethod arrays for rendering.

Sources: src/Controllers/ShopCartController.php176-213

Step 4: Validate and Store (processCheckout)

User selections stored in session with validation:

Sources: src/Controllers/ShopCartController.php352-359

Step 5: Confirm Selections (_getCheckoutConfirm)

Retrieves plugin instances from session to display on confirmation page:

Also validates plugin configuration is still active:

Sources: src/Controllers/ShopCartController.php445-479

Step 6: Execute Payment (addOrder)

Payment plugin's processOrder() method invoked:

If payment plugin doesn't exist or lacks processOrder(), system defaults to completeOrder().

Sources: src/Controllers/ShopCartController.php669-676

Payment Plugin Flow

Payment plugins handle the most complex integration, as they must process financial transactions and potentially redirect users to external payment gateways.

Payment Plugin Interface

Required Class: App\Plugins\{PluginKey}\Controllers\FrontController

Required Method: processOrder()

Method Signature:

Payment Processing Flow

Session Data Available

Payment plugins can access:

Session Key	Type	Description
`orderID`	string	Newly created order ID
`dataOrder`	array	Order details (customer, totals, etc.)
`arrCartDetail`	array	Cart items with products
`shippingAddress`	array	Customer shipping information
`paymentMethod`	string	Selected payment plugin key
`shippingMethod`	string	Selected shipping plugin key
`dataTotal`	array	Order total breakdown

Sources: src/Controllers/ShopCartController.php641-646

Example: Cash on Delivery Plugin

Simplest payment plugin that doesn't require external processing:

Sources: src/Controllers/ShopCartController.php669-676

Shipping Plugin Flow

Shipping plugins provide delivery method options and calculate shipping costs.

Shipping Plugin Interface

Required Class: App\Plugins\{PluginKey}\AppConfig

Required Method: getInfo()

Return Structure:

Shipping Integration Points

Shipping plugins are loaded at checkout display and used in total calculations:

Display Stage: getInfo() called to show available shipping options
Selection Stage: User choice stored in session as shippingMethod
Calculation Stage: Shipping fee retrieved from plugin and added to order totals
Order Stage: Shipping method string stored in shop_order.shipping_method column

Sources: src/Controllers/ShopCartController.php176-191 src/Controllers/ShopCartController.php445-460 src/Controllers/ShopCartController.php577

Total Plugin Flow

Total plugins calculate additional order amounts like taxes, discounts, and fees.

Total Plugin Interface

Required Class: App\Plugins\{PluginKey}\AppConfig

Required Method: processDataTotal($data)

Method Signature:

Total Calculation Flow

Total plugins are invoked by ShopOrderTotal::processDataTotal():

Total Types

Total plugins typically implement one of these calculation types:

Type	Code	Purpose	Sort Order
Subtotal	`subtotal`	Sum of cart items	1
Shipping	`shipping`	Shipping fee	10
Tax	`tax`	Sales tax calculation	20
Discount	`discount`	Coupons, promotions (negative)	30
Other Fee	`other_fee`	Processing fees	40
Total	`total`	Final amount	100

The sort value determines display order in checkout and order totals.

Sources: src/Controllers/ShopCartController.php204-213 src/Controllers/ShopCartController.php270 src/Controllers/ShopCartController.php487-491

Configuration and Enablement

Plugin availability is controlled by configuration entries:

Configuration Check

Before loading a plugin, system verifies it's enabled:

This checks for configuration key matching the plugin key (e.g., $Shipping_flat_rate).

Sources: src/Controllers/ShopCartController.php450 src/Controllers/ShopCartController.php469

Feature Toggles

Configuration system also controls whether plugin types are used:

When feature is disabled, entire plugin category is skipped.

Sources: src/Controllers/ShopCartController.php352 src/Controllers/ShopCartController.php357 src/Controllers/ShopCartController.php445 src/Controllers/ShopCartController.php464

Error Handling and Fallbacks

The plugin system implements defensive programming to handle missing or malformed plugins gracefully:

Class Existence Checks

Prevents fatal errors when plugin files are missing.

Sources: src/Controllers/ShopCartController.php184 src/Controllers/ShopCartController.php457 src/Controllers/ShopCartController.php476

Method Existence Checks

Allows plugins with incomplete implementations to be installed without breaking the system.

Sources: src/Controllers/ShopCartController.php186 src/Controllers/ShopCartController.php672

Default Fallback

If payment plugin cannot be executed, system falls back to completeOrder():

This ensures checkout can complete even with plugin failures.

Sources: src/Controllers/ShopCartController.php672-676

Creating Custom Plugins

Plugin Development Checklist

1. Directory Structure

app/Plugins/{Type}/{PluginKey}/
├── AppConfig.php
├── Controllers/
│ └── FrontController.php (payment plugins only)
├── Views/ (optional)
└── config.php (optional)

2. AppConfig Class

All plugin types require:

3. Payment Plugin Controller

Payment plugins add:

4. Database Configuration

Add entry to admin_config table:

5. Enable Plugin

Set configuration active:

Sources: src/Controllers/ShopCartController.php176-213 src/Controllers/ShopCartController.php669-676

Summary

The GP247/Shop plugin system provides extensibility through:

Convention over Configuration: No interfaces or inheritance required, just naming conventions
Database-Driven Discovery: Plugins registered in admin_config table and queried at runtime
Defensive Programming: Extensive class_exists() and method_exists() checks prevent fatal errors
Session-Based State: Plugin selections and order data passed via session during checkout
Three Plugin Types: Shipping, payment, and total plugins integrate at specific lifecycle points
Graceful Degradation: Missing or malformed plugins don't break the checkout process

The system allows third-party developers to extend core functionality by following simple conventions and implementing specific methods, without requiring modifications to core files.

Refresh this wiki

URL: https://deepwiki.com/gp247net/shop/6-plugin-and-extension-system