Helper Functions and Utilities

Purpose and Scope

This document provides a reference guide for the utility functions and helper methods available in the GP247/Shop package. These functions provide reusable logic for common operations including order processing, customer management, email notifications, and data validation/mapping.

For information about the broader configuration system that many of these helpers rely on, see Configuration-Driven System Behavior. For controller-level order processing logic, see Order Processing and Email Notifications. For customer model methods and authentication, see Customer Authentication.

The helper functions are organized into two primary files:

• src/Library/Helpers/order.php - Order processing and validation utilities
• src/Library/Helpers/customer.php - Customer management and data mapping utilities

All helper functions include existence checks and can be disabled via the gp247_functions_except configuration array to allow custom implementations.

---

Helper Function Architecture

The following diagram illustrates how helper functions integrate into the system architecture:

Sources: src/Library/Helpers/order.php1-211 src/Library/Helpers/customer.php1-671

---

Order Helper Functions

gp247_order_process_after_success

Handles post-order processing including sending email notifications to both administrators and customers.

Function Signature:

Behavior Flow:

Key Implementation Details:

Aspect	Implementation
Configuration Dependencies	order_success_to_admin, order_success_to_customer, email_action_mode
Data Sources	ShopOrder::with('details')->find($orderID)
Product Details	Calls ShopProduct->getDetail($product_id) for each order item
Download Links	Checks $product->tag == GP247_TAG_DOWNLOAD and $product->downloadPath->path
Currency Rendering	Uses gp247_currency_render() for all monetary values
View Resolution	Uses gp247_shop_process_view('GP247TemplatePath::'.gp247_store_info('template'), $subPath)
Email Subjects	Rendered via gp247_language_render('email.order.email_subject_to_admin', ['order_id' => $orderID])

Sources: src/Library/Helpers/order.php7-84

---

gp247_order_mapping_validate

Generates dynamic validation rules and error messages for order/checkout forms based on configuration settings.

Function Signature:

Return Structure:

Configuration-Driven Validation Logic:

Configuration Keys Checked:

Configuration Key	Validation Impact
use_shipping	Makes shippingMethod required
use_payment	Makes paymentMethod required
customer_lastname	Enables last_name field
customer_lastname_required	Makes last_name required vs nullable
customer_address1	Enables address1 field
customer_address1_required	Makes address1 required vs nullable
customer_address2	Enables address2 field
customer_address2_required	Makes address2 required vs nullable
customer_address3	Enables address3 field
customer_address3_required	Makes address3 required vs nullable
customer_phone	Enables phone field
customer_phone_required	Makes phone required vs nullable
customer_country	Enables country field (validates against AdminCountry codes)
customer_country_required	Makes country required vs nullable
customer_postcode	Enables postcode field
customer_postcode_required	Makes postcode required vs nullable
customer_company	Enables company field
customer_company_required	Makes company required vs nullable
customer_name_kana	Enables first_name_kana and last_name_kana fields
customer_name_kana_required	Makes kana fields required vs nullable

Country Validation: The function queries AdminCountry table to build a dynamic list of valid country codes:

Sources: src/Library/Helpers/order.php89-211

---

Customer Helper Functions

customer

Returns the customer authentication guard instance.

Function Signature:

Usage:

Sources: src/Library/Helpers/customer.php7-15

---

Email Notification Functions

The following diagram shows the email notification system flow:

Sources: src/Library/Helpers/customer.php20-102

---

gp247_customer_sendmail_reset_notification

Sends password reset email with a time-limited reset link.

Function Signature:

Parameters:

Parameter	Type	Description
$token	string	Password reset token
$emailReset	string	Customer email address

Implementation Details:

• Generates reset URL: gp247_route_front('customer.password_reset', ['token' => $token])
• Token expiry pulled from: config('auth.passwords.'.config('auth.defaults.passwords').'.expire')
• Uses view template: email.forgot_password
• Subject: gp247_language_render('email.forgot_password.reset_button')

Sources: src/Library/Helpers/customer.php20-41

---

gp247_customer_sendmail_verify

Sends email verification link to newly registered customers.

Function Signature:

Parameters:

Parameter	Type	Description
$emailVerify	string	Customer email address
$userId	string	Customer user ID

Implementation Details:

• Generates signed URL using Laravel's URL::temporarySignedRoute()
• Route name: customer.verify_process
• Expiry: config('auth.verification', 60) minutes
• Token: sha1($emailVerify)
• Uses view template: email.customer_verify
• Returns: true on success

Sources: src/Library/Helpers/customer.php47-79

---

gp247_customer_sendmail_welcome

Sends welcome email to newly registered customers (if enabled via configuration).

Function Signature:

Parameters:

Parameter	Type	Description
$customer	ShopCustomer	Customer model instance

Configuration Check: Only sends if gp247_config('welcome_customer') is enabled.

Data Included:

• title: From gp247_language_render('email.welcome_customer.title')
• first_name: Customer's first name
• last_name: Customer's last name

Sources: src/Library/Helpers/customer.php84-102

---

Data Mapping and Validation Functions

These functions provide configuration-driven data mapping and validation rule generation for customer operations:

Sources: src/Library/Helpers/customer.php111-615

---

gp247_customer_address_mapping

