RewriteCond %{REQUEST_URI} ^/cart/trellis/ [NC]
RewriteRule ^ - [L]

trelliscart/                 ← Install root (TC_ROOT)
├── index.php                ← Root entry point
├── .htaccess                ← Apache config, RewriteBase, security
├── includes/
│   ├── bootstrap.php        ← Loaded first by every page
│   ├── config.php           ← DB credentials (auto-generated by installer)
│   ├── functions/
│   │   ├── database.php     ← tc_row/rows/val/insert/update/query/table
│   │   ├── helpers.php      ← tc_money/base/asset/redirect/sanitize/csrf
│   │   ├── cart.php         ← tc_cart_add/get/update/save/restore
│   │   └── auth.php         ← tc_require_admin/customer, login functions
│   └── classes/             ← PSR-4 autoloaded. Drop MyClass.php here.
├── plugins/                 ← YOUR PLUGINS GO HERE
│   └── my-plugin/
│       ├── plugin.json      ← Manifest (name, settings schema)
│       └── plugin.php       ← Plugin class
├── public/
│   ├── index.php            ← Storefront homepage
│   ├── css/                 ← storefront.css, admin.css
│   ├── js/                  ← storefront.js, admin.js
│   └── images/products/     ← Product image uploads
├── admin/                   ← All admin panel pages
├── catalog/                 ← Storefront: category, product, search
├── cart/                    ← Cart AJAX endpoints
├── checkout/                ← Checkout and confirmation
├── account/                 ← Customer account pages
├── templates/
│   ├── admin/               ← sidebar.php, topbar.php
│   └── storefront/          ← header.php, footer.php, product-card.php
├── install/                 ← Web installer (delete after setup)
└── storage/                 ← Backups, cache, logs (not web-accessible)

define('DB_HOST',    'localhost');
define('DB_NAME',    'your_database');
define('DB_USER',    'db_user');
define('DB_PASS',    'db_password');
define('DB_PREFIX',  'tc_');
define('STORE_URL',  'https://yourstore.com/cart/trellis');
define('SECRET_KEY', '64-char-random-hex...');

// Optional: enable full stack traces on errors
// define('TC_DEBUG', true);

tc_config('store_name', 'My Store');    // returns value or default
tc_config('currency_symbol', '$');          // always use tc_config() not constants

// URL: /cart/trellis/catalog/product.php?slug=my-product
// → Maps directly to catalog/product.php
// No router, no MVC — just a PHP file that loads bootstrap
// and queries the DB based on $_GET['slug']

// All links and redirects use tc_base() to get the install path:
tc_base();  // → "/cart/trellis"
tc_asset('/public/css/admin.css');  // → "/cart/trellis/public/css/admin.css"

// In every form:
<form method="post">
  <input type="hidden" name="csrf_token" value="<?= e(tc_csrf_token()) ?>">
  ...
</form>

// In the handler:
if (tc_csrf_verify($_POST['csrf_token'] ?? '')) {
    // process form...
}

// Fetch a single row (returns array or null)
$product = tc_row(
    "SELECT * FROM " . tc_table('products') . " WHERE product_id=? AND is_active=1",
    [(int)$_GET['id']]
);

// Fetch multiple rows
$orders = tc_rows(
    "SELECT * FROM " . tc_table('orders') . " WHERE customer_id=? ORDER BY order_id DESC",
    [$customerId]
);

// Insert a row (returns new auto-increment ID)
$newId = tc_insert(tc_table('my_table'), [
    'name'    => $name,
    'user_id' => $userId,
]);

// Update rows (returns affected row count)
tc_update(
    tc_table('products'),
    ['is_featured' => 1],   // SET
    'product_id=?',           // WHERE
    [$productId]
);

// Raw query (DELETE, complex WHERE, CREATE TABLE)
tc_query(
    "DELETE FROM " . tc_table('my_table') . " WHERE id=?",
    [$id]
);

