Skip to content

Channels

Complete reference for the Channel model, sales channels, and multi-channel management in Shopper.

Channels represent different sales platforms where your products can be sold. Examples include your main website, mobile app, marketplace integrations, or physical stores.

Model

The model used is Shopper\Core\Models\Channel. It implements Shopper\Core\Models\Contracts\Channel and uses the HasSlug trait: the slug you set is converted with Str::slug() and gets a -1, -2 suffix when it is already taken. The slug is not generated from the name, so pass one when you create a channel. The model is configurable via config/shopper/models.php.

Extending the Model

To add custom behavior, extend the model and update your configuration:

namespace App\Models;

use Shopper\Core\Models\Channel as BaseChannel;

class Channel extends BaseChannel
{
}

Update config/shopper/models.php:

return [
    'channel' => \App\Models\Channel::class,
];

Database Schema

Channels are stored in the sh_channels table (sh_ is the default table prefix).

ColumnTypeNullableDefaultDescription
idbigintnoautoPrimary key
namestringno-Channel name
slugstringyesnullURL-friendly identifier (unique)
descriptiontextyesnullChannel description
timezonestringyesnullChannel timezone, stored for your own code (Shopper does not read it)
urlstringyesnullChannel URL
is_defaultbooleannofalseDefault channel flag
is_enabledbooleannofalseWhether the channel is active. Only enabled channels are listed in the admin product form
metadatajsonbyesnullAdditional custom data, cast to an array
created_attimestampyesnullCreation timestamp
updated_attimestampyesnullLast update timestamp

Relationships

Products

Channels have a many-to-many polymorphic relationship with products:

// Get all products for a channel
$channel->products; // Collection of Product models

// Add products to channel
$channel->products()->attach([$productId1, $productId2]);

// Remove products from channel
$channel->products()->detach($productId);

// Sync products
$channel->products()->sync($productIds);

Orders and Carts

Orders and carts store the channel they were placed on in a nullable channel_id column and expose a channel() relation. Deleting a channel sets this column to null. The Channel model has no inverse relation, so query orders by the column:

use Shopper\Core\Models\Order;

$order->channel; // Channel model or null

$mobileOrders = Order::query()
    ->where('channel_id', $mobileChannel->id)
    ->count();

Query Scopes

use Shopper\Core\Models\Channel;

// Get only the default channel
Channel::query()->default()->first();

// Get only enabled channels
Channel::query()->enabled()->get();

// Combine scopes
Channel::query()
    ->enabled()
    ->where('timezone', 'UTC')
    ->get();

Observer Behavior

The Shopper\Core\Observers\ChannelObserver ensures only one channel can be default:

// When creating/updating a channel with is_default = true:
// 1. Any existing default channel is set to is_default = false
// 2. The new/updated channel becomes the default

$channel = Channel::query()->create([
    'name' => 'Mobile App',
    'is_default' => true, // Previous default is automatically unset
]);

The previous default is updated with updateQuietly(), so no model events fire for it. The observer does not keep a default in place: setting is_default to false on the current default leaves the store without one.

Default Channel

When you accept the database step of php artisan shopper:install, the ChannelSeeder creates one channel named Web Store, with the slug web-store, the url from config('app.url'), enabled and marked as default.

You can retrieve the default channel using the default scope. It returns null when no channel is marked as default:

use Shopper\Core\Models\Channel;
use Shopper\Models\Product;

// Get the default channel
$channel = Channel::query()->default()->first();

// Use in controllers
public function index()
{
    $channel = Channel::query()->default()->first();

    $products = Product::query()
        ->forChannel($channel->id)
        ->publish()
        ->get();
}

Creating Channels

The 2.x admin panel has no page to manage channels: create them in code, for example in a seeder. is_enabled defaults to false, so pass 'is_enabled' => true for a channel you want to pick in the admin product form.

Default Website Channel

Creating a channel with 'is_default' => true removes the flag from the current default, such as the seeded Web Store channel.