Maps and validates customer address data for address book operations.

Function Signature:

Return Structure:

Base Fields (Always Present):

• first_name (required)
• address1 (required)

Configuration-Dependent Fields:

Config Key	Field Added	Required Config
customer_lastname	last_name	customer_lastname_required
customer_address2	address2	customer_address2_required
customer_address3	address3	customer_address3_required
customer_phone	phone	customer_phone_required
customer_country	country	customer_country_required
customer_postcode	postcode	customer_postcode_required

Sources: src/Library/Helpers/customer.php111-173

---

gp247_customer_data_insert_mapping

Maps and validates customer data for registration/creation operations.

Function Signature:

Return Structure:

Base Fields (Always Present):

• first_name (required)
• email (required, unique, email format)
• password (bcrypted, with confirmation)

Special Handling:

Aspect	Implementation
Password Hashing	bcrypt($dataRaw['password']) applied
Email Uniqueness	Validates unique:ShopCustomer,email
Password Rules	Uses gp247_customer_validate_password()['password_confirm']
Custom Fields	Queries AdminCustomField for shop_customer type
Status Field	Optionally includes $dataRaw['status'] if present

Configuration-Driven Fields: Same as gp247_customer_address_mapping, plus:

• customer_sex / customer_sex_required
• customer_birthday / customer_birthday_required
• customer_group / customer_group_required
• customer_company / customer_company_required
• customer_name_kana / customer_name_kana_required (adds both first_name_kana and last_name_kana)

Sources: src/Library/Helpers/customer.php183-396

---

gp247_customer_data_edit_mapping

Maps and validates customer data for profile update operations.

Function Signature:

Return Structure:

Differences from Insert Mapping:

Aspect	Insert Mapping	Edit Mapping
Password	Required with confirmation	Nullable (only updated if provided)
Email Uniqueness	Checks all records	Excludes current customer ID
ID Handling	Not applicable	Explicitly unset from $dataRaw
Password Rule	password_confirm	password_nullable

Password Update Logic:

Email Uniqueness:

Sources: src/Library/Helpers/customer.php405-615

---

gp247_customer_validate_password

Generates dynamic password validation rules based on configuration.

Function Signature:

Return Structure:

Password Validation Builder:

Configuration Keys:

Config Key	Default	Validation Rule Added
customer_password_min	6	Minimum length
customer_password_max	16	Maximum length
customer_password_letter	false	Requires at least one letter
customer_password_mixedcase	false	Requires uppercase and lowercase
customer_password_number	false	Requires at least one number
customer_password_symbol	false	Requires at least one symbol

Sources: src/Library/Helpers/customer.php644-670

---

Customer Lifecycle Functions

gp247_customer_created_by_client

Hook function executed after customer self-registration.

Function Signature:

Actions Performed:

1. Sends welcome email via gp247_customer_sendmail_welcome($user)
2. Sends email verification via $user->sendEmailVerify()

Sources: src/Library/Helpers/customer.php620-629

---

gp247_customer_created_by_admin

Hook function executed after admin creates a customer.

Function Signature:

Current Implementation: Empty placeholder for future customization.

Sources: src/Library/Helpers/customer.php634-639

---

Email Template Structure

The email templates referenced by helper functions follow a consistent structure:

Order Success Email Templates

Admin Template: email.order_success_to_admin Customer Template: email.order_success_to_customer

Both templates extend gp247-shop-front::email.layout and receive the following data:

Variable	Description
$orderID	Order ID string
$toname	Full name (first + last)
$address	Combined address (address1 + address2 + address3)
$phone	Phone number
$currency	Currency code
$comment	Order comment/notes
$orderDetail	Array of order items with sku, name, linkDownload, price, qty, total
$subtotal	Subtotal (currency rendered)
$shipping	Shipping cost (currency rendered)
$discount	Discount amount (currency rendered)
$otherFee	Other fees (currency rendered)
$total	Total amount (currency rendered)

Order Detail Item Structure:

Sources: src/Views/front/email/order_success_to_admin.blade.php1-68 src/Views/front/email/order_success_to_customer.blade.php1-68

---

Helper Function Disabling Mechanism

All helper functions check for existence and can be disabled via configuration:

To Disable a Helper Function:

1. Add function name to gp247_functions_except config array
2. Implement custom version in your application

Example:

This pattern allows developers to override any helper function with custom business logic while maintaining the rest of the system's functionality.

Sources: src/Library/Helpers/order.php7-8 src/Library/Helpers/customer.php7-8

---

Integration with Core Services

The helper functions integrate with several core services from the GP247 ecosystem:

Service Function	Purpose	Used By
gp247_config()	Retrieve configuration values	All validation mapping functions
gp247_language_render()	Render localized text	All email and message functions
gp247_mail_send()	Send emails	All email notification functions
gp247_shop_process_view()	Resolve template views	All email notification functions
gp247_currency_render()	Format currency values	Order email functions
gp247_store_info()	Get store information	Email configuration
gp247_route_front()	Generate frontend routes	Password reset emails

These core services are provided by the GP247/Core package and documented separately. For configuration system details, see Configuration-Driven System Behavior.

Sources: src/Library/Helpers/order.php10-80 src/Library/Helpers/customer.php23-99