Customer Model and Data Structure

Purpose and Scope

This document details the ShopCustomer model, which represents customer accounts in the GP247/Shop e-commerce system. It covers the database schema, model relationships, customer lifecycle operations, email verification system, and integration with authentication and custom fields.

For information about customer authentication and login flows, see Customer Authentication. For administrative customer management interfaces, see Customer Administration. For customer API endpoints, see Customer API.

Database Table Structure

The customer data is stored in the shop_customer table with the following structure:

Column	Type	Purpose
id	varchar/uuid	Primary key, auto-generated with 'CUS' prefix
first_name	varchar	Customer's first name
last_name	varchar	Customer's last name
email	varchar	Email address (unique, used for authentication)
password	varchar	Hashed password
phone	varchar	Contact phone number
address_id	integer	Foreign key to default address in shop_customer_address
email_verified_at	timestamp	Timestamp when email was verified (null if unverified)
remember_token	varchar	Laravel authentication remember token
store_id	integer	Store isolation for multi-store architecture
status	integer	Account status (active/inactive)
created_at	timestamp	Account creation timestamp
updated_at	timestamp	Last modification timestamp

The customer model is store-scoped, meaning each customer record belongs to a specific store instance, enabling multi-vendor isolation.

Sources: src/Models/ShopCustomer.php25-27

Model Architecture and Core Components

Class Definition and Inheritance

The ShopCustomer model extends Laravel's Authenticatable base class, providing full authentication capabilities including login, logout, remember me functionality, and password reset flows. It incorporates five traits that extend functionality:

• ModelTrait: Provides common query builder methods and multi-store filtering
• UuidTrait: Enables UUID-based primary key generation with custom prefixes
• SocialAccountTrait: Adds social login capabilities (Google, Facebook, etc.)
• Notifiable: Enables Laravel notification system for emails
• HasApiTokens: Provides Sanctum-based API token authentication

Sources: src/Models/ShopCustomer.php12-17

Protected and Computed Attributes

The model defines several attribute protection and computation rules:

The name accessor automatically concatenates first_name and last_name to provide a full name attribute src/Models/ShopCustomer.php64-67 This computed attribute is automatically appended to JSON serialization src/Models/ShopCustomer.php37-39

Sources: src/Models/ShopCustomer.php26-67

Customer Relationships

Entity Relationship Diagram

Orders Relationship

The orders() relationship provides access to all orders placed by the customer:

This one-to-many relationship links customers to their purchase history src/Models/ShopCustomer.php40-43

Addresses Relationship

The addresses() relationship manages multiple shipping and billing addresses:

Customers can maintain multiple addresses, with one designated as the default via the address_id column src/Models/ShopCustomer.php45-48 The getAddressDefault() method retrieves the default address src/Models/ShopCustomer.php149-154

Sources: src/Models/ShopCustomer.php40-154

Customer Lifecycle Operations

Customer Creation Flow

The createCustomer() static method orchestrates customer account creation src/Models/ShopCustomer.php121-142:

1. Data Sanitization: Input data is cleaned using gp247_clean() to prevent XSS and SQL injection
2. UUID Generation: During model creation, the UuidTrait::creating() hook generates a unique ID with 'CUS' prefix using gp247_generate_id('CUS') src/Models/ShopCustomer.php88-92
3. Address Mapping: Customer address fields are extracted using gp247_customer_address_mapping()
4. Record Creation: The customer record is inserted into the database
5. Default Address: A new ShopCustomerAddress is created and linked as the default address
6. Custom Fields: Any custom field values are inserted via gp247_custom_field_update()
7. Event Trigger: The gp247_event_customer_created() function is called to trigger post-creation hooks (e.g., welcome emails)

Sources: src/Models/ShopCustomer.php88-142

Customer Update Flow

The updateInfo() static method handles customer profile updates src/Models/ShopCustomer.php101-115 sanitizing data and updating both core fields and custom field values.

Customer Deletion Cascade

When a customer is deleted, the model's deleting event hook ensures proper cleanup:

This cascade deletion removes all associated custom field data to maintain referential integrity src/Models/ShopCustomer.php75-85

Sources: src/Models/ShopCustomer.php71-115

Email Verification System

Verification State Management

The customer model includes a built-in email verification system with three key methods:

Verification Status Methods

Method	Return Type	Purpose
isVerified()	boolean	Checks if email_verified_at is not null src/Models/ShopCustomer.php169-172
hasVerifiedEmail()	boolean	Returns true if unverified AND gp247_config('customer_verify') is enabled src/Models/ShopCustomer.php179-182
sendEmailVerify()	boolean	Sends verification email if required src/Models/ShopCustomer.php188-194

