VendorHive Documentation

📋 Introduction

What is VendorHive and what does it offer?

VendorHive is a production-ready, reusable Laravel package that adds a complete multi-vendor marketplace to any Laravel application. Install it via Composer and you instantly get:

⚙️ Requirements

System requirements before installing VendorHive.

📦 Installation

Step-by-step guide to install VendorHive in your Laravel project.

composer require gambolthemes/vendorhive

// composer.json (your Laravel project)
{
    "repositories": [
        {
            "type": "path",
            "url": "../VendorHive"
        }
    ]
}

composer require gambolthemes/vendorhive:@dev

php artisan vendor:publish --tag=vendorhive-config

php artisan make:migration add_role_to_users_table --table=users

public function up(): void
{
    Schema::table('users', function (Blueprint $table) {
        $table->enum('role', ['admin', 'vendor', 'customer'])
              ->default('customer')
              ->after('email');
        $table->string('phone')->nullable()->after('role');
    });
}

public function down(): void
{
    Schema::table('users', function (Blueprint $table) {
        $table->dropColumn(['role', 'phone']);
    });
}

namespace App\Models;

use Gambolthemes\VendorHive\Traits\VendorHiveUser;
use Illuminate\Foundation\Auth\User as Authenticatable;

class User extends Authenticatable
{
    use HasFactory, Notifiable, VendorHiveUser;

    protected $fillable = [
        'name', 'email', 'password', 'role', 'phone',
    ];
}

'user_model' => \App\Models\User::class,

php artisan migrate

# Create demo users (admin/vendor/customer with password: 12345678)
php artisan db:seed --class="Gambolthemes\VendorHive\Database\Seeders\AdminSeeder"

# Create 6 categories with 30 subcategories
php artisan db:seed --class="Gambolthemes\VendorHive\Database\Seeders\CategorySeeder"

# Create 23 default settings
php artisan db:seed --class="Gambolthemes\VendorHive\Database\Seeders\SettingSeeder"

// routes/web.php

// Remove or comment out this line:
// Route::get('/', function () { return view('welcome'); });

// VendorHive handles all routes via the package

php artisan serve

🚀 Quick Start (Copy & Paste)

All commands in one block — paste into your terminal:

# 1. Install package
composer require gambolthemes/vendorhive

# 2. Publish config
php artisan vendor:publish --tag=vendorhive-config

# 3. Create role migration
php artisan make:migration add_role_to_users_table --table=users
# ↑ Edit this migration (see Step 3 above), then:

# 4. Run migrations
php artisan migrate

# 5. Seed data
php artisan db:seed --class="Gambolthemes\VendorHive\Database\Seeders\AdminSeeder"
php artisan db:seed --class="Gambolthemes\VendorHive\Database\Seeders\CategorySeeder"
php artisan db:seed --class="Gambolthemes\VendorHive\Database\Seeders\SettingSeeder"

# 6. Start server
php artisan serve

💳 Payment Setup & QA

Recommended steps to configure gateways and quickly verify end-to-end payment flow.

🔧 Configuration

Full reference of all options in config/vendorhive.php

Middleware Configuration

'middleware' => [
    'web'      => ['web'],
    'auth'     => ['web', 'auth'],
    'admin'    => ['web', 'auth', 'vendorhive.admin'],
    'vendor'   => ['web', 'auth', 'vendorhive.vendor'],
    'customer' => ['web', 'auth', 'vendorhive.customer'],
    'guest'    => ['web', 'guest'],
    'api'      => ['api'],
],

👤 User Model Setup

How to integrate VendorHive with your existing User model.

The VendorHiveUser Trait

The VendorHiveUser trait adds role helpers and marketplace relationships to your User model:

User Roles

VendorHive uses 3 roles stored in the role column of the users table:

🛡️ Middleware

VendorHive registers 3 middleware aliases automatically.

🏢 Admin Panel

All admin features accessible at /admin/dashboard

Admin URLs

🏪 Vendor Panel

Vendor dashboard accessible at /vendor/dashboard

Vendor Registration Flow

1. User visits /vendor/register and fills the registration form
2. If vendor_auto_approve is false (default), vendor status is set to pending
3. Vendor sees the /vendor/pending page until admin approves
4. Admin approves from /admin/vendors → vendor can now access dashboard

Vendor URLs

🛍️ Frontend / Storefront

Customer-facing pages.

Public URLs (No Login Required)

Customer URLs (Login Required)

📊 Models Reference

15 Eloquent models included in the package.

Using Models in Your Code