use Shopper\Core\Models\Channel;

$channel = Channel::query()->create([
    'name' => 'Website',
    'slug' => 'website',
    'description' => 'Main e-commerce website',
    'url' => config('app.url'),
    'timezone' => config('app.timezone'),
    'is_default' => true,
    'is_enabled' => true,
]);

Additional Channels

// Mobile app channel
$mobileChannel = Channel::query()->create([
    'name' => 'Mobile App',
    'slug' => 'mobile-app',
    'description' => 'iOS and Android mobile application',
    'timezone' => 'UTC',
    'is_enabled' => true,
]);

// Marketplace channel
$marketplaceChannel = Channel::query()->create([
    'name' => 'Amazon',
    'slug' => 'amazon',
    'description' => 'Amazon marketplace integration',
    'url' => 'https://amazon.com/store/your-store',
    'is_enabled' => true,
    'metadata' => [
        'marketplace_id' => 'ATVPDKIKX0DER',
        'seller_id' => 'A1234567890',
    ],
]);

Retrieving Channels

use Shopper\Core\Models\Channel;

// Get all enabled channels
$channels = Channel::query()->enabled()->get();

// Get default channel
$default = Channel::query()->default()->first();

// Get channel by slug
$channel = Channel::query()
    ->where('slug', 'website')
    ->first();

// Get channel by slug, throws ModelNotFoundException when none matches
$channel = Channel::findBySlug('website');

// Get channel with products
$channel = Channel::query()
    ->with('products')
    ->where('slug', 'mobile-app')
    ->first();

// Get channels with product counts
$channels = Channel::query()
    ->enabled()
    ->withCount('products')
    ->get();

Assigning Products to Channels

use Shopper\Models\Product;

$product = Product::query()->find($id);

// Assign to channels (via product)
$product->channels()->attach([$channelId1, $channelId2]);

// Get products for a specific channel
$products = Product::query()
    ->forChannel($channelId)
    ->publish()
    ->get();

// Get products assigned to at least one of these channels
$products = Product::query()
    ->forChannel([$channelId1, $channelId2])
    ->publish()
    ->get();

Storefront Example

namespace App\Http\Controllers;

use Shopper\Core\Models\Channel;
use Shopper\Models\Product;

class ProductController extends Controller
{
    public function index()
    {
        // Get products for default channel
        $channel = Channel::query()->default()->first();

        $products = Product::query()
            ->forChannel($channel->id)
            ->publish()
            ->with(['brand', 'categories'])
            ->paginate(12);

        return view('products.index', compact('products'));
    }
}

Multi-Channel API

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use Illuminate\Http\Request;
use Shopper\Core\Models\Channel;
use Shopper\Models\Product;

class ProductController extends Controller
{
    public function index(Request $request)
    {
        $channelSlug = $request->header('X-Channel', 'website');

        $channel = Channel::query()
            ->where('slug', $channelSlug)
            ->enabled()
            ->firstOrFail();

        $products = Product::query()
            ->forChannel($channel->id)
            ->publish()
            ->paginate(20);

        return response()->json($products);
    }
}

Use Cases

ChannelExample Use
WebsiteMain e-commerce storefront
Mobile AppiOS/Android application
MarketplaceAmazon, eBay, Etsy integration
POSPhysical store point of sale
WholesaleB2B customer portal
SocialFacebook/Instagram shop

Best Practices

  1. Default Channel: Always have one default channel for fallback
  2. Product Assignment: Assign products to relevant channels during creation
  3. Timezone: Shopper stores timezone but does not read it: use it in your own code (for example to show order dates in the channel's timezone)
  4. Metadata: Use metadata for channel-specific configuration (marketplace or seller IDs). Keep secrets such as API keys in .env, not in a database column
// Example: Channel-specific settings
$channel = Channel::query()->find($id);
$marketplaceId = $channel->metadata['marketplace_id'] ?? null;
$sellerId = $channel->metadata['seller_id'] ?? null;

Last updated on

Edit on GitHub