// ✗ WRONG — will fail with ONLY_FULL_GROUP_BY error
"SELECT p.*, m.name AS brand FROM tc_products p
 LEFT JOIN tc_manufacturers m ON p.manufacturer_id=m.manufacturer_id
 GROUP BY p.product_id"

// ✓ CORRECT — wrap joined columns in ANY_VALUE()
"SELECT p.*, ANY_VALUE(m.name) AS brand FROM tc_products p
 LEFT JOIN tc_manufacturers m ON p.manufacturer_id=m.manufacturer_id
 GROUP BY p.product_id"

plugins/
└── my-plugin/
    └── my-plugin.php    ← Main file. Loaded from bootstrap.php.

if (file_exists(TC_ROOT . '/plugins/my-plugin/my-plugin.php')) {
    require_once TC_ROOT . '/plugins/my-plugin/my-plugin.php';
}

{
  "name":        "My Plugin",
  "slug":        "my-plugin",
  "version":     "1.0.0",
  "description": "Does something awesome.",
  "author":      "Your Name",
  "icon":        "🚀",
  "settings": [
    {
      "key":     "api_key",
      "label":   "API Key",
      "type":    "text",
      "default": "",
      "hint":    "Your API key from example.com"
    },
    {
      "key":     "enabled",
      "label":   "Enable Plugin",
      "type":    "checkbox",
      "default": "1"
    }
  ]
}

<?php
// plugins/my-plugin/my-plugin.php
// This file is required by bootstrap.php on every request.

// ── One-time install ───────────────────────────────────────────────
if (!tc_config('my_plugin_installed', '')) {
    $sql = file_get_contents(TC_ROOT . '/plugins/my-plugin/install.sql');
    foreach (array_filter(array_map('trim', explode(';', $sql))) as $stmt) {
        if ($stmt) tc_db()->exec($stmt);
    }
    try {
        tc_insert(tc_table('configuration'), [
            'config_key'   => 'my_plugin_installed',
            'config_value' => '1',
            'group_name'   => 'plugins',
        ]);
    } catch (Exception $e) { /* already exists */ }
}

// ── Plugin functions ───────────────────────────────────────────────

/** Get a plugin-specific config value. */
function my_plugin_config(string $key, string $default = ''): string {
    return tc_config('my_plugin_' . $key, $default);
}

/** Save a plugin-specific config value. */
function my_plugin_set(string $key, string $value): void {
    $k = 'my_plugin_' . $key;
    $exists = tc_val("SELECT config_id FROM " . tc_table('configuration') . " WHERE config_key=?", [$k]);
    if ($exists) tc_update(tc_table('configuration'), ['config_value' => $value], 'config_key=?', [$k]);
    else tc_insert(tc_table('configuration'), ['config_key' => $k, 'config_value' => $value, 'group_name' => 'plugins']);
}

// In catalog/product.php, after the description output:
if (function_exists('my_plugin_after_description')) {
    my_plugin_after_description($product);
}

// In your plugin file, define the function:
function my_plugin_after_description(array $product): void {
    echo '<p>Extended warranty available for ' . e($product['name']) . '</p>';
}

// Read a setting
$apiKey = tc_config('my_plugin_api_key', '');
$enabled = tc_config('my_plugin_enabled', '1');

// Guard: only run if plugin is enabled
if (!tc_config('my_plugin_enabled', '1')) return;

// Write a setting
$exists = tc_val("SELECT config_id FROM " . tc_table('configuration') . " WHERE config_key=?", ['my_plugin_api_key']);
if ($exists) {
    tc_update(tc_table('configuration'), ['config_value' => $value], 'config_key=?', ['my_plugin_api_key']);
} else {
    tc_insert(tc_table('configuration'), ['config_key' => 'my_plugin_api_key', 'config_value' => $value, 'group_name' => 'plugins']);
}

// plugins/my-gateway/my-gateway.php

/** Render the payment radio button at checkout */
function my_gateway_render_option(): void {
    echo '<label><input type="radio" name="payment_method" value="my-gateway"> Pay with My Gateway</label>';
}

