Installation and Setup

Purpose and Scope

This document guides you through installing the GP247/Shop package and performing initial setup. It covers prerequisite packages, two installation approaches (adding to an existing GP247 CMS installation or using the complete S-Cart distribution), service provider registration, running setup commands, and customizing published views.

For information about the core architecture and how the service provider bootstraps the system, see Core Architecture and Service Provider. For database schema details created during installation, see Database Schema. For initial data seeding, see Data Seeders and Initialization.

---

Installation Prerequisites

GP247/Shop requires the following packages from the GP247 ecosystem:

Package	Role	Installation Method
Laravel	Framework foundation	Included in GP247/CMS
GP247/Core	Core system functionality	Dependency of GP247/CMS
GP247/Front	Frontend infrastructure	Dependency of GP247/CMS

The package integrates into the GP247 ecosystem through ShopServiceProvider, which registers routes, middleware, commands, and configurations into the Laravel application.

Sources: readme.md67-81 ShopServiceProvider.php1-17

---

Installation Workflow

Sources: readme.md64-100

---

Option 1: Adding Shop to GP247 CMS

Step 1: Install GP247 CMS Base

Install the GP247 CMS package, which includes Laravel, GP247/Core, and GP247/Front:

This creates a complete CMS installation with the GP247 ecosystem foundation.

Step 2: Require the Shop Package

Add the shop package via Composer:

This installs the GP247/Shop package and its dependencies into vendor/gp247/shop/.

Step 3: Register Service Provider

Edit bootstrap/providers.php and add the service provider to the end of the array:

The ShopServiceProvider class is located at src/ShopServiceProvider.php17 and handles all package bootstrapping.

Step 4: Run Installation Command

Execute the shop installation command:

This command is registered in src/ShopServiceProvider.php50-51 and performs:

• Database migration execution (creates 39 tables)
• Initialization seeder execution (admin menus, currencies, statuses)
• Default configuration seeder execution
• Directory structure creation

Step 5: Generate Sample Data

Optionally create sample data for testing:

This command is registered in src/ShopServiceProvider.php53 and populates products, categories, brands, and demo orders.

Sources: readme.md66-87 ShopServiceProvider.php50-61

---

Option 2: Using S-Cart Distribution

S-Cart is a complete e-commerce distribution that includes Laravel, GP247 ecosystem packages, and GP247/Shop pre-configured.

Step 1: Create S-Cart Project

This installs all required packages with the service provider already registered.

Step 2: Run S-Cart Installation

Equivalent to gp247:shop-install, performs database setup and initialization.

Step 3: Generate Sample Data

Equivalent to gp247:shop-sample, creates demonstration content.

Sources: readme.md89-100

---

Service Provider Bootstrap Sequence

Sources: ShopServiceProvider.php69-132 ShopServiceProvider.php139-206 ShopServiceProvider.php20-62

---

Directory Structure Created

During the initial() method execution, the service provider creates application directories for custom extensions:

Directory Path	Purpose	Created In
app/GP247/Shop/Api	Custom API controllers	ShopServiceProvider.php24-26
app/GP247/Shop/Controllers	Custom frontend controllers	ShopServiceProvider.php27-29
app/GP247/Shop/Admin/Controllers	Custom admin controllers	ShopServiceProvider.php30-32

These directories allow developers to extend the shop package without modifying vendor files.

Sources: ShopServiceProvider.php23-37

---

Registered Artisan Commands

The service provider registers four management commands:

Command	Class	Function	Registered In
gp247:shop-install	ShopInstall	Run migrations and seeders	ShopServiceProvider.php51
gp247:shop-uninstall	ShopUninstall	Remove shop data and tables	ShopServiceProvider.php52
gp247:shop-sample	ShopSample	Generate demonstration data	ShopServiceProvider.php53
gp247:shop-clear-cart	ShopClearCart	Clean expired cart sessions	ShopServiceProvider.php54

Command registration occurs in the initial() method at ShopServiceProvider.php50-55

Sources: ShopServiceProvider.php7-10 ShopServiceProvider.php50-61

---

Configuration Merging

The register() method merges shop configurations into the Laravel application:

Core Configuration

Located at ShopServiceProvider.php141:

Customer Authentication Guards

Customer-specific auth guards registered at ShopServiceProvider.php188-190:

• auth.guards - Defines customer guard configuration
• auth.passwords - Password reset configuration for customers
• auth.providers - Customer authentication provider

Middleware Configuration

