# Gocars Online - WordPress Plugin

**Version:** 2.5.0  
**Author:** Alexis Tarantos  
**License:** Proprietary  
**Requires WordPress:** 5.0+  
**Requires PHP:** 7.4+

---

## 📋 Table of Contents

-   [Overview](#-overview)
-   [Features](#-features)
-   [Installation](#-installation)
-   [Configuration](#-configuration)
-   [Credential Management](#-credential-management)
-   [Domain Authorization](#-domain-authorization)
-   [Shortcodes](#-shortcodes)
-   [Automatic Updates](#-automatic-updates)
-   [Migration Guide](#-migration-guide)
-   [Troubleshooting](#-troubleshooting)
-   [Support](#-support)
-   [Changelog](#-changelog)
-   [System Requirements](#-system-requirements)
-   [License](#-license)

---

## 🚗 Overview

Gocars Online is a comprehensive Car Rental Booking System plugin for WordPress. It integrates seamlessly with the Gocars backend platform to provide:

-   **Search Forms** - Allow customers to search for available vehicles
-   **Fleet Display** - Showcase your vehicle inventory with dynamic filtering
-   **Terms & Conditions** - Display rental terms and policies
-   **Multi-language Support** - Serve customers in multiple languages
-   **Automatic Updates** - Stay up-to-date with the latest features and fixes

---

## ✨ Features

### Core Functionality

-   🔍 **Advanced Search Forms** - Customizable booking search with location, date/time selection
-   🚙 **Fleet Management** - Display vehicle inventory with filtering and sorting
-   🌍 **Multi-language Support** - Greek, English, German, Italian support built-in
-   📱 **Responsive Design** - Mobile-friendly interface
-   🎨 **Customizable Styling** - Adjust colors, layouts, and appearance
-   ⚡ **Performance Optimized** - Caching and efficient data loading

### Integration Features

-   🔗 **Gocars Backend Integration** - Direct connection to your Gocars admin panel
-   💬 **Discord Notifications** - Real-time updates to your Discord channel
-   🔄 **Automatic Data Sync** - Hourly synchronization with backend
-   📊 **Analytics Tracking** - Monitor bookings and user behavior

### Developer Features

-   🔐 **Secure Credential Management** - Multi-tier configuration system
-   🌐 **Domain Authorization** - Control which domains can use the plugin
-   🔄 **GitHub-based Updates** - Automatic plugin updates from private repository
-   📝 **Extensive Logging** - Track issues and monitor performance

---

## 📦 Installation

### Method 1: WordPress Admin (Recommended)

1. Download the `gocars-online.zip` file
2. Go to **WordPress Admin → Plugins → Add New**
3. Click **Upload Plugin**
4. Choose the zip file and click **Install Now**
5. Click **Activate Plugin**

### Method 2: Manual Installation

1. Extract the `gocars-online.zip` file
2. Upload the `gocars-online` folder to `/wp-content/plugins/`
3. Go to **WordPress Admin → Plugins**
4. Find **Gocars Online** and click **Activate**

### Method 3: FTP Upload

1. Extract the zip file
2. Upload via FTP to `/wp-content/plugins/gocars-online/`
3. Set proper permissions (755 for directories, 644 for files)
4. Activate from WordPress admin

---

## ⚙️ Configuration

### Initial Setup

After activation, configure the plugin:

1. Go to **Gocars Online** in WordPress admin menu
2. Navigate to **Settings** submenu
3. Review current configuration status
4. (Optional) Add custom credentials for this domain

### Required Information

You'll need from your Gocars backend:

-   **Domain Slug** - Your subdomain (e.g., `yourcompany` from `yourcompany.gocars.gr`)
-   **Online Admin Link** - URL to your Gocars admin panel
-   **Language ID** - Default language for this installation

### Creating Your First Shortcode

1. Go to **Gocars Online → Add New**
2. Enter a title (e.g., "Homepage Search Form")
3. Configure:
    - **Gocars Display** - Choose shortcode type (Search Form, Fleet, Terms)
    - **Domain** - Your Gocars subdomain
    - **Online Admin Link** - Your admin panel URL
4. Customize appearance in the Search Form Settings or Fleet Settings tabs
5. Click **Publish**
6. Copy the generated shortcode
7. Paste it into any page or post

---

## 🔐 Credential Management

Gocars Online uses a multi-tier credential system for maximum flexibility and security.

### Credential Priority (Highest to Lowest)

| Priority | Method                              | Use Case                                |
| -------- | ----------------------------------- | --------------------------------------- |
| 1        | **WordPress Options** ⭐            | Recommended for production              |
| 2        | **.env File** 🔧                    | Recommended for development             |
| 3        | **Server Environment Variables** 🖥️ | Recommended for enterprise              |
| 4        | **Legacy Embedded Credentials** ⚠️  | Deprecated, backward compatibility only |

### Configuration Methods

#### Method 1: WordPress Options (Recommended)

Go to **Gocars Online → Settings**:

-   **GitHub Token:** `github_pat_...`
-   **Discord Webhook ID:** `1234567890`
-   **Discord Webhook Token:** `abc123...`

**Pros:**

-   ✅ Easy to configure via admin interface
-   ✅ Domain-specific credentials
-   ✅ No code changes needed
-   ✅ Better security than embedded

**Use When:** Production sites, client installations

#### Method 2: .env File (Development)

Create `.env` file in plugin root:

```env
# GitHub Personal Access Token (Fine-grained, read-only)
AUTH_TOKEN_GITHUB=github_pat_YOUR_TOKEN_HERE

# Discord Webhook Configuration
DISCORD_WEBHOOK_ID=1377652001239990282
DISCORD_WEBHOOK_TOKEN=your_webhook_token_here
```

**Important:** Add `.env` to `.gitignore`!

```gitignore
.env
.env.*
```

**Pros:**

-   ✅ Perfect for local development
-   ✅ Easy to switch between environments
-   ✅ Not committed to version control

**Use When:** Development, staging environments

#### Method 3: Server Environment Variables (Enterprise)

**Apache (.htaccess):**

```apache
SetEnv AUTH_TOKEN_GITHUB "github_pat_YOUR_TOKEN"
SetEnv DISCORD_WEBHOOK_ID "1234567890"
SetEnv DISCORD_WEBHOOK_TOKEN "abc123..."
```

**Nginx:**

```nginx
fastcgi_param AUTH_TOKEN_GITHUB "github_pat_YOUR_TOKEN";
fastcgi_param DISCORD_WEBHOOK_ID "1234567890";
fastcgi_param DISCORD_WEBHOOK_TOKEN "abc123...";
```

**Pros:**

-   ✅ Most secure
-   ✅ Centralized management
-   ✅ No files to manage

**Use When:** Enterprise hosting, managed servers

#### Method 4: Legacy Embedded (Deprecated)

⚠️ **For backward compatibility only.** Do not use for new installations.

Credentials are base64-encoded in `inc/gocars-config.php`. This method:

-   ❌ Less secure (extractable from code)
-   ❌ Same credentials for all sites
-   ❌ Requires plugin update to change
-   ✅ Works immediately without configuration

**Migration:** Sites using this method will see a notice encouraging migration to WordPress Options.

### Creating GitHub Personal Access Token

Required for automatic updates from private repository.

1. Go to **GitHub Settings → Tokens**
2. Click **Generate new token → Fine-grained token**
3. Configure:
    - **Token name:** Gocars Plugin Updates - [Domain]
    - **Expiration:** 1 year (you'll get renewal reminder)
    - **Repository access:** Only select `go-creations/gocars-online`
    - **Permissions:**
        - Repository → **Contents:** Read-only
        - Repository → **Metadata:** Read-only
4. Click **Generate token**
5. Copy immediately (you won't see it again!)
6. Add to WordPress: **Gocars Online → Settings**

---

## 🌐 Domain Authorization

**New in v2.5.0:** Domain-based authorization for enhanced security and license management.

### How It Works

-   Plugin checks if current domain is in the allow-list
-   Allow-list is fetched from GitHub: `domains.json`
-   Unauthorized domains receive a notice and cannot receive updates
-   Updates are checked hourly and cached for 6 hours

### Domain Format

The `domains.json` file in the repository root:

```json
["website.gocreations.info", "client1.com", "client2.gr", "demo.gocars.online"]
```

**Format rules:**

-   One domain per line (as array elements)
-   Lowercase only
-   No `www.` prefix
-   No `http://` or `https://`
-   No trailing slashes
-   Subdomains allowed: `subdomain.domain.com`

### Adding a Domain

**For Developers:**

1. Edit `domains.json` in repository
2. Add new domain to the array
3. Commit and push to `main` branch
4. Domain is authorized within 6 hours (cache expiry)

**For Support Team:**

Send request with:

-   Client domain
-   Purchase confirmation / License key
-   Installation URL

### Troubleshooting Authorization

If a domain shows as "not authorized":

1. **Check spelling** - Must match exactly (case-insensitive)
2. **Remove www** - Use `domain.com` not `www.domain.com`
3. **Check cache** - Wait up to 6 hours or force refresh
4. **Verify token** - GitHub token must have access to private repo

**Force cache refresh:**

```
yoursite.com/wp-admin/plugins.php?gocars_clear_domain_cache=1
```

(Requires admin privileges)

### Error Messages

| Message                        | Meaning               | Solution                      |
| ------------------------------ | --------------------- | ----------------------------- |
| "GitHub token is required"     | No token configured   | Add token in Settings         |
| "Domain not authorized"        | Not in `domains.json` | Contact support to add domain |
| "Could not fetch domains.json" | GitHub API error      | Check token permissions       |

---

## 📝 Shortcodes

### Search Form

Display a booking search form:

```
[search_form id="123"]
```

**Parameters:**

-   `id` - Shortcode post ID (required)

**Features:**

-   Location selection (pickup/dropoff)
-   Date/time picker (desktop and mobile)
-   Age group selection
-   Vehicle type filter (optional)
-   Different dropoff location option
-   Responsive design

**Customization:**

-   Header text and colors
-   Body styling
-   Primary/alternative colors
-   Border display
-   Loading effects
-   Keypoints display

---

### Fleet Display

Show available vehicles:

```
[fleet id="123"]
[fleet id="123" number="6"]
[fleet id="123" vehicle="car"]
[fleet id="123" category="SUV"]
```

**Parameters:**

-   `id` - Shortcode post ID (required)
-   `number` - Max vehicles to display (optional)
-   `vehicle` - Filter by vehicle type: `car`, `moto`, `atv`, `scooter`, `buggy`, `bicycle` (optional)
-   `category` - Filter by category/model type (optional)
-   `slider` - Display as slider: `true`/`false` (optional)

**Display Options:**

-   Grid or slider layout
-   Sorting: Price, Name, Category
-   Show/hide: Images, description, features, pricing
-   Custom button text and styling
-   Vehicle type icons

---

### Terms & Conditions

Display rental terms:

```
[terms id="123"]
```

**Parameters:**

-   `id` - Shortcode post ID (required)

**Features:**

-   Multi-language support
-   HTML formatting support
-   Customizable styling

---

## 🔄 Automatic Updates

### How Updates Work

1. **Check Frequency:** Every hour via WordPress cron
2. **Update Source:** Private GitHub repository
3. **Authorization:** Domain must be in allow-list
4. **Delivery:** Standard WordPress update interface

### Manual Update Check

Force immediate update check:

-   **WordPress Admin → Plugins → Check for updates**

Or via URL:

```
yoursite.com/wp-admin/plugins.php?puc_check_for_updates=1&puc_slug=gocars-online
```

### Update Notifications

You'll receive notifications:

-   **Admin Dashboard** - Update available notice
-   **Discord** (if configured) - Update notifications
-   **Error Log** - Any update failures

### What Gets Updated

| Updated                    | Preserved                   |
| -------------------------- | --------------------------- |
| ✅ Plugin core files       | ❌ Your custom settings     |
| ✅ Template files          | ❌ Shortcode configurations |
| ✅ JavaScript/CSS assets   | ❌ .env file (ignored)      |
| ✅ Configuration structure |                             |

### Automatic Data Sync

**Separate from plugin updates!**

-   **Frequency:** Every hour
-   **What syncs:**
    -   Vehicle inventory
    -   Location data
    -   Pricing information
    -   Language translations
    -   Terms & conditions
    -   Options/settings

### Preventing Updates

To temporarily disable updates:

```php
// Add to wp-config.php
define('AUTOMATIC_UPDATER_DISABLED', true);
```

Or filter specific plugin:

```php
add_filter('auto_update_plugin', function($update, $item) {
    if ($item->slug === 'gocars-online') {
        return false;
    }
    return $update;
}, 10, 2);
```

---

## 🔄 Migration Guide

### For Existing Installations (v2.4.x → v2.5.0)

If you're upgrading from v2.4.x or earlier:

#### What Changed

-   ✅ New credential management system
-   ✅ Domain authorization added
-   ✅ WordPress options support
-   ⚠️ Embedded credentials now deprecated (but still work)

#### Action Required

**Option 1: Continue Using Embedded Credentials (Easiest)**

Do nothing! Your site will continue working normally. You'll see a deprecation notice in Settings, but functionality is unchanged.

**Option 2: Migrate to WordPress Options (Recommended)**

1. Go to **Gocars Online → Settings**
2. (Optional) Create your own GitHub fine-grained token
3. Enter credentials in the form
4. Click **Save Custom Credentials**
5. Verify status shows "WordPress Options" instead of "Legacy Embedded"

#### Benefits of Migrating

-   ✅ Better security (domain-specific credentials)
-   ✅ Isolated GitHub rate limits (5000 req/hour per token)
-   ✅ Custom Discord notifications
-   ✅ Easier credential rotation
-   ✅ No code changes needed for updates

#### Timeline

-   **Now - Month 6:** Embedded credentials fully supported
-   **Month 6 - Month 12:** Deprecation warnings in admin
-   **Month 12+:** Embedded credentials may be removed (advance notice provided)

---

### For Fresh Installations (v2.5.0+)

Recommended configuration method:

1. **Development:** Use `.env` file
2. **Production:** Use WordPress Options
3. **Enterprise:** Use server environment variables

**Never** rely on embedded credentials for new installations.

---

## 🐛 Troubleshooting

### Common Issues

#### "Could not determine if updates are available"

**Possible causes:**

1. No GitHub token configured
2. Invalid/expired GitHub token
3. Domain not in allow-list
4. Repository access denied

**Solutions:**

1. Check: **Gocars Online → Settings** → Verify token is set
2. Create new token with proper permissions (see [Creating GitHub Token](#creating-github-personal-access-token))
3. Contact support to add domain to `domains.json`
4. Verify token has access to `go-creations/gocars-online` repo

---

#### "This domain is not authorized for automatic updates"

**Cause:** Domain not in `domains.json` allow-list

**Solution:**

1. Verify domain spelling matches exactly
2. Contact support with:
    - Full domain (e.g., `yoursite.com`)
    - Purchase/license information
    - Installation URL
3. Wait 6 hours after addition (cache expiry)
4. Force refresh: `?gocars_clear_domain_cache=1` (admin only)

---

#### Shortcode displays but no vehicles

**Checklist:**

1. ✅ Domain configured correctly?
2. ✅ Backend API accessible? (Test: visit `https://DOMAIN.gocars.gr/online-admin/`)
3. ✅ Vehicles exist in backend?
4. ✅ Language ID correct?
5. ✅ Data sync completed? (Check: last update timestamp)

**Force data refresh:** Visit any shortcode edit page and click "Update"

---

#### Discord notifications not working

**Checklist:**

-   Webhook ID and Token configured?
-   Webhook still active in Discord?
-   Check **Discord server settings → Integrations → Webhooks**

**Test webhook manually:**

```bash
curl -X POST https://discord.com/api/webhooks/YOUR_ID/YOUR_TOKEN \
  -H "Content-Type: application/json" \
  -d '{"content":"Test from Gocars"}'
```

---

#### Styling issues / CSS conflicts

**Common causes:**

-   Theme CSS overriding plugin styles
-   Page builder conflicts
-   Caching plugins

**Solutions:**

-   Clear all caches (plugin, theme, CDN)
-   Test with default WordPress theme
-   Check browser console for errors
-   Add custom CSS in Advanced settings:

```css
/* Increase specificity */
.gocars-search-form .your-element {
    /* your fixes */
}
```

---

#### Multi-language not working

**Checklist:**

-   WPML/Polylang installed and active?
-   Languages configured in backend?
-   Language ID in shortcode settings matches backend?
-   Browser locale detection enabled?

**Debug:**

```php
// Check detected language
var_dump(get_locale());      // Should show: en_US, el, de_DE, etc.
var_dump(ICL_LANGUAGE_CODE); // WPML
```

---

### Debug Mode

Enable WordPress debug logging:

```php
// Add to wp-config.php
define('WP_DEBUG', true);
define('WP_DEBUG_LOG', true);
define('WP_DEBUG_DISPLAY', false);
```

Check logs at: `/wp-content/debug.log`  
Look for lines starting with `Gocars:`

---

### Performance Issues

**Symptoms:** Slow page load, high server CPU, timeout errors

**Optimization:**

-   Enable caching (automatic; verify in Settings → Advanced → Data Sync Status)
-   Reduce update frequency (add to `functions.php`):

```php
add_filter('cron_schedules', function($schedules) {
    $schedules['gocars_custom'] = array(
        'interval' => 86400, // 24 hours
        'display'  => 'Once Daily'
    );
    return $schedules;
});
```

-   Optimize images: WebP format, resize to max display size, lazy loading
-   Database cleanup: Remove old post revisions, optimize tables

---

## 📞 Support

### Before Contacting Support

Please gather:

-   WordPress version
-   PHP version
-   Active theme and plugins
-   Error messages (exact text)
-   Steps to reproduce issue
-   Screenshots if relevant

### Support Channels

| Channel               | Details                                      |
| --------------------- | -------------------------------------------- |
| **Email**             | support@gocars.online                        |
| **Response Time**     | 24-48 hours (business days)                  |
| **Emergency Support** | For critical production issues only          |
| **Discord Community** | General questions, feature requests, updates |

### Feature Requests

We welcome suggestions! Please include:

-   Use case / problem to solve
-   Proposed solution
-   Business impact
-   Willingness to beta test

---

## 📋 System Requirements

### Minimum Requirements

| Requirement | Version                  |
| ----------- | ------------------------ |
| WordPress   | 5.0+                     |
| PHP         | 7.4+                     |
| MySQL       | 5.6+ or MariaDB 10.0+    |
| Memory      | 64MB (128MB recommended) |
| Disk Space  | 10MB                     |

### Recommended Environment

| Requirement | Version                 |
| ----------- | ----------------------- |
| WordPress   | Latest version          |
| PHP         | 8.1+                    |
| MySQL       | 8.0+ or MariaDB 10.6+   |
| Memory      | 256MB                   |
| HTTPS       | Required for production |

### Server Requirements

-   **cURL** - Enabled (for API calls)
-   **JSON** - Extension enabled
-   **Mbstring** - Extension enabled
-   **WordPress Cron** - Enabled (for automatic updates)

### Compatible Hosting

Tested and verified on:

-   ✅ SiteGround
-   ✅ WP Engine
-   ✅ Kinsta
-   ✅ Cloudways
-   ✅ Bluehost
-   ✅ HostGator

---

## 📊 Changelog

### Version 2.5.0 (2024-02-10)

**New Features:**

-   ✨ Multi-tier credential management system
-   ✨ Domain-based authorization for updates
-   ✨ WordPress Options support for credentials
-   ✨ Migration path from embedded credentials
-   ✨ Enhanced security with fine-grained GitHub tokens
-   ✨ Domain allow-list system via domains.json

**Improvements:**

-   ⚡ Credential source tracking and logging
-   ⚡ Automatic cache refresh on plugin update
-   ⚡ Better error messages and admin notices
-   ⚡ Settings page for credential management
-   ⚡ Deprecation warnings for legacy credentials

**Changes:**

-   🔧 Embedded credentials now deprecated (backward compatible)
-   🔧 GitHub token now required for all update operations
-   🔧 Domain authorization required for automatic updates

**Security:**

-   🔒 Base64 obfuscation for legacy credentials
-   🔒 Domain-specific credential isolation
-   🔒 Fine-grained GitHub token support
-   🔒 Credential source auditing

---

### Version 2.4.0 (Previous)

**Features:**

-   Search form shortcode
-   Fleet display shortcode
-   Terms & conditions shortcode
-   Multi-language support (EN, EL, DE, IT)
-   Automatic backend synchronization
-   Discord notifications
-   GitHub-based updates

---

## 📄 License

### Proprietary License

**Copyright © 2024 Alexis Tarantos / Go Creations**

This software is proprietary and confidential. Unauthorized copying, distribution, modification, or use is strictly prohibited.

**Permitted Use:**

-   Installation on authorized domains only
-   Use as per license agreement
-   Updates via official channels

**Prohibited:**

-   Redistribution
-   Modification for resale
-   Reverse engineering
-   Use on unauthorized domains

For licensing inquiries: support@gocars.online

---

## 🙏 Credits

-   **Developed by:** Alexis Tarantos
-   **Company:** Go Creations
-   **Website:** https://gocars.online

**Third-Party Libraries:**

-   Plugin Update Checker by Yahnis Elsts
-   jQuery UI
-   Select2
-   Swiper.js
-   Mobiscroll (date picker)

---

**Last Updated:** February 10, 2024  
**Plugin Version:** 2.5.0  
**Documentation Version:** 1.0

_Made with ❤️ by Go Creations_
