README

Free, open-source software for e-commerce websites
composer create-project gp247/s-cart

Homepage | Demo | Documentation | FB Group

(Vietnamese version: README_vi.md)

1. Overview

S-Cart is the best free e-commerce website project for individuals and businesses, built on the GP247 ecosystem (the Laravel Framework) and the latest technologies.

Our mission is "Effective and friendly for everyone":

• Effective: meets even the smallest customer requirements.
• Friendly: easy to use, easy to maintain, easy to extend.
• Everyone: businesses, individuals, developers, students.

S-Cart 2.x:

Backed by the GP247 ecosystem https://github.com/gp247net

Core Laravel framework 13.x https://github.com/laravel/laravel

UI built with Tailwind CSS 4

Screenshots

S-Cart features

Core capabilities

• Plugin packages built on the HMVC pattern
• Command-line upgrades and patches for S-Cart
• Full documentation for developers and customers

Professional storefront features

• Multi-language
• Multi-currency
• Full e-commerce feature set:
  • Shopping cart management
  • Order management
  • Product management
  • Customer management
• CMS content management:
  • Categories
  • News
  • Content pages
• Extensions:
  • Payment plugins
  • Shipping methods
  • Discount system
  • Tax calculation
• Professional plugins for S-Cart:
  • Multi-vendor: https://gp247.net/en/docs/s-cart/multi-vendor.html
  • Multi-store: https://gp247.net/en/docs/s-cart/multi-store.html
• Developer resources:
  • Online marketplace for plugins and templates
  • Secured API support for apps and mobile integrations

Powerful administration

• User management:
  • Role-based permissions (admin, manager, marketing, etc.)
  • Comprehensive security with full audit logging
  • Access control, authentication, and CAPTCHA
• Business tools:
  • Product management
  • Order processing
  • Customer management
  • Analytics and reporting
  • Activity tracking

Folder structure for a GP247-based website

Website-folder/
|
├── app
│     └── GP247
│           ├── Core(+) //Override Core controllers
│           ├── Helpers(+) //Auto-loads Helpers/*.php into the system
│           ├── Front(+) //Override GP247/Front controllers 
│           ├── Shop(+) //Override GP247/Shop controllers 
│           ├── Plugins(+) //Generated by `php artisan gp247:make-plugin --name=NameOfPlugin`
│           └── Templates(+) //Generated by `php artisan gp247:make-template --name=NameOfTempate`
├── public
│     └── GP247
│           ├── Core(+)
│           ├── Plugins(+)
│           └── Templates(+)
├── resources
│            └── views/vendor
│                           ├── gp247-admin(+) //Core view overrides
│                           ├── gp247-shop-admin(+) //Shop view overrides
│                           └── gp247-front-admin(+) //Front view overrides
├── vendor
│     ├── gp247/core
│     ├── gp247/front
│     └── gp247/shop
└──...

2. Quick installation guide

Method 1: Install with Composer (recommended)

1. Create the project

composer create-project gp247/s-cart

2. Check your .env configuration

Make sure the database settings are correct. If APP_KEY is not set yet, generate it with:

php artisan key:generate

3. Install S-Cart

php artisan sc:install

4. Install sample data (optional)

php artisan sc:sample

Method 2: Install with Git Clone

1. Clone the repository

git clone https://github.com/gp247net/s-cart.git
cd s-cart

2. Create .env and install dependencies

cp .env.example .env
php artisan key:generate
composer install

3. Configure the database in .env

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=your_username
DB_PASSWORD=your_password

4. Install S-Cart

php artisan sc:install
php artisan sc:sample   # optional, sample data

Method 3: Install with Docker (supported from S-Cart 2)

No need to install PHP/Composer/MySQL on your machine — Docker is all you need. There are two clearly separate compose files for dev and prod — always use the right one for the environment:

• docker-compose.yml — dev environment (your local machine)
• docker-compose.prod.yml — prod environment (your server)

DEV setup:

git clone https://github.com/gp247net/s-cart.git
cd s-cart
cp .env.example .env
docker compose up -d --build
docker compose exec app php artisan key:generate
docker compose exec app php artisan sc:install
docker compose exec app php artisan sc:sample   # optional

Open the site: http://localhost:8000

PROD setup:

