Customers

Customers are users who have the customer role and can place orders in your store. Shopper extends your Laravel User model with e-commerce specific fields and relationships.

User Model Integration

Shopper doesn’t create a separate Customer model. Instead, it extends your existing App\Models\User model with the InteractsWithShopper trait and ShopperUser contract.

namespace App\Models;

use Illuminate\Foundation\Auth\User as Authenticatable;
use Shopper\Models\Contracts\ShopperUser;
use Shopper\Traits\InteractsWithShopper;

class User extends Authenticatable implements ShopperUser
{
    use InteractsWithShopper;
}

The InteractsWithShopper trait provides:

HasRoles (Spatie Permission) for role-based access control
HasDiscounts for customer-specific discount eligibility
HasProfilePhoto for avatar management

Database Schema

User Table Modifications

Shopper modifies the standard Laravel users table:

Column	Type	Nullable	Default	Description
`id`	bigint	no	auto	Primary key
`first_name`	string	yes	null	First name
`last_name`	string	no	-	Last name
`email`	string	no	-	Email address (unique)
`password`	string	yes	null	Password (nullable for social auth)
`email_verified_at`	timestamp	yes	null	Email verification date
`gender`	string	yes	null	Gender enum value
`phone_number`	string	yes	null	Phone number
`birth_date`	date	yes	null	Birth date
`avatar_type`	string	no	avatar_ui	Avatar source type
`avatar_location`	string	yes	null	Avatar file path
`timezone`	string	yes	null	User timezone
`opt_in`	boolean	no	false	Marketing email consent
`last_login_at`	timestamp	yes	null	Last login timestamp
`last_login_ip`	string	yes	null	Last login IP address

Address Table

Column	Type	Nullable	Default	Description
`id`	bigint	no	auto	Primary key
`first_name`	string	no	-	First name
`last_name`	string	no	-	Last name
`company_name`	string	yes	null	Company name
`street_address`	string	no	-	Street address
`street_address_plus`	string	yes	null	Additional address line
`postal_code`	string	no	-	Postal/ZIP code
`city`	string	no	-	City
`state`	string	yes	null	State/province/region
`phone_number`	string	yes	null	Phone number
`shipping_default`	boolean	no	false	Default shipping address
`billing_default`	boolean	no	false	Default billing address
`type`	string	yes	null	Address type enum
`country_id`	bigint	yes	null	FK to countries
`user_id`	bigint	no	-	FK to users

Gender Type

The GenderType enum defines available gender options:

use Shopper\Core\Enum\GenderType;

GenderType::Male    // male
GenderType::Female  // female

Address Type

The AddressType enum defines address categories:

use Shopper\Core\Enum\AddressType;

AddressType::Billing   // billing
AddressType::Shipping  // shipping

Relationships

Orders

// Get all customer orders
$customer->orders; // Collection of Order models

// Get recent orders
$customer->orders()
    ->latest()
    ->take(5)
    ->get();

Addresses

// Get all customer addresses
$customer->addresses; // Collection of Address models

// Get default shipping address
$customer->addresses()
    ->where('shipping_default', true)
    ->first();

// Get default billing address
$customer->addresses()
    ->where('billing_default', true)
    ->first();

Query Scopes

use App\Models\User;

// Get only customers (users with 'user' role)
User::query()->customers()->get();

// Get administrators (admin or manager roles)
User::query()->administrators()->get();

Role Checking

// Check if user is an admin
$user->isAdmin();

// Check if user is a manager
$user->isManager();

// Check if email is verified
$user->isVerified();

Computed Attributes

// Get full name
$customer->full_name; // "John Doe"

// Get formatted birth date
$customer->birth_date_formatted; // "15, January 1990"

// Get roles as comma-separated string
$customer->roles_label; // "User, VIP"

// Get profile picture URL
$customer->picture; // Avatar URL (ui-avatars or uploaded)

Address Model

The model used is Shopper\Core\Models\Address. It implements Shopper\Core\Models\Contracts\Address and is configurable via config/shopper/models.php.

