Upgrades

TrellisCart uses a signed update system. Every release ZIP is signed with Ed25519 and verified before installation.

Automatic Update Check

TrellisCart checks trelliscart.com/releases.json once per day for new versions. When an update is available, a notification appears in the admin dashboard.

Installing an Update

Manual Update

You can also manually place a release ZIP in storage/updates/. The ZIP must have a matching .sig manifest file alongside it. Without the manifest, the update is refused.

Rollback

If an update causes problems, go to Upgrade Center → Backup History and click Rollback on the backup taken before the update. The rollback restores files and database from the backup.

Products & Catalog

Manage your product catalog from the admin panel under Catalog → Products.

Adding a Product

Product Fields Reference

Stock Behavior

Stock is not decremented when an order is placed. It decrements when:

• A PayPal payment is captured (via return URL or webhook)
• An admin manually changes order status from Pending to Processing or Shipped

This prevents abandoned carts from permanently reducing inventory.

Categories

TrellisCart supports unlimited nested category levels. Categories can have images, descriptions, and SEO settings.

Creating Categories

Go to Catalog → Categories and click Add Category. Set the name, parent category (for subcategories), and optionally upload a category image.

Category Images

Category images are displayed on the homepage category grid and category listing pages. Accepted formats: JPG, PNG, WebP, GIF. Images are stored in public/images/categories/.

Nesting

To create a subcategory, select a parent when creating the category. TrellisCart supports unlimited depth, but three levels (top → sub → sub-sub) is recommended for usability.

Category Slugs

Slugs are generated automatically from the category name. They must be unique. You can edit the slug when creating or editing a category. Changing a slug after products are linked may affect URLs.

Shipping

TrellisCart supports flat-rate shipping, free shipping thresholds, and live carrier rates from FedEx, UPS, and USPS.

Flat Rate Shipping

Configure flat rates under Store → Shipping:

• Standard: Default rate applied to most orders
• Expedited: Optional faster shipping option
• Overnight: Optional priority shipping option
• Free Shipping Minimum: Order total above which shipping is free

Carrier Plugins

Live carrier rates require API credentials from each carrier. Configure under Plugins → [Carrier] Shipping.

How Rates Are Calculated

At checkout, TrellisCart collects the customer's destination address and queries enabled carrier plugins. Available rates are displayed to the customer who selects their preferred method. The selected method and rate are stored on the order.

Tax Zones

TrellisCart supports per-state and per-country tax rates with a global fallback. Configure under Store → Tax Rates.

Zone-Based Tax

Enable Zone-Based Tax in the Tax Settings card to activate per-location rates. When enabled, the system looks up the customer's state and country at checkout and applies the matching rate.

Rate Lookup Order

1. Exact state + country match (e.g., New Mexico + US)
2. Country-wide rate with no state (e.g., all US states)
3. Global catch-all rate (no country, no state)
4. Global fallback rate from Settings

Adding a Tax Rate

Multiple Rates (Stacking)

Multiple active rates for the same state are summed in priority order. Use this for separate state and county rates. Lower priority number = applied first.

Global Fallback

The global rate applies when no zone rate matches. Set it to 0 if you only collect tax in specific states.

Payment Setup

TrellisCart includes a PayPal Orders API v2 plugin. Card payments require a separate gateway plugin with client-side tokenization.

PayPal Setup

Order Payment Flow

1. Customer selects PayPal at checkout
2. TrellisCart creates a PayPal order and redirects customer to PayPal
3. Customer approves payment on PayPal
4. Customer is returned to your store and the capture is attempted
5. On success: order status → Processing, stock decremented, coupon use incremented
6. PayPal also sends a webhook confirming capture (idempotent — safe if both fire)

Card Payments

Raw card data is never collected or stored by TrellisCart. Card payments require a gateway plugin (Stripe, Authorize.net) that tokenizes card data on the client side before any data reaches your server. Orders placed via card stay in Pending status until the gateway confirms payment.

Coupons

Create discount codes under Catalog → Coupons. TrellisCart supports percentage, fixed amount, and free shipping coupon types.

Coupon Types

Coupon Options

