Development Setup

Guide for setting up a local development environment for the Manage Rhino Group platform.

---

Prerequisites

Requirement	Version	Purpose
PHP	8.x	WordPress and custom plugins
MySQL	8.0+	Database
Composer	2.x	PHP dependency management
Node.js	18+	Build tools (Suma Gemini only)
Git	Latest	Version control
Laravel Herd	Latest	Local WordPress hosting (recommended)

---

Initial Setup

1. Clone the Repository

git clone [bitbucket-repo-url] manage
cd manage

The repository is located at Z:\Herd\manage on the development machine.

2. Configure Laravel Herd

Laravel Herd provides the local PHP server and automatic SSL:

1. Add Z:\Herd\manage to Herd's sites directory
2. The site will be available at https://manage.test or similar
3. Herd handles PHP version management and Nginx configuration

3. Create Database

CREATE DATABASE managerhinogroup CHARACTER SET utf8 COLLATE utf8_general_ci;

4. Import Database

Import a copy of the production database (sanitized if needed):

mysql -u root managerhinogroup < managerhinogroup.sql

caution

The database contains API keys, webhook URLs, and site credentials. Handle exports with care.

5. Configure wp-config.php

Ensure these constants are set:

/** Database */
define('DB_NAME', 'managerhinogroup');
define('DB_USER', 'root');
define('DB_PASSWORD', '');
define('DB_HOST', '127.0.0.1');

/** Cross-database access */
define('OSTICKETS_DBNAME', 'ostickets');

/** Debug */
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);

6. Install Plugin Dependencies

# Suma Gemini (has Composer + npm dependencies)
cd wp-content/plugins/suma-gemini
composer install
npm install
npm run dev

# Suma Management (has Composer dependencies)
cd wp-content/plugins/suma-management
composer install

# Suma Harvest (has Composer dependencies)
cd wp-content/plugins/suma-harvest
composer install

7. Activate Plugins

In WP Admin → Plugins, activate:

• Suma Management
• Suma Gemini
• Suma Harvest
• Suma Order Volume Monitor
• Suma Toolshed
• Advanced Custom Fields Pro
• MainWP Dashboard (optional locally)

8. Configure Plugin Settings

Suma Gemini Settings (WP Admin → Suma Gemini)

• API Key: Generate at https://aistudio.google.com/apikey
• Security Key: Set a shared secret for external API calls
• Default Model: gemini-2.5-flash (recommended for development)

Suma Management Pinecone Settings

• API Key: Pinecone project API key
• Host: Index host URL (from Pinecone dashboard)
• Namespace: manage-rhinogroup
• Auto-sync: Enable/disable automatic vectorization

Harvest Settings

Configure via ACF options page:

• Account ID: Harvest account identifier
• Access Token: Personal access token from Harvest
• Projects to include/exclude: Filter project visibility

---

Development Workflow

Working on Suma Management

The main management plugin has no build step. Edit PHP/CSS/JS files directly.

wp-content/plugins/suma-management/
├── suma-management.php     ← Plugin bootstrap, hooks
├── api.php                 ← AJAX endpoint router (switch statement)
├── classes/
│   ├── Site.php            ← Site model (40+ properties)
│   ├── Site_Update.php     ← Sync engine
│   ├── Sites.php           ← Site list/query operations
│   ├── Costs.php           ← Cost CRUD
│   ├── License.php         ← License management
│   ├── Pinecone.php        ← Pinecone API client
│   ├── Pinecone_Sync.php   ← Auto-sync on site updates
│   ├── Pinecone_Settings.php
│   ├── Reports.php         ← Report generation (KoolReport)
│   ├── Admin.php           ← Admin pages, menus
│   ├── Settings.php        ← Settings pages
│   ├── Search.php          ← Site search
│   ├── Logs.php            ← Activity logging
│   ├── Lighthouse.php      ← Performance audits
│   ├── Screenshot.php      ← Screenshot capture
│   ├── Asana.php           ← Asana integration
│   ├── Git.php             ← Bitbucket integration
│   ├── Google.php          ← Google APIs (Sheets, Analytics)
│   ├── Cloudflare.php      ← Cloudflare SDK wrapper
│   └── Envato.php          ← Envato marketplace
├── views/                  ← PHP template files
├── css/                    ← Stylesheets
└── js/                     ← Frontend scripts

Working on Suma Gemini

This plugin uses Laravel Mix for asset compilation:

cd wp-content/plugins/suma-gemini

# Development (watch mode)
npm run watch

# Production build
npm run production