Extending the Address Model

namespace App\Models;

use Shopper\Core\Models\Address as BaseAddress;

class Address extends BaseAddress
{
    // Add your customizations here
}

Update config/shopper/models.php:

return [
    'address' => \App\Models\Address::class,
];

Address Relationships

Each address belongs to a user and optionally to a country:

$address->user;    // The customer who owns this address
$address->country; // The Country model (nullable)

Address Methods

The Address model provides helpers for checking default status:

$address->isShippingDefault(); // true if this is the default shipping address
$address->isBillingDefault();  // true if this is the default billing address
$address->full_name;           // "John Doe" (computed from first_name + last_name)

Creating Customers

Basic Customer

use App\Models\User;
use Shopper\Core\Enum\GenderType;
use Illuminate\Support\Facades\Hash;

$customer = User::query()->create([
    'first_name' => 'John',
    'last_name' => 'Doe',
    'email' => 'john@example.com',
    'password' => Hash::make('password'),
    'gender' => GenderType::Male,
    'email_verified_at' => now(),
]);

// Assign customer role
$customer->assignRole(config('shopper.admin.roles.user'));

Customer with Address

use Shopper\Core\Models\Address;
use Shopper\Core\Enum\AddressType;

$customer = User::query()->create([
    'first_name' => 'Jane',
    'last_name' => 'Doe',
    'email' => 'jane@example.com',
    'gender' => GenderType::Female,
    'phone_number' => '+1234567890',
    'opt_in' => true,
]);

$customer->assignRole(config('shopper.admin.roles.user'));

// Add shipping address
$customer->addresses()->create([
    'first_name' => 'Jane',
    'last_name' => 'Doe',
    'street_address' => '123 Main Street',
    'city' => 'New York',
    'postal_code' => '10001',
    'country_id' => $countryId,
    'type' => AddressType::Shipping,
    'shipping_default' => true,
]);

Retrieving Customers

use App\Models\User;

// Get all customers
$customers = User::query()
    ->customers()
    ->latest()
    ->get();

// Search customers
$customers = User::query()
    ->customers()
    ->where(function ($query) use ($search) {
        $query->where('first_name', 'like', "%{$search}%")
            ->orWhere('last_name', 'like', "%{$search}%")
            ->orWhere('email', 'like', "%{$search}%");
    })
    ->get();

// Get customer with addresses and orders
$customer = User::query()
    ->with(['addresses', 'orders'])
    ->findOrFail($id);

// Get customers who opted in for marketing
$marketingList = User::query()
    ->customers()
    ->where('opt_in', true)
    ->get();

// Get verified customers only
$verified = User::query()
    ->customers()
    ->whereNotNull('email_verified_at')
    ->get();

Managing Addresses

use Shopper\Core\Models\Address;

// Create address for customer
$address = Address::query()->create([
    'user_id' => $customer->id,
    'first_name' => 'John',
    'last_name' => 'Doe',
    'street_address' => '456 Oak Avenue',
    'city' => 'Los Angeles',
    'postal_code' => '90001',
    'country_id' => $countryId,
    'type' => AddressType::Billing,
    'billing_default' => true,
]);

// Update default address
Address::query()
    ->where('user_id', $customer->id)
    ->where('type', AddressType::Shipping)
    ->update(['shipping_default' => false]);

$newDefault = Address::query()->find($addressId);
$newDefault->update(['shipping_default' => true]);

Observer Behavior

When a user is deleted, the InteractsWithShopper trait automatically:

Detaches all roles
Deletes all addresses

// When deleting a user:
$customer->delete();
// Roles are detached and addresses are deleted automatically

Role Configuration

Roles are defined in config/shopper/admin.php:

return [
    'roles' => [
        'admin' => 'administrator',
        'manager' => 'manager',
        'user' => 'user',
    ],
];

Permissions

The admin panel generates five permissions for customer management:

Permission	Description
`browse_customers`	View the customers list
`read_customers`	View a single customer profile
`add_customers`	Create new customers
`edit_customers`	Edit customer profiles
`delete_customers`	Delete or anonymize customers