use Gambolthemes\VendorHive\Models\Product;
use Gambolthemes\VendorHive\Models\Category;
use Gambolthemes\VendorHive\Models\Order;
use Gambolthemes\VendorHive\Models\Vendor;

// Get all active products
$products = Product::active()->get();

// Get featured products
$featured = Product::featured()->take(8)->get();

// Get active categories with children
$categories = Category::active()->parents()->with('children')->get();

// Check if a user is a vendor
if ($user->isVendor()) {
    $shop = $user->vendor->shop;
}

🌱 Seeders

3 built-in seeders to bootstrap your marketplace data.

php artisan db:seed --class="Gambolthemes\VendorHive\Database\Seeders\AdminSeeder"

php artisan db:seed --class="Gambolthemes\VendorHive\Database\Seeders\CategorySeeder"

php artisan db:seed --class="Gambolthemes\VendorHive\Database\Seeders\SettingSeeder"

🔀 Routes Reference

All 105+ web routes registered by VendorHive. All route names use the vendorhive. prefix.

Public Routes

Cart Routes

Authentication Routes

Customer Routes (requires login + customer role)

Vendor Routes (requires login + vendor role + approved)

Admin Routes (requires login + admin role)

Admin has 40+ routes for dashboard, vendors, products, categories, orders, coupons, pages, settings, withdrawals, and reports. All prefixed with /admin/ and named vendorhive.admin.*.

See the Admin Panel section for all URLs.

🔌 REST API

Built-in API endpoints at /api/v1/vendorhive/

Public API Endpoints

Authenticated API Endpoints (requires auth:sanctum)

💰 Commission System

How VendorHive calculates and manages commissions.

Commission Rate Priority

1. Vendor-specific rate — set per vendor via admin panel (vendors.commission_rate column)
2. Database setting — Setting::getValue('global_commission_rate')
3. Config fallback — config('vendorhive.commission_percentage', 10)

How It Works

// Example: Product sold for $100, commission rate = 10%

Commission Amount = $100 × 10% = $10     // platform keeps
Vendor Earning    = $100 - $10  = $90     // vendor gets

// Commission record created automatically when order is placed
// Vendor balance updated when admin marks commission as completed

CommissionService Methods

Using CommissionService in Your Code

use Gambolthemes\VendorHive\Services\CommissionService;

$service = app(CommissionService::class);

// Calculate commission for a vendor on $100 order
$result = $service->calculate($vendor, 100.00);
// Returns: ['rate' => 10, 'commission' => 10.00, 'vendor_earning' => 90.00]

🧰 Helpers

Static helper methods available via VendorHiveHelper.

use Gambolthemes\VendorHive\Helpers\VendorHiveHelper;

Usage in Blade Views

{{-- Display formatted price --}}
{{ Gambolthemes\VendorHive\Helpers\VendorHiveHelper::formatPrice($product->price) }}

{{-- Get a setting --}}
{{ Gambolthemes\VendorHive\Helpers\VendorHiveHelper::setting('site_name', 'My Store') }}

🎨 Customization

How to customize views, layouts, and routes.

Custom Views (Override Blade Templates)

Publish views to override them in your app:

php artisan vendor:publish --tag=vendorhive-views

This copies all views to resources/views/vendor/vendorhive/. Edit files there — Laravel will use your overrides automatically.

Custom Layouts

Change the layout files used by VendorHive in config/vendorhive.php:

'layouts' => [
    'app'    => 'layouts.app',        // your app layout
    'admin'  => 'layouts.admin',      // your admin layout
    'vendor' => 'layouts.vendor',     // your vendor layout
],

Route Prefix

Serve VendorHive under a custom URL path:

// Serve marketplace under /marketplace/...
'route_prefix' => 'marketplace',

// Result: /marketplace/products, /marketplace/admin/dashboard, etc.

Currency

'currency'        => 'INR',
'currency_symbol' => '₹',

📤 Publishing Assets

VendorHive supports 4 publish tags for customization.

📁 File Structure

Complete package directory structure (133 files).

🔍 Troubleshooting

Common issues and their solutions.

// Laravel 11/12: bootstrap/providers.php
return [
    Gambolthemes\VendorHive\VendorHiveServiceProvider::class,
];

// Laravel 10: config/app.php → 'providers' array
Gambolthemes\VendorHive\VendorHiveServiceProvider::class,

php artisan config:clear
php artisan route:clear
php artisan view:clear
php artisan cache:clear
composer dump-autoload

🔑 Default Credentials

Login credentials created by the seeders.