• Minimum Order: Coupon only applies if subtotal meets this amount
• Max Uses: Limits total redemptions across all customers (0 = unlimited)
• Active: Toggle to enable or disable without deleting

Coupon Use Timing

Coupon use count increments only after payment is confirmed — not when the order is placed. This prevents abandoned orders from consuming coupon uses.

Zen-Cart Import

Migrate your existing Zen-Cart store to TrellisCart using the built-in importer. Go to Admin → Zen-Cart Import.

What Gets Imported

Running the Import

Re-running the Import

You can safely re-run the importer. With Skip Duplicates enabled, existing products (matched by SKU) are skipped. To do a full fresh import, clear the relevant tables in phpMyAdmin first.

Admin Users & Roles

TrellisCart uses role-based access control with three built-in roles. Manage users under Admin → Admin Users.

Roles

Staff Permissions

• View orders (read-only)
• View product catalog (read-only)
• Upload media images

Admin Permissions

Everything staff can do, plus:

• Edit orders and update order status
• Edit products, categories, manufacturers
• View and edit customers
• View reports
• Edit banners, newsletters, coupons, and gift certificates
• Change store settings

Superadmin Permissions

Everything admin can do, plus:

• Manage admin user accounts and roles
• Run upgrades and rollbacks
• Run Zen-Cart importer
• Manage and configure plugins
• Edit CMS pages (raw HTML)
• View activity logs

Managing Orders

View and manage all orders from Sales → Orders.

Order Statuses

Stock and Coupon Accounting

When an admin changes an order from Pending → Processing (for COD or bank transfer orders), TrellisCart automatically decrements stock and increments coupon use count. This only happens once — subsequent status changes do not re-decrement.

Adding a Tracking Number

Open an order, scroll to the Shipping section, and enter the tracking number and carrier. The customer receives an email notification with a link to track their shipment.

Issuing a Refund

PayPal refunds can be initiated from the order detail page. For other payment methods, process the refund through your payment provider and then manually update the order status to Refunded.

Saved Carts

Abandoned carts are visible under Sales → Saved Carts. You can view cart contents and send a recovery email to the customer.

Email Setup

TrellisCart sends transactional emails for orders, account creation, and password resets.

Emails Sent Automatically

SMTP Configuration

Go to Configuration → Email and set:

• Transport: SMTP
• Host: Your SMTP server (e.g. smtp.yourdomain.com)
• Port: 587 for TLS, 465 for SSL
• Encryption: TLS (recommended) or SSL
• Username / Password: Your email credentials
• From Name / Address: What customers see as the sender

Media & Images

Upload and manage images from Content → Media.

Upload Restrictions

• Allowed types: JPG, PNG, WebP, GIF (validated by file content, not extension)
• Maximum size: 5MB per file
• SVG: Not allowed (SVG can contain JavaScript)
• Filenames: Randomized on upload — original filename is not used

Image Locations

Plugin System

TrellisCart plugins live in the plugins/ directory. Each plugin is a self-contained folder with its own PHP files, admin settings, and frontend handlers.

Plugin Structure

plugins/
└── myplugin/
    ├── myplugin.php         ← Main plugin file (required)
    ├── admin/
    │   └── settings.php     ← Admin settings page
    ├── includes/
    │   └── class-api.php    ← Plugin classes
    └── webhooks/
        └── handler.php      ← Webhook endpoint

Main Plugin File

The main plugin file (myplugin.php) must define plugin metadata and register the plugin with TrellisCart:

PHP '0',
    'api_key'    => '',
    'api_mode'   => 'sandbox',
];

Accessing TrellisCart Functions

All TrellisCart core functions are available in plugins after including bootstrap:

PHPrequire_once dirname(__DIR__, 2) . '/includes/bootstrap.php';

Plugin Settings Page

Plugin admin pages go in admin/settings.php inside your plugin folder. Require admin access at the top:

PHPrequire_once dirname(__DIR__, 3) . '/includes/bootstrap.php';
tc_require_admin('admin'); // or 'superadmin'

Storing Plugin Settings

Use the tc_configuration table to store plugin settings. All core config functions work for plugins:

PHP// Read a setting
$apiKey = tc_config('myplugin_api_key', '');