/** Process the payment — called during order placement */
function my_gateway_process(array $context): array {
    // Only handle if our method was selected
    if (($_POST['payment_method'] ?? '') !== 'my-gateway') {
        return $context; // not our method — pass through unchanged
    }
    try {
        // Call your gateway API here...
        $context['transaction_id'] = 'txn_123abc';
        $context['payment_method'] = 'My Gateway';
        $context['payment_status'] = 'paid';
    } catch (Throwable $e) {
        $context['error'] = 'Payment failed: ' . $e->getMessage();
    }
    return $context; // always return context
}

plugins/
└── sale-banner/
    └── sale-banner.php

<?php
// plugins/sale-banner/sale-banner.php
// Register in bootstrap.php: require_once TC_ROOT . '/plugins/sale-banner/sale-banner.php';

function sale_banner_render(): void {
    if (!tc_config('sale_banner_enabled', '1')) return;
    $message = tc_config('sale_banner_message', 'Free shipping on orders over $49!');
    $bg      = tc_config('sale_banner_color', '#2d6a4f');
    echo '<div id="sale-banner" style="background:'
       . e($bg)
       . ';color:#fff;text-align:center;padding:.6rem 1rem;font-size:.88rem">'
       . e($message)
       . ' <button onclick="this.parentNode.style.display=\'none\'"'
       . ' style="background:none;border:none;color:#fff;cursor:pointer;margin-left:.5rem">&times;</button></div>';
}

<?php if (function_exists('sale_banner_render')) sale_banner_render(); ?>

<?php
// plugins/my-plugin/storefront/my-page.php
// URL: /cart/trellis/plugins/my-plugin/storefront/my-page.php
require_once dirname(__DIR__, 3) . '/includes/bootstrap.php';

// Adjust depth: count levels from your file to TC_ROOT
// catalog/product.php      → dirname(__DIR__)
// account/orders.php       → dirname(__DIR__)
// admin/catalog/page.php   → dirname(__DIR__, 2)
// plugins/mine/admin/page  → dirname(__DIR__, 3)

$data = tc_rows('SELECT * FROM ' . tc_table('my_table') . ' ORDER BY name');
?>
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>My Page — <?= e(tc_config('store_name')) ?></title>
<link rel="stylesheet" href="<?= tc_asset('/public/css/storefront.css') ?>">
</head>
<body>
<?php require_once TC_ROOT . '/templates/storefront/header.php'; ?>

<nav class="tc-breadcrumb"><ol>
  <li><a href="<?= tc_base() ?>/">Home</a></li>
  <li class="active">My Page</li>
</ol></nav>

<div class="tc-section"><div class="tc-container">
  <h1 class="tc-section-title">My <em>Page</em></h1>
  <!-- your content -->
</div></div>

<?php require_once TC_ROOT . '/templates/storefront/footer.php'; ?>
<script src="<?= tc_asset('/public/js/storefront.js') ?>"></script>
</body></html>

<?php
// plugins/my-plugin/admin/index.php
require_once dirname(__DIR__, 3) . '/includes/bootstrap.php';
tc_require_admin(); // redirect to login if not authenticated

$success = false;
$errors  = [];

if ($_SERVER['REQUEST_METHOD'] === 'POST') {
    if (!tc_csrf_verify($_POST['csrf_token'] ?? '')) {
        $errors[] = 'Invalid token.';
    } else {
        // handle form...
        $success = true;
    }
}