Components

To customize the admin UI for customer management:

php artisan shopper:component:publish customer

Creates config/shopper/components/customer.php:

use Shopper\Livewire;
use Shopper\Livewire\Components;

return [
    'pages' => [
        'customer-index' => Livewire\Pages\Customers\Index::class,
        'customer-create' => Livewire\Pages\Customers\Create::class,
        'customer-show' => Livewire\Pages\Customers\Show::class,
    ],
    'components' => [
        'customers.addresses' => Components\Customers\Addresses::class,
        'customers.orders' => Components\Customers\Orders::class,
        'customers.profile' => Components\Customers\Profile::class,
    ],
];

Storefront Example

namespace App\Http\Controllers;

use App\Models\User;
use Shopper\Core\Models\Address;
use Shopper\Core\Enum\GenderType;
use Shopper\Core\Enum\AddressType;
use Illuminate\Support\Facades\Hash;

class AccountController extends Controller
{
    public function show()
    {
        $customer = auth()->user();

        return view('account.show', [
            'customer' => $customer,
            'orders' => $customer->orders()->latest()->paginate(10),
            'addresses' => $customer->addresses,
        ]);
    }

    public function updateProfile(Request $request)
    {
        $validated = $request->validate([
            'first_name' => 'required|string|max:255',
            'last_name' => 'required|string|max:255',
            'phone_number' => 'nullable|string|max:20',
            'birth_date' => 'nullable|date',
            'opt_in' => 'boolean',
        ]);

        auth()->user()->update($validated);

        return back()->with('success', 'Profile updated successfully');
    }

    public function storeAddress(Request $request)
    {
        $validated = $request->validate([
            'first_name' => 'required|string',
            'last_name' => 'required|string',
            'street_address' => 'required|string',
            'city' => 'required|string',
            'postal_code' => 'required|string',
            'country_id' => 'required|exists:countries,id',
            'type' => 'required|in:billing,shipping',
        ]);

        auth()->user()->addresses()->create([
            ...$validated,
            'type' => AddressType::from($validated['type']),
        ]);

        return back()->with('success', 'Address added successfully');
    }
}

Use Cases

Scope	Description
`customers()`	Users with ‘user’ role
`administrators()`	Users with ‘admin’ or ‘manager’ role

Method	Description
`isAdmin()`	Check if user has admin role
`isManager()`	Check if user has manager role
`isVerified()`	Check if email is verified

Prologue

Getting Started

Catalog

Sales

Store Setup

System

Storefront

Releases

User Model Integration

Database Schema

User Table Modifications

Address Table

Gender Type

Address Type

Relationships

Orders

Addresses

Query Scopes

Role Checking

Computed Attributes

Address Model

Extending the Address Model

Address Relationships

Address Methods

Creating Customers

Basic Customer

Customer with Address

Retrieving Customers

Managing Addresses

Observer Behavior

Role Configuration

Permissions

Components

Storefront Example

Use Cases

Prologue

Getting Started

Catalog

Sales

Store Setup

System

Storefront

Releases

​User Model Integration

​Database Schema

​User Table Modifications

​Address Table

​Gender Type

​Address Type

​Relationships

​Orders

​Addresses

​Query Scopes

​Role Checking

​Computed Attributes

​Address Model

​Extending the Address Model

​Address Relationships

​Address Methods

​Creating Customers

​Basic Customer

​Customer with Address

​Retrieving Customers

​Managing Addresses

​Observer Behavior

​Role Configuration

​Permissions

​Components

​Storefront Example

​Use Cases

User Model Integration

Database Schema

User Table Modifications

Address Table

Gender Type

Address Type

Relationships

Orders

Addresses

Query Scopes

Role Checking

Computed Attributes

Address Model

Extending the Address Model

Address Relationships

Address Methods

Creating Customers

Basic Customer

Customer with Address

Retrieving Customers

Managing Addresses

Observer Behavior

Role Configuration

Permissions

Components

Storefront Example

Use Cases