Email Verification Middleware Integration

The EmailIsVerifiedMiddleware enforces email verification requirements src/Middleware/EmailIsVerifiedMiddleware.php17-38:

• Configuration-Driven: Only enforces verification if gp247_config('customer_verify') is enabled
• Excluded Routes: Verification pages, logout, and resend routes bypass the check src/Middleware/EmailIsVerifiedMiddleware.php20-24
• Redirect Behavior: Unverified customers are redirected to customer.verify route

Password Reset Integration

The model overrides Laravel's password reset notification to use the shop's email system:

This method is automatically called by Laravel's password reset flow src/Models/ShopCustomer.php55-59

Sources: src/Models/ShopCustomer.php55-194 src/Middleware/EmailIsVerifiedMiddleware.php17-38

Authentication and Security

Authentication Capabilities

As an Authenticatable model, ShopCustomer provides full Laravel authentication support:

Feature	Implementation
Login/Logout	Via customer() guard (defined in auth config)
Session Management	Standard Laravel session driver
Remember Me	Via remember_token column src/Models/ShopCustomer.php35
Password Hashing	Automatic via Laravel's $hidden attribute
API Authentication	Sanctum tokens via HasApiTokens trait src/Models/ShopCustomer.php10-17

Security Features

Password Protection: The password and remember_token fields are hidden from array and JSON serialization src/Models/ShopCustomer.php34-36 preventing accidental exposure in API responses.

Data Sanitization: All input data passes through gp247_clean() before insertion or update src/Models/ShopCustomer.php103-123 providing XSS protection.

Sources: src/Models/ShopCustomer.php10-123

Custom Fields Integration

Custom Field Architecture

The customer model integrates with the GP247 custom fields system, allowing administrators to define additional customer attributes without database schema changes.

Custom Field Lifecycle

Creation/Update: Both createCustomer() and updateInfo() methods accept a fields array that is passed to gp247_custom_field_update() src/Models/ShopCustomer.php112-136:

Deletion: The model's deleting event hook ensures custom field cleanup src/Models/ShopCustomer.php78-83:

• Joins admin_custom_field and admin_custom_field_detail tables
• Filters by rel_id = customer.id and type = 'shop_customer'
• Deletes all matching custom field detail records

Sources: src/Models/ShopCustomer.php78-136

Profile Management

Profile Singleton Pattern

The model implements a cached profile access pattern:

This provides efficient access to the currently authenticated customer without repeated database queries src/Models/ShopCustomer.php28-162

Usage Pattern

Sources: src/Models/ShopCustomer.php28-162

Multi-Store Context

Store Isolation

The ShopCustomer model is store-scoped, meaning customer accounts are isolated per store in multi-vendor configurations:

Configuration	Behavior
Single Store Mode	All customers belong to default store
Multi-Store Mode	Customers are filtered by store_id column
Root Store Access	Administrator can view all customers across stores
Vendor Store Access	Vendor only sees their own customers

The ModelTrait automatically applies store filtering in query builders when multi-store mode is enabled (see Multi-Store and Multi-Vendor Architecture for details).

Store Assignment

When a customer is created, the store_id is automatically set based on the current store context:

• During customer registration on a storefront, the active store ID is assigned
• Administrators creating customers can specify the target store
• Customers cannot access other stores' customer areas

Sources: Referenced from high-level architecture diagrams (Diagram 3: Multi-Tenant Architecture)

Summary of Key Model Methods

Method	Type	Purpose
createCustomer(array)	Static	Factory method for customer creation with address and custom fields src/Models/ShopCustomer.php121-142
updateInfo(array, int)	Static	Update customer profile with custom fields src/Models/ShopCustomer.php101-115
orders()	Relationship	HasMany relationship to ShopOrder src/Models/ShopCustomer.php40-43
addresses()	Relationship	HasMany relationship to ShopCustomerAddress src/Models/ShopCustomer.php45-48
getAddressDefault()	Instance	Retrieve default shipping/billing address src/Models/ShopCustomer.php149-154
isVerified()	Instance	Check if email is verified src/Models/ShopCustomer.php169-172
hasVerifiedEmail()	Instance	Check if verification is required src/Models/ShopCustomer.php179-182
sendEmailVerify()	Instance	Send verification email src/Models/ShopCustomer.php188-194
sendPasswordResetNotification(token)	Instance	Send password reset email src/Models/ShopCustomer.php55-59
getNameAttribute()	Accessor	Compute full name from first_name + last_name src/Models/ShopCustomer.php64-67
profile()	Instance	Cached access to current authenticated customer src/Models/ShopCustomer.php156-162

Sources: src/Models/ShopCustomer.php