$items = tc_rows('SELECT * FROM ' . tc_table('my_table') . ' ORDER BY id DESC');
?>
<!DOCTYPE html><html lang="en"><head>
<meta charset="UTF-8">
<title>My Plugin — Admin</title>
<link rel="stylesheet" href="<?= tc_asset('/public/css/admin.css') ?>">
</head><body class="tc-admin">
<?php require_once TC_ROOT . '/templates/admin/sidebar.php'; ?>
<div class="tc-admin-main">
  <?php require_once TC_ROOT . '/templates/admin/topbar.php'; ?>
  <div class="tc-admin-content">
    <div class="tc-page-header">
      <div><h1 class="tc-page-title">My Plugin</h1>
      <div class="tc-breadcrumb-admin">Plugins › My Plugin</div></div>
    </div>
    <?php if ($success): ?><div class="tc-alert tc-alert-ok">Saved.</div<?php endif; ?>
    <div class="tc-card">
      <div class="tc-card-header">Items</div>
      <div class="tc-card-body">
        <form method="post">
          <input type="hidden" name="csrf_token" value="<?= e(tc_csrf_token()) ?>">
          <!-- fields -->
        </form>
      </div>
    </div>
  </div>
</div>
<script src="<?= tc_asset('/public/js/admin.js') ?>"></script>
</body></html>

<?php
// _si($url, $label, $icon, $currentUri) — main nav item
// _ss($url, $label, $currentUri)        — sub-item
?>
<div class="tc-sidebar-divider"></div>
<div class="tc-sidebar-section">
  <div class="tc-sidebar-label">Plugins</div>
  <?= _si(tc_base().'/plugins/my-plugin/admin/index.php', 'My Plugin', '🔌', $_cur) ?>
  <?= _ss(tc_base().'/plugins/my-plugin/admin/settings.php', 'Settings', $_cur) ?>
</div>

// 1. Render the field in the product edit form
// Add to admin/catalog/product-edit.php inside the form:
<?php if (function_exists('my_plugin_product_field')) my_plugin_product_field($product); ?>

// In your plugin:
function my_plugin_product_field(array $product): void {
    $val = '';
    if (!empty($product['product_id'])) {
        $row = tc_row("SELECT value FROM " . tc_table('product_meta') .
                       " WHERE product_id=? AND meta_key='my_field'", [$product['product_id']]);
        $val = $row['value'] ?? '';
    }
    echo '<div class="tc-fg">'
       . '<label class="tc-fl">My Custom Field</label>'
       . '<input type="text" name="my_plugin_field" class="tc-fc" value="' . e($val) . '">'
       . '</div>';
}

// 2. Save the field after the product saves
// Add to admin/catalog/product-edit.php after the product is saved:
<?php if (function_exists('my_plugin_product_save')) my_plugin_product_save($productId, $_POST); ?>

function my_plugin_product_save(int $productId, array $post): void {
    $val = tc_sanitize($post['my_plugin_field'] ?? '');
    tc_query(
        "INSERT INTO " . tc_table('product_meta') .
        " (product_id, meta_key, value) VALUES (?,?,?)" .
        " ON DUPLICATE KEY UPDATE value=VALUES(value)",
        [$productId, 'my_field', $val]
    );
}

function my_plugin_send_email(string $toEmail, string $toName, string $subject, string $body): bool {
    // Try PHPMailer first, fall back to mail()
    if (class_exists('PHPMailer\PHPMailer\PHPMailer')) {
        $mail = new PHPMailer\PHPMailer\PHPMailer(true);
        $mail->isSMTP();
        $mail->Host       = tc_config('smtp_host', 'localhost');
        $mail->SMTPAuth   = true;
        $mail->Username   = tc_config('smtp_user');
        $mail->Password   = tc_config('smtp_pass');
        $mail->SMTPSecure = 'tls';
        $mail->Port       = (int) tc_config('smtp_port', '587');
        $mail->setFrom(tc_config('email_from'), tc_config('email_from_name'));
        $mail->addAddress($toEmail, $toName);
        $mail->isHTML(true);
        $mail->Subject = $subject;
        $mail->Body    = $body;
        return $mail->send();
    }
    // Fallback
    return mail($toEmail, $subject, strip_tags($body));
}

function my_plugin_rate_limit(string $key, int $max, int $windowSeconds): bool {
    $now       = time();
    $sessionKey = 'rl_' . $key;
    $record    = $_SESSION[$sessionKey] ?? ['count' => 0, 'start' => $now];

    if ($now - $record['start'] > $windowSeconds) {
        $record = ['count' => 0, 'start' => $now]; // reset window
    }
    $record['count']++;
    $_SESSION[$sessionKey] = $record;
    return $record['count'] <= $max;
}