// Save a setting
tc_update(tc_table('configuration'),
    ['config_value' => $newValue],
    'config_key=?', ['myplugin_api_key']
);

PHP Function Reference

Core functions available throughout TrellisCart and in plugins after loading bootstrap.

Database

$products = tc_rows(
    'SELECT * FROM ' . tc_table('products') . ' WHERE is_active=? ORDER BY sort_order',
    [1]
);

$product = tc_row(
    'SELECT * FROM ' . tc_table('products') . ' WHERE product_id=?',
    [$productId]
);

$count = tc_val('SELECT COUNT(*) FROM ' . tc_table('orders') . ' WHERE status_id=?', [1]);

$orderId = tc_insert(tc_table('orders'), [
    'customer_id' => $customerId,
    'status_id'   => 1,
    'total'       => 49.99,
]);

tc_update(tc_table('orders'),
    ['status_id' => 2],
    'order_id=?', [$orderId]
);

$table = tc_table('products'); // Returns e.g. "tc_products"

Configuration

$storeName = tc_config('store_name', 'My Store');
$taxRate   = (float) tc_config('tax_rate', '0');

Authentication

tc_require_admin();            // Any logged-in admin
tc_require_admin('admin');     // Admin or superadmin
tc_require_admin('superadmin'); // Superadmin only

tc_require_permission('orders_edit');
tc_require_permission('catalog_edit');
tc_require_permission('upgrade_manage');

// In form:
echo '';

// In POST handler:
if (!tc_csrf_verify($_POST['csrf_token'] ?? '')) {
    die('Invalid request');
}

Helpers

echo e($product['name']); // Safe output

$name = tc_sanitize($_POST['name'] ?? '');

tc_redirect('/account/');         // Relative
tc_redirect('https://example.com'); // Absolute

$url = tc_base() . '/catalog/search.php?q=' . urlencode($query);

tc_admin_log('plugin_action', 'Processed payment for order #' . $orderId);

Cart

// In a payment plugin after successful capture:
tc_finalize_paid_order($orderId, $captureTransactionId);

Hooks & Events

TrellisCart's hook system lets plugins respond to store events without modifying core files.

Current Integration Points

Adding a Shipping Plugin

See the Shipping Plugins guide for the interface a shipping plugin must implement.

Adding a Payment Plugin

See the Payment Plugins guide for the interface a payment plugin must implement.

Shipping Plugins

Build a shipping rate plugin by creating a rate.php file in your plugin folder that returns available shipping methods.

How Shipping Plugins Work

1. During checkout, TrellisCart scans enabled plugins for a rate.php file
2. Each rate.php receives destination info and cart contents and returns available rates
3. All rates from all enabled plugins are merged and displayed to the customer

rate.php Interface

PHP 'mycarrier_ground',
        'label' => 'My Carrier Ground (3-5 days)',
        'cost'  => 7.99,
    ],
    [
        'id'    => 'mycarrier_express',
        'label' => 'My Carrier Express (1-2 days)',
        'cost'  => 14.99,
    ],
];

Rate Object Fields

Payment Plugins

Payment plugins handle the checkout payment step. TrellisCart never stores raw card data — all payment plugins must use client-side tokenization or redirect flows.

Payment Flow

1. Customer selects payment method at checkout step 2
2. Customer reviews order at checkout step 3 and clicks Place Order
3. Order is created in Pending status
4. Customer is redirected to gateway or gateway-hosted fields collect a token
5. On successful payment: call tc_finalize_paid_order($orderId, $captureId)
6. Customer is shown order confirmation

Using tc_finalize_paid_order()

This function handles everything after a confirmed payment: status update, stock decrement, coupon increment. It is idempotent — safe to call from both the return URL and a webhook.

PHP// After confirming payment with your gateway:
$success = tc_finalize_paid_order($orderId, $gatewayTransactionId);

if ($success) {
    tc_redirect('/checkout/confirmation.php');
} else {
    // Already finalized or order not found
    tc_redirect('/checkout/confirmation.php');
}

Webhook Handlers

Payment webhooks must independently verify the request comes from the gateway before taking any action. Never trust a webhook payload without cryptographic verification.

PHP// Example: verify webhook signature before processing
$rawBody  = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';