wp-content/plugins/suma-gemini/
├── suma-gemini.php         ← Plugin bootstrap
├── src/
│   ├── Gemini_Client.php   ← API wrapper (retries, fallback)
│   ├── Models.php          ← Available model definitions
│   ├── Rate_Limiter.php    ← Transient-based limiting
│   └── REST/
│       ├── Rewrite.php     ← POST /rewrite endpoint
│       ├── Ticket_Urgency.php ← POST /ticket-urgency endpoint
│       └── Parse_Email.php ← POST /parse-email-reply endpoint
├── resources/
│   ├── js/admin.js         ← Admin scripts
│   └── css/admin.css       ← Admin styles (Tailwind)
├── composer.json
├── package.json
└── webpack.mix.js

Working on Suma Harvest

No build step. Edit PHP files directly:

wp-content/plugins/suma-harvest/
├── suma-harvest.php        ← Plugin bootstrap
├── inc/
│   ├── API.php             ← Harvest API client (JoliCode)
│   ├── Data.php            ← Database queries
│   ├── Milestones.php      ← Milestone management
│   ├── Report.php          ← Milestone checking
│   ├── Teams.php           ← Teams webhook integration
│   ├── models/
│   │   ├── Client.php
│   │   ├── Project.php
│   │   ├── Task.php
│   │   ├── Time_Entry.php
│   │   └── Milestone.php
│   └── routes/
│       ├── default.php     ← Main dashboard
│       ├── project.php     ← Project detail
│       ├── recent_time.php ← Recent time entries
│       ├── user_project.php ← User breakdown
│       └── task_project.php ← Task breakdown
└── views/                  ← Dashboard templates

---

Debugging

PHP Debug Logging

All errors log to wp-content/debug.log:

// Custom logging
error_log('[Suma Management] Site sync failed for site_id: ' . $site_id);

Xdebug Configuration

For VS Code debugging, add to php.ini:

[xdebug]
xdebug.mode=debug
xdebug.start_with_request=yes
xdebug.client_port=9003

VS Code launch configuration:

{
  "name": "Listen for Xdebug",
  "type": "php",
  "request": "launch",
  "port": 9003,
  "pathMappings": {
    "/path/to/manage": "${workspaceFolder}"
  }
}

Testing AJAX Endpoints

Use the browser console or Postman:

// Browser console (when logged into WP Admin)
jQuery.post(ajaxurl, {
    action: 'get_sites',
    nonce: sumaManagement.nonce
}, function(response) {
    console.log(response);
});

Testing REST Endpoints

# Test Gemini urgency endpoint
curl -X POST https://manage.test/wp-json/suma/gemini/ticket-urgency \
  -H "Content-Type: application/json" \
  -H "suma-gemini-security-key: your-api-key" \
  -d '{"subject": "Site is down", "body": "Production site returning 500 errors", "client_name": "Test Client"}'

Testing Cron Scripts Locally

# Run any cron script directly
cd Z:\Herd\manage
php cron/site-updates.php
php cron/daily-site-check.php

---

Git Workflow

Branch Strategy

• main / master — Production (deployed to WP Engine)
• Feature branches — feature/description
• Hotfix branches — hotfix/description

Deployment

The site runs on WP Engine. Deployment is via Git push:

git remote add production [wpengine-git-url]
git push production main

Or via WP Engine's deployment pipeline.

---

Common Tasks

Adding a New AJAX Endpoint

1. Open wp-content/plugins/suma-management/api.php
2. Add a new case to the switch statement:

case 'your_new_action':
    // Validate nonce is already handled at the top
    $result = $your_class->your_method($_POST);
    wp_send_json_success($result);
    break;

3. Register the JavaScript action in the frontend

Adding a New Cron Script

1. Create file in cron/ directory
2. Add WordPress bootstrap at the top:

<?php
require_once dirname(__DIR__) . '/wp-load.php';

3. Add to server crontab with appropriate schedule
4. Document in this page

Adding a New Toolshed Route

1. Create subdirectory in suma-toolshed/inc/routes/your-route/
2. Create init.php with route class:

<?php
namespace Suma\ToolShed\Routes\YourRoute;

use Suma\ToolShed\Route;

class Your_Route extends Route {
    public function register_routes(): void {
        register_rest_route('suma-tools/v1', '/your-route', [
            'methods'  => 'POST',
            'callback' => [$this, 'handle'],
            'permission_callback' => [$this, 'check_permissions'],
        ]);
    }
}

3. The route will be auto-discovered on next load