// Usage: allow 5 submissions per 10 minutes
if (!my_plugin_rate_limit('my_action', 5, 600)) {
    $errors[] = 'Too many attempts. Please wait before trying again.';
}

RewriteCond %{REQUEST_URI} ^/cart/trellis/ [NC]
RewriteRule ^ - [L]

$product = [
    // Identity
    'product_id'       => 42,
    'sku'              => 'TC-001',
    'name'             => 'Blue Spruce Seedling',
    'slug'             => 'blue-spruce-seedling',
    // Content
    'description'      => '<p>Full HTML description.</p>',
    'short_desc'       => 'Brief description.',
    'meta_title'       => 'SEO title',
    'meta_desc'        => 'SEO description',
    // Pricing
    'price'            => '29.99',    // always a string from DB
    'sale_price'       => '24.99',    // null if no sale
    'cost_price'       => '10.00',    // internal use only
    // Inventory
    'stock_qty'        => '50',
    'stock_low_alert'  => '5',
    'track_stock'      => '1',
    // Shipping
    'weight_lbs'       => '1.500',
    'length_in'        => '10.00',
    'width_in'         => '6.00',
    'height_in'        => '4.00',
    // Flags
    'is_active'        => '1',
    'is_featured'      => '0',
    'is_new'           => '0',
    // Media
    'image'            => 'product_abc123.jpg',  // filename, may be null
    // JOINed
    'brand_name'       => 'TrellisCart Nursery',  // from tc_manufacturers
    'effective_price'  => '24.99',  // COALESCE(sale_price, price)
    // Timestamps
    'created_at'       => '2024-01-15 09:30:00',
    'updated_at'       => '2024-06-01 14:22:00',
];

// Tip: All values are strings from PDO. Cast explicitly:
(float)$product['price']      // → 29.99 (float)
(int)$product['stock_qty']  // → 50 (int)

$category = [
    'category_id'  => 5,
    'parent_id'    => 2,           // null if top-level
    'name'         => 'Trees',
    'slug'         => 'trees',
    'description'  => '<p>HTML description.</p>',
    'image'        => 'cat_trees.jpg',  // null if no image
    'meta_title'   => 'SEO title',
    'meta_desc'    => 'SEO description',
    'sort_order'   => '10',
    'is_active'    => '1',
    'is_featured'  => '0',
];

$customer = [
    'customer_id'  => 12,
    'group_id'     => 1,            // 1=Standard, 2=VIP, 3=Wholesale
    'firstname'    => 'Jane',
    'lastname'     => 'Smith',
    'email'        => 'jane@example.com',
    'phone'        => '555-1234',
    'newsletter'   => '1',
    'is_active'    => '1',
    'last_login'   => '2024-06-01 09:00:00',
    'created_at'   => '2024-01-01 00:00:00',
    // password_hash is never returned in queries — use password_verify() for checks
];

$order = [
    'order_id'        => 101,
    'customer_id'     => 12,       // null for guest orders
    'status_id'       => 2,        // 1=Pending,2=Processing,3=Shipped,4=Delivered
    'firstname'       => 'Jane',
    'lastname'        => 'Smith',
    'email'           => 'jane@example.com',
    'phone'           => '555-1234',
    'ship_address1'   => '123 Main St',
    'ship_city'       => 'Denver',
    'ship_state'      => 'CO',
    'ship_postcode'   => '80201',
    'ship_country'    => 'US',
    'ship_method'     => 'standard',
    'subtotal'        => '89.97',   // always strings from DB
    'shipping_cost'   => '6.99',
    'tax_amount'      => '0.00',
    'discount_amount' => '0.00',
    'total'           => '96.96',
    'coupon_code'     => 'SAVE10',  // null if no coupon
    'payment_method'  => 'Stripe',
    'payment_ref'     => 'txn_abc123',
    'tracking_number' => '9400111899223',  // null until shipped
    'customer_notes'  => 'Leave at door.',
    'ip_address'      => '192.168.1.1',
    'created_at'      => '2024-06-01 14:22:00',
];