git clone https://github.com/gp247net/s-cart.git
cd s-cart
cp .env.example .env
# Configure .env for prod: APP_ENV, DB_*, WWWUSER/WWWGROUP — see DOCKER.md
docker compose -f docker-compose.prod.yml up -d --build
docker compose -f docker-compose.prod.yml exec app php artisan key:generate
docker compose -f docker-compose.prod.yml exec app php artisan sc:install
docker compose -f docker-compose.prod.yml exec app php artisan sc:sample   # optional
docker compose -f docker-compose.prod.yml run --rm node                    # build CSS/JS assets

⚠️ Always include -f docker-compose.prod.yml on prod — forgetting it accidentally applies the dev config (debug mode on, runs as root, installs Xdebug...). See the Q&A in DOCKER.md for that failure mode in detail.

For the full step-by-step guide and a detailed troubleshooting Q&A covering both dev and prod, see DOCKER.md.

Important note on folder permissions

If you installed with Method 1 or 2 (no Docker), make sure the following folders are writable, otherwise installation and various features won't work correctly:

• app/GP247
• public/GP247
• public/vendor
• resources/views/vendor
• storage
• vendor

3. Q&A

Q: How do I check the installed S-Cart version?

(Only available when S-Cart is installed directly, not via the component-by-component method)

php artisan sc:info

Q: How do I update S-Cart?

Update each package with Composer:

composer update gp247/core
composer update gp247/front
composer update gp247/shop

Then run (only available when S-Cart is installed directly):

php artisan sc:update

Q: How do I create a new plugin?

php artisan gp247:make-plugin --name=PluginName

Also generate a zip file for distribution:

php artisan gp247:make-plugin --name=PluginName --download=1

Q: How do I create a new template?

php artisan gp247:make-template --name=TemplateName

Also generate a zip file for distribution:

php artisan gp247:make-template --name=TemplateName --download=1

Q: How do I customize the upload (lfm) configuration?

php artisan vendor:publish --tag=config-lfm

Q: How do I customize the admin UI?

Each package publishes its admin views into its own views/vendor/<namespace> folder — publish only the tag you actually need to override:

php artisan vendor:publish --tag=gp247:core-view        # -> views/vendor/gp247-admin
php artisan vendor:publish --tag=gp247:front-admin      # -> views/vendor/gp247-front-admin
php artisan vendor:publish --tag=gp247:shop-view-admin  # -> views/vendor/gp247-shop-admin

Add --force if you need to overwrite files already published there.

Q: How do I customize the default template?

php artisan vendor:publish --tag=gp247:front-view       # -> app/GP247/Templates/GP247Front
php artisan vendor:publish --tag=gp247:front-public     # -> public/GP247/Templates/GP247Front
php artisan vendor:publish --tag=gp247:shop-view-front  # -> app/GP247/Templates/GP247Front

Add --force if you need to overwrite files already published there.

Q: How do I override the gp247_* helper functions?

1. Add the list of functions you want to override to config/gp247_functions_except.php
2. Create new PHP files containing the new functions in app/GP247/Helpers, e.g. app/GP247/Helpers/myfunction.php

Q: How do I override controllers in GP247/Core, GP247/Front, or GP247/Shop?

S-Cart lets you override any controller (including API controllers) in GP247/Core, GP247/Front, and GP247/Shop using the same mechanism: create the corresponding controller in app/GP247/{Core|Front|Shop}, extend the original controller, and prepend App to the original namespace.

Example, overriding a Core controller:

1. Create the matching file under app/GP247/Core/Controllers/... (keep the same sub-path and filename as in the original package).
2. Make the new controller extend the original controller from vendor/gp247/core/....
3. Change the namespace from GP247\Core\Controllers to App\GP247\Core\Controllers (just prepend App, keep the rest as-is).

The same pattern applies to GP247\Front\* and GP247\Shop\* (becoming App\GP247\Front\* and App\GP247\Shop\*) and to API controllers (GP247\Core\Api\Controllers becomes App\GP247\Core\Api\Controllers).

Q: How do I add new routes for the admin area?

Use the GP247_ADMIN_PREFIX and GP247_ADMIN_MIDDLEWARE prefix/middleware constants in your route declarations.

Reference: https://github.com/gp247net/core/blob/master/src/routes.php

Q: What environment variables in .env should I know about?

Disable the API:

GP247_API_MODE=1   // set to 0 to disable

Database table prefix (cannot be changed after gp247 is installed):

GP247_DB_PREFIX=gp247_

Admin page path prefix:

GP247_ADMIN_PREFIX=gp247_admin