if (!myGateway_verifySignature($rawBody, $signature, $webhookSecret)) {
    http_response_code(400);
    exit;
}

$event = json_decode($rawBody, true);
// Process event...

Security Guide

Security practices built into TrellisCart and steps you should take before going live.

Built-In Security Features

Before Going Live

• Enable HTTPS and redirect all HTTP traffic to HTTPS
• Set TC_DEBUG to false in config.php
• Use a strong, unique SECRET_KEY (32+ random characters)
• Change all default passwords immediately
• Delete or rename the install/ directory
• Configure the updater public key in UpgradeManager.php
• Set up the PayPal Webhook ID before accepting PayPal payments
• Restrict admin access by IP in your server config where possible
• Ensure storage/backups/ is not web-accessible
• Test order flow with a PayPal sandbox account before going live

Password Policy

• Customer passwords: minimum 12 characters
• Admin passwords: use a password manager to generate long random passwords
• Never reuse passwords across services
• Admin accounts are locked after 5 failed login attempts with exponential backoff

Sensitive File Locations

These files contain sensitive information and must be protected:

Best Practices

Recommendations for running TrellisCart reliably and securely in production.

Development Practices

• Never develop directly on a live store — use a staging environment
• Test all payment flows with sandbox accounts before going live
• Use version control for any customizations
• Keep config.php out of version control
• Use TC_DEBUG = true only in development — never in production

Plugin Development

• Always call tc_require_admin() at the top of admin pages
• Always verify CSRF tokens on POST requests with tc_csrf_verify()
• Use tc_table() for all table names — never hardcode
• Use prepared statements — never string concatenation for SQL values
• Escape all output with e()
• Log plugin actions with tc_admin_log()
• Use tc_finalize_paid_order() for all payment confirmations
• Never store API keys in PHP files that could be committed to git

Operations

• Back up the database daily — use the Upgrade Center backup tool or your host's backup service
• Monitor the admin activity log for unusual actions
• Review low stock alerts regularly
• Test email delivery monthly — send a test email from Configuration → Email
• Check for TrellisCart updates regularly — security patches are released as updates
• Review admin user list quarterly — remove inactive accounts

Performance

• Optimize product images before upload — aim for under 200KB per image
• Enable PHP OPcache on your server for significant performance improvement
• Use a CDN for static assets (images, CSS, JS) on high-traffic stores
• Keep the products-per-page setting reasonable (12–24) to avoid slow catalog pages

Release Signing

TrellisCart uses Ed25519 asymmetric cryptography to verify update packages. Every update ZIP must be signed before it can be installed.

How It Works

1. You generate an Ed25519 keypair once using bin/generate-keypair.php
2. The public key goes into UpgradeManager.php — this is what stores use to verify
3. The private key stays with you, offline, never shared
4. For each release, you run bin/sign-release.php which creates a .sig manifest
5. The manifest contains the ZIP's SHA256 hash and an Ed25519 signature over that hash
6. When a store installs an update, it verifies the hash and signature before extracting anything

Generating Your Keypair

BASHphp /path/to/trelliscart/bin/generate-keypair.php

This creates bin/private.key and bin/public.key. Copy the public key output and paste it into includes/classes/UpgradeManager.php at the RELEASE_PUBLIC_KEY constant.

Signing a Release

BASHphp /path/to/trelliscart/bin/sign-release.php /path/to/trelliscart-1.0.0.zip

This creates trelliscart-1.0.0.zip.sig. Upload both the .zip and the .zip.sig to your download server.

Updating releases.json

After signing, add the SHA256 hash to your releases.json file and upload it to trelliscart.com/releases.json:

JSON{
  "latest": {
    "version": "1.0.1",
    "download_url": "https://trelliscart.com/downloads/trelliscart-1.0.1.zip",
    "sha256": "paste-sha256-hash-here",
    "min_php": "8.0.0"
  }
}

What Happens Without a Signature

If a ZIP is placed in storage/updates/ without a matching .sig file, the upgrade system refuses to install it and shows an error. This is intentional — unsigned updates are never installed.

Database Schema

TrellisCart uses a prefixed table structure. The default prefix is tc_. All tables use InnoDB with utf8mb4 charset.