// Fetch order items separately:
$items = tc_rows("SELECT * FROM " . tc_table('order_items') . " WHERE order_id=?", [$order['order_id']]);
// Each item: order_id, product_id, sku, name, options_text, quantity, unit_price, total_price

CREATE TABLE IF NOT EXISTS `tc_product_badges` (
  `product_id`  INT UNSIGNED NOT NULL,
  `badge_text`  VARCHAR(30)  DEFAULT NULL,
  `badge_color` VARCHAR(20)  DEFAULT NULL,
  PRIMARY KEY (`product_id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;

<?php
// plugins/product-badges/product-badges.php
if (!tc_config('product_badges_installed', '')) {
    tc_db()->exec(file_get_contents(TC_ROOT . '/plugins/product-badges/install.sql'));
    try { tc_insert(tc_table('configuration'),['config_key'=>'product_badges_installed','config_value'=>'1','group_name'=>'plugins']); } catch(Exception $e){}
}

/** Render badge on product page (call from catalog/product.php) */
function pb_show_badge(array $product): void {
    try {
        $row = tc_row("SELECT * FROM ".tc_table('product_badges')." WHERE product_id=?", [$product['product_id']]);
    } catch (Throwable $e) { return; }
    if (!$row || empty($row['badge_text'])) return;
    $color = $row['badge_color'] ?: '#ef4444';
    echo '<span style="background:'.e($color).';color:#fff;padding:.25rem .7rem;border-radius:4px;font-size:.8rem;font-weight:700">'.e($row['badge_text']).'</span>';
}

/** Render edit field in admin product form */
function pb_product_field(array $product): void {
    try { $row = tc_row("SELECT * FROM ".tc_table('product_badges')." WHERE product_id=?", [$product['product_id'] ?? 0]); }
    catch (Throwable $e) { $row = null; }
    echo '<div class="tc-fg"><label class="tc-fl">Badge Label</label>'
       . '<input type="text" name="pb_badge" class="tc-fc" value="'.e($row['badge_text'] ?? '').'" placeholder="NEW, HOT, LIMITED"></div>';
}

/** Save badge when product is saved */
function pb_product_save(int $productId, array $post): void {
    $text = tc_sanitize($post['pb_badge'] ?? '');
    try {
        if ($text) tc_query("INSERT INTO ".tc_table('product_badges')." (product_id,badge_text) VALUES(?,?) ON DUPLICATE KEY UPDATE badge_text=VALUES(badge_text)", [$productId,$text]);
        else tc_query("DELETE FROM ".tc_table('product_badges')." WHERE product_id=?", [$productId]);
    } catch (Throwable $e) {}
}

// In catalog/product.php, below product description:
<?php if (function_exists('pb_show_badge')) pb_show_badge($product); ?>

// In admin/catalog/product-edit.php, inside the form:
<?php if (function_exists('pb_product_field')) pb_product_field($product ?? []); ?>

// In admin/catalog/product-edit.php, after tc_insert/tc_update:
<?php if (function_exists('pb_product_save')) pb_product_save($productId, $_POST); ?>

define('TC_DEBUG', true); // Shows full stack trace on error pages

<?php
// plugins/my-plugin/my-plugin.php
// If you see the HTML comment in view-source, the plugin loads correctly.
function my_plugin_footer(): void {
    echo '<!-- my-plugin is alive -->';
}

// Check if a function exists before calling it
if (function_exists('some_other_plugin_function')) {
    some_other_plugin_function($args);
}

// Check if a table exists before querying it
try {
    $rows = tc_rows("SELECT * FROM " . tc_table('my_table'));
} catch (Throwable $e) {
    $rows = []; // table not yet installed
}

// Guard new array keys
$newField = $product['new_field_added_in_v1_1'] ?? null;