Frontend middleware extended at ShopServiceProvider.php146-149:

• check.currency - Currency selection middleware
• check.email_verified - Email verification enforcement

File Manager Configuration

File upload folders configured at ShopServiceProvider.php182-185 for:

• product - Product images
• category - Category images
• brand - Brand logos
• supplier - Supplier images
• customer - Customer avatars

Layout Page Configuration

Frontend layout pages registered at ShopServiceProvider.php193-204 including:

• shop_item_list - Product listing layouts
• shop_product_detail - Product detail pages
• shop_cart - Shopping cart pages
• shop_checkout - Checkout flow pages
• shop_profile - Customer account pages

Sources: ShopServiceProvider.php139-206

---

Middleware Registration

Middleware registration occurs at ShopServiceProvider.php245-256 The middleware classes are:

• CurrencyMiddleware at ShopServiceProvider.php11
• EmailIsVerifiedMiddleware at ShopServiceProvider.php12
• CustomerAuth at ShopServiceProvider.php13

Sources: ShopServiceProvider.php221-256

---

View Loading and Publishing

View Namespace Registration

The service provider loads views from two locations:

Views are accessed using namespace syntax:

• Admin: gp247-shop-admin::path.to.view
• Frontend: gp247-shop-front::path.to.view

Sources: ShopServiceProvider.php108-109

Publishing Views for Customization

Admin View Customization

Publish admin views to modify backend interfaces:

Published location: resources/views/vendor/gp247-shop-admin

Configured at ShopServiceProvider.php286

Frontend View Customization

Publish frontend views to customize storefront templates:

Published location: app/GP247/Templates/Default

Configured at ShopServiceProvider.php287

Note: If using a custom template (not Default), manually copy views from vendor/gp247/shop/Views/front to your template directory.

Sources: ShopServiceProvider.php283-289 readme.md106-121

---

Installation Verification

After installation, verify the setup:

1. Check Database Tables

Confirm 39 shop tables were created with prefix shop_:

• Core entities: shop_product, shop_category, shop_order, shop_customer
• Supporting tables: shop_order_detail, shop_product_description, etc.

2. Access Admin Panel

Navigate to /admin and verify shop menu items appear:

• Products
• Categories
• Orders
• Customers
• Reports

These are registered by the initialization seeder.

3. Check Frontend Routes

Verify frontend shop routes are accessible:

• /shop - Product listing
• /cart - Shopping cart
• /checkout - Checkout process

4. Verify Commands Available

List available shop commands:

Should display:

• gp247:shop-install
• gp247:shop-uninstall
• gp247:shop-sample
• gp247:shop-clear-cart

Sources: ShopServiceProvider.php50-55

---

Post-Installation Configuration

After installation, configure the shop via admin panel:

Configuration Area	Admin Location	Purpose
Store Information	/admin/store_info	Business name, contact details
Currency Settings	/admin/currency	Supported currencies, exchange rates
Payment Methods	/admin/extension/payment	Enable payment gateways
Shipping Methods	/admin/extension/shipping	Configure shipping options
Tax Configuration	/admin/tax	Tax rules and rates
Email Templates	/admin/email_template	Order notifications

Configuration values are stored in the admin_config table and accessed via the gp247_config() helper function throughout the application.

For detailed configuration information, see Configuration-Driven System Behavior.

Sources: ShopServiceProvider.php141

---

Troubleshooting

Directory Creation Errors

If directory creation fails during initial(), check:

• Write permissions on app/ directory
• PHP mkdir() function availability
• Disk space availability

Error handling at ShopServiceProvider.php23-37 catches exceptions and displays detailed error messages.

Service Provider Not Found

If ShopServiceProvider class not found:

1. Verify package installed: composer show gp247/shop
2. Check bootstrap/providers.php includes correct namespace
3. Clear configuration cache: php artisan config:clear
4. Regenerate autoload files: composer dump-autoload

Migration Failures

If gp247:shop-install fails:

1. Check database connection in .env
2. Ensure database exists and user has CREATE TABLE permissions
3. Review migration files in vendor/gp247/shop/src/DB/migrations/
4. Check Laravel logs in storage/logs/

View Not Found Errors

If views not loading:

1. Clear view cache: php artisan view:clear
2. Verify service provider registered
3. Check view namespace registration at ShopServiceProvider.php108-109

Sources: ShopServiceProvider.php33-36 ShopServiceProvider.php43-46 ShopServiceProvider.php56-61