Core Tables

Catalog Tables

Order Tables

System Tables

File Structure

Overview of the TrellisCart directory layout.

trelliscart/
├── index.php                  ← Entry point (includes public/index.php)
├── page.php                   ← CMS page renderer
├── includes/
│   ├── bootstrap.php          ← Loaded by every page; sets up DB, session, auth
│   ├── config.php             ← Database credentials and constants (not in git)
│   ├── functions/
│   │   ├── database.php       ← tc_rows(), tc_row(), tc_insert(), etc.
│   │   ├── helpers.php        ← e(), tc_sanitize(), tc_redirect(), etc.
│   │   ├── cart.php           ← Cart functions and tc_finalize_paid_order()
│   │   ├── auth.php           ← tc_require_admin(), RBAC, login functions
│   │   └── mail.php           ← Email sending via SMTP
│   └── classes/
│       ├── UpgradeManager.php ← Signed update system
│       └── ZenCartImporter.php← Zen-Cart migration tool
├── admin/                     ← Admin panel pages
│   ├── login.php
│   ├── index.php              ← Dashboard
│   ├── orders/
│   ├── catalog/
│   ├── customers/
│   ├── reports/
│   ├── store/
│   ├── content/
│   ├── system/
│   └── upgrade.php
├── public/
│   ├── index.php              ← Storefront homepage
│   ├── css/
│   ├── js/
│   └── images/
│       ├── products/          ← Product images (PHP execution blocked)
│       └── categories/        ← Category images
├── account/                   ← Customer account pages
├── cart/                      ← Cart page
├── catalog/                   ← Search, category, product pages
├── checkout/                  ← Checkout steps 1-4
├── plugins/
│   ├── paypal/
│   ├── fedex/
│   ├── ups/
│   └── usps/
├── templates/
│   ├── storefront/            ← Header, footer, product card templates
│   └── admin/                 ← Admin sidebar, topbar templates
├── install/
│   ├── index.php              ← Web installer
│   ├── schema.sql             ← Full database schema
│   └── migrations/            ← Incremental schema updates
├── storage/
│   ├── backups/               ← Update backups (not web-accessible)
│   ├── updates/               ← Uploaded update ZIPs
│   ├── staging/               ← Temporary extraction during updates
│   └── cache/                 ← Rate limiting and config cache files
└── bin/
    ├── generate-keypair.php   ← One-time Ed25519 keypair generator
    └── sign-release.php       ← Sign a release ZIP for distribution

Key Configuration Files

Changelog

Version history for TrellisCart.

v1.0.0 — Initial Release

April 2026 — Trellis Group LLC

Features

• Full storefront with category browsing, product pages, search, and featured products
• Multi-step checkout with address, shipping method selection, payment, and confirmation
• Complete admin panel — orders, products, categories, customers, reports, content, and settings
• PayPal Orders API v2 plugin with full webhook signature verification
• FedEx, UPS, and USPS live shipping rate plugins
• Zone-based tax rates by state and country with stacking support
• Coupon system — percent, fixed, and free shipping types with max-use limits
• Gift certificate system
• Zen-Cart importer — products, categories, customers, orders, reviews, coupons, and images
• Signed update system with Ed25519 + SHA256 mandatory verification
• Staged update extraction with rollback support
• Role-based admin access control — staff, admin, superadmin
• Granular per-action AJAX permissions
• Admin brute-force protection with IP + username lockout
• Customer login rate limiting
• Full security header suite — CSP, HSTS, X-Content-Type-Options, X-Frame-Options
• File upload validation via finfo + getimagesize + size limits
• Idempotent order finalization — safe for webhook + return URL simultaneous capture
• CMS pages and banner management
• Newsletter subscriber management
• Admin activity log
• Saved cart recovery with email sending
• Low stock reporting
• Sales and product reports

Security

• Argon2ID password hashing throughout
• Session regeneration on login (admin and customer)
• CSRF protection on all POST requests
• PDO prepared statements for all database queries
• Raw card data never collected or stored
• PayPal webhook signature verification mandatory
• Update signing mandatory — unsigned updates refused
• PHP execution blocked in upload directories