PHPackages                             davidiwezulu/ecommerce - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Framework](/categories/framework)
4. /
5. davidiwezulu/ecommerce

ActiveLibrary[Framework](/categories/framework)

davidiwezulu/ecommerce
======================

A flexible e-commerce package for Laravel

v1.1.0(1y ago)110MITPHPPHP >=8.2CI passing

Since Sep 28Pushed 1y ago1 watchersCompare

[ Source](https://github.com/davidiwezulu/ecommerce)[ Packagist](https://packagist.org/packages/davidiwezulu/ecommerce)[ RSS](/packages/davidiwezulu-ecommerce/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (6)Versions (3)Used By (0)

🎉 Laravel E-Commerce Package
============================

[](#-laravel-e-commerce-package)

[![Latest Version on Packagist](https://camo.githubusercontent.com/79a6e3a896dcdb59a4d492d4161e7a9b485641b017d187dd68fd4fb9dd1f134d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f64617669646977657a756c752f65636f6d6d657263652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/davidiwezulu/ecommerce)[![Tests](https://github.com/davidiwezulu/ecommerce/actions/workflows/ci.yml/badge.svg)](https://github.com/davidiwezulu/ecommerce/actions/workflows/ci.yml/badge.svg)[![License: MIT](https://camo.githubusercontent.com/fdf2982b9f5d7489dcf44570e714e3a15fce6253e0cc6b5aa61a075aac2ff71b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d79656c6c6f772e737667)](https://opensource.org/licenses/MIT)

Introduction
------------

[](#introduction)

After letting this gem sit in a private repository for way too long, I decided it was time to dust it off, give it a serious makeover, and finally share it with everyone. What started as a personal side project has now evolved into a full-fledged e-commerce package 🚀.

Overview
--------

[](#overview)

An extensible Laravel package providing robust e-commerce functionalities, including cart management, order processing, admin operations, flexible tax calculations, and seamless payment gateway integration (Stripe and PayPal). Designed without a predefined UI to offer maximum flexibility, allowing integration with any Laravel backend, controllers, or views.

Laravel Version Compatibility
-----------------------------

[](#laravel-version-compatibility)

This package is compatible with the following Laravel versions:

LaravelPackage8.x–10.x≥1.0.011.x≥1.0.0Requirements
------------

[](#requirements)

- **PHP**: >= 8.0
- **Laravel**: 8.x, 9.x, or 10.x, 11.x
- **Database**: MySQL, PostgreSQL, SQLite, or any Laravel-supported database.

### Upgrade steps for Laravel 11 projects)

[](#upgrade-steps-for-laravel-11-projects)

```
composer require davidiwezulu/ecommerce "^1.1"
php artisan vendor:publish --provider="Davidiwezulu\Ecommerce\EcommerceServiceProvider" --tag=config
php artisan vendor:publish --provider="Davidiwezulu\Ecommerce\EcommerceServiceProvider" --tag=migrations
php artisan migrate

```

Table of Contents
-----------------

[](#table-of-contents)

- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
    - [Important Note](#important-note)
    - [Currency Settings](#currency-settings)
    - [Tax Settings](#tax-settings)
    - [Payment Gateways](#payment-gateways)
        - [Stripe Configuration](#stripe-configuration)
        - [PayPal Configuration](#paypal-configuration)
    - [Custom Models](#custom-models)
    - [Database Migrations](#database-migrations)
- [Usage](#usage)
    - [Cart Management](#cart-management)
        - [Adding or Updating Cart Items](#adding-or-updating-cart-items)
        - [Removing Cart Items](#removing-cart-items)
        - [Retrieving Cart Items](#retrieving-cart-items)
        - [Clearing the Cart](#clearing-the-cart)
    - [Admin Operations](#admin-operations)
        - [Adding a New Product with Tax Rate](#adding-a-new-product-with-tax-rate)
        - [Updating an Existing Product](#updating-an-existing-product)
        - [Updating Inventory](#updating-inventory)
    - [Order Processing](#order-processing)
        - [Stripe Payment Example](#stripe-payment-example)
        - [PayPal Payment Example](#paypal-payment-example)
    - [Tax Calculations](#tax-calculations)
- [Extending the Package](#extending-the-package)
    - [Custom Models](#custom-models-1)
        - [Extend Package Models (Optional)](#extend-package-models-optional)
    - [Adding Custom Payment Gateways](#adding-custom-payment-gateways)
- [License](#license)
- [Conclusion](#conclusion)

Features
--------

[](#features)

- **Cart Management**: Add, update, remove, and retrieve cart items with tax calculations.
- **Order Processing**: Create, process, and manage orders with tax-inclusive totals.
- **Admin Operations**: Create and manage products, update inventory, and set specific tax rates per product.
- **Payment Gateway Integration**: Supports Stripe and PayPal, with options for customisation.
- **Flexible Tax System**: Configure default tax rates, specify per-product tax rates, and choose whether taxes are included in prices.
- **Currency Configuration**: Define default currency symbol and code.
- **Model customisation**: Extend and override default models through configuration.
- **Extensibility**: Implement custom payment gateways by adhering to the provided interface.
- **Payment Status Handling**: Handle successful and failed payments with appropriate responses.
- **Automatic Inventory Tracking**: Automatically updates product inventory levels upon successful order placements.
- **Seamless Integration**: Designed to integrate with any Laravel application without enforcing any specific frontend or UI.

Installation
------------

[](#installation)

### Step 1: Install the Package

[](#step-1-install-the-package)

Use Composer to install the package into your Laravel application:

```
composer require davidiwezulu/ecommerce
```

### Step 2: Publish Configuration and Migrations

[](#step-2-publish-configuration-and-migrations)

**Important:** Before running migrations, ensure you have configured the package according to your application's needs. This includes setting up currency, tax settings, payment gateways, and customising models if necessary.

Publish the package's configuration file and migrations:

```
php artisan vendor:publish --provider="Davidiwezulu\Ecommerce\EcommerceServiceProvider"
```

### Step 3: Configure the Package

[](#step-3-configure-the-package)

Edit the `config/ecommerce.php` file to suit your application's requirements. Ensure all configurations are set correctly before proceeding to migrations.

### Step 4: Run Migrations

[](#step-4-run-migrations)

Run the migrations to create the necessary database tables:

```
php artisan migrate
```

### Configuration

[](#configuration)

The package provides a configuration file located at `config/ecommerce.php`, allowing you to customise various aspects.

#### Important Note

[](#important-note)

Configure the package before running migrations. This ensures that your custom settings, such as table names and model classes, are correctly applied during the migration process.

#### Currency Settings

[](#currency-settings)

Set your application's default currency in the `.env` file:

```
CURRENCY_SYMBOL=£
CURRENCY_CODE=GBP
```

Or directly in config/ecommerce.php:

```
'currency' => [
    'symbol' => env('CURRENCY_SYMBOL', '£'),
    'code'   => env('CURRENCY_CODE', 'GBP'),
],
```

#### Tax Settings

[](#tax-settings)

Configure tax settings in the .env file:

```
TAX_RATE=0.2  # 20% default tax rate
TAX_INCLUDED_IN_PRICES=false  # Are taxes included in product prices?
```

Or directly in config/ecommerce.php:

```
'tax' => [
    'default_rate' => env('TAX_RATE', 0.0),
    'included_in_prices' => env('TAX_INCLUDED_IN_PRICES', false),
],
```

### Payment Gateways

[](#payment-gateways)

#### Stripe Configuration

[](#stripe-configuration)

In your .env file:

```
STRIPE_SECRET_KEY=your-stripe-secret-key
```

In config/ecommerce.php:

```
'payment_gateways' => [
    'stripe' => [
        'class'      => \Davidiwezulu\Ecommerce\Payments\StripeGateway::class,
        'secret_key' => env('STRIPE_SECRET_KEY'),
    ],
    // ...
],
```

#### PayPal Configuration

[](#paypal-configuration)

In your .env file:

```
PAYPAL_CLIENT_ID=your-paypal-client-id
PAYPAL_SECRET=your-paypal-secret
PAYPAL_MODE=sandbox  # Use 'live' for production
```

In config/ecommerce.php:

```
'payment_gateways' => [
    'paypal' => [
        'class'     => \Davidiwezulu\Ecommerce\Payments\PayPalGateway::class,
        'client_id' => env('PAYPAL_CLIENT_ID'),
        'secret'    => env('PAYPAL_SECRET'),
        'mode'      => env('PAYPAL_MODE', 'sandbox'),
    ],
    // ...
],
```

### Custom Models

[](#custom-models)

You can override the default models used by the package in config/ecommerce.php:

```
'models' => [
    'product'     => App\Models\Product::class,
    'inventory'   => App\Models\Inventory::class,
    'order'       => App\Models\Order::class,
    'order_item'  => App\Models\OrderItem::class,
    'cart_item'   => App\Models\CartItem::class,
],
```

#### Database Migrations

[](#database-migrations)

The package provides migrations for creating necessary database tables. If you've customised table names or models, ensure that these are correctly set in the configuration before running migrations.

Important: Always back up your database before running new migrations, especially in production environments.

Usage
-----

[](#usage)

### Cart Management

[](#cart-management)

Manage cart items using the `Cart` facade.

#### Adding or Updating Cart Items

[](#adding-or-updating-cart-items)

```
use Davidiwezulu\Ecommerce\Facades\Cart;

Cart::addOrUpdate($productId, $quantity);
```

#### Removing Cart Items

[](#removing-cart-items)

```
Cart::remove($productId);
```

#### Retrieving Cart Items

[](#retrieving-cart-items)

```
$items = Cart::items();

foreach ($items as $item) {
    echo 'Product: ' . $item->product->name . PHP_EOL;
    echo 'Price: ' . $item->price . PHP_EOL;
    echo 'Tax Amount: ' . $item->tax_amount . PHP_EOL;
    echo 'Quantity: ' . $item->quantity . PHP_EOL;
    echo 'Total Price: ' . $item->total_price . PHP_EOL; // Uses getTotalPriceAttribute()
    echo '---' . PHP_EOL;
}
```

#### Clearing the Cart

[](#clearing-the-cart)

```
Cart::clear();
```

### Admin Operations

[](#admin-operations)

Admins can manage products and inventory using the Admin facade.

#### Adding a New Product with Tax Rate

[](#adding-a-new-product-with-tax-rate)

```
use Davidiwezulu\Ecommerce\Facades\Admin;

$productData = [
    'name'        => 'Product Name',
    'price'       => 100.00,
    'tax_rate'    => 0.15, // 15% tax rate
    'description' => 'Product Description',
    'sku'         => 'SKU001',
];

$product = Admin::addProduct($productData);
```

#### Updating an Existing Product

[](#updating-an-existing-product)

```
$productData = [
    'name'        => 'Updated Product Name',
    'price'       => 120.00,
    'tax_rate'    => 0.18, // Updated tax rate
    'description' => 'Updated Description',
];

$product = Admin::updateProduct($productId, $productData);
```

#### Updating Inventory

[](#updating-inventory)

```
$quantity = 50; // New stock quantity
Admin::updateInventory($productId, $quantity);
```

### Order Processing

[](#order-processing)

Use the Order facade to create orders and process payments.

#### Stripe Payment Example

[](#stripe-payment-example)

```
use Davidiwezulu\Ecommerce\Facades\Order;
use Illuminate\Support\Facades\Auth;
use Davidiwezulu\Ecommerce\Facades\Cart;

$paymentDetails = [
    'gateway' => 'stripe',
    'token'   => 'stripe-token', // Token from Stripe.js or Checkout
];

$cartItems = Cart::items()->toArray();

try {
    $order = Order::create(Auth::id(), $cartItems, $paymentDetails);
    Cart::clear();
    return redirect()->route('order.success')->with('message', 'Order created successfully!');
} catch (\Exception $e) {
    return redirect()->route('order.failed')->with('error', 'Payment failed: ' . $e->getMessage());
}
```

#### PayPal Payment Example

[](#paypal-payment-example)

#### Step 1: Initiate PayPal Payment

[](#step-1-initiate-paypal-payment)

```
use Davidiwezulu\Ecommerce\Facades\Order;
use Illuminate\Support\Facades\Auth;

$paymentDetails = [
    'gateway'    => 'paypal',
    'return_url' => route('paypal.return'),
    'cancel_url' => route('paypal.cancel'),
];

$cartItems = Cart::items()->toArray();

try {
    // This will redirect the user to PayPal for payment approval
    return Order::create(Auth::id(), $cartItems, $paymentDetails);
} catch (\Exception $e) {
    return redirect()->route('order.failed')->with('error', 'Payment initiation failed: ' . $e->getMessage());
}
```

#### Step 2: Handle PayPal Return (After User Approval)

[](#step-2-handle-paypal-return-after-user-approval)

Create routes in your web.php:

```
Route::get('/paypal/return', [PaymentController::class, 'handlePayPalReturn'])->name('paypal.return');
Route::get('/paypal/cancel', [PaymentController::class, 'handlePayPalCancel'])->name('paypal.cancel');
```

Implement the controller methods:

```
namespace App\Http\Controllers;

use Illuminate\Http\Request;
use Illuminate\Support\Facades\Auth;
use Davidiwezulu\Ecommerce\Services\OrderService;
use Davidiwezulu\Ecommerce\Facades\Cart;

class PaymentController extends Controller
{
    public function handlePayPalReturn(Request $request)
    {
        $paymentId = $request->get('paymentId');
        $payerId   = $request->get('PayerID');
        $userId    = Auth::id();
        $cartItems = Cart::items()->toArray();

        try {
            $orderService = new OrderService();
            $order = $orderService->executePayPalPayment($paymentId, $payerId, $userId, $cartItems);
            Cart::clear();
            return redirect()->route('order.success')->with('message', 'Order created successfully!');
        } catch (\Exception $e) {
            return redirect()->route('order.failed')->with('error', 'Payment failed: ' . $e->getMessage());
        }
    }

    public function handlePayPalCancel()
    {
        return redirect()->route('order.cancelled')->with('message', 'Payment was cancelled.');
    }
}
```

### Tax Calculations

[](#tax-calculations)

The package supports flexible tax calculations, including per-product tax rates and configurable default tax rates.

#### Adding a Product with a Specific Tax Rate

[](#adding-a-product-with-a-specific-tax-rate)

```
use Davidiwezulu\Ecommerce\Facades\Admin;

$productData = [
    'name'        => 'Taxed Product',
    'price'       => 200.00,
    'tax_rate'    => 0.10, // 10% tax rate
    'description' => 'A product with a specific tax rate',
    'sku'         => 'TP-002',
];

$product = Admin::addProduct($productData);
```

#### Calculating Tax in Cart Items

[](#calculating-tax-in-cart-items)

When you add or update items in the cart, the tax amount is automatically calculated based on the product's tax rate or the default tax rate.

```
use Davidiwezulu\Ecommerce\Facades\Cart;

// Add product to cart
Cart::addOrUpdate($productId, $quantity);

// Retrieve cart items with tax details
$items = Cart::items();

foreach ($items as $item) {
    echo 'Product: ' . $item->product->name . PHP_EOL;
    echo 'Price: ' . $item->price . PHP_EOL;
    echo 'Tax Amount: ' . $item->tax_amount . PHP_EOL;
    echo 'Total Price (incl. Tax): ' . $item->total_price . PHP_EOL;
}
```

### Extending the Package

[](#extending-the-package)

#### Custom Models

[](#custom-models-1)

**Benefit of Custom Models:** Defining models in the configuration allows you to override or extend the default models provided by the package with your own custom models. This provides flexibility to add custom methods, relationships, and business logic specific to your application.

#### Extend Package Models (Optional)

[](#extend-package-models-optional)

You can extend the package's default models if you want to retain the base functionality while adding your customisations.

**Example:**

```
namespace App\Models;

use Davidiwezulu\Ecommerce\Models\Product as BaseProduct;

class Product extends BaseProduct
{
    // Add your customisations here

    /**
     * Example of adding a new relationship.
     */
    public function categories()
    {
        return $this->belongsToMany(Category::class);
    }

    /**
     * Example of adding a custom method.
     */
    public function calculateDiscountedPrice()
    {
        // Implement your discount logic here
    }
}
```

### Update Configuration:

[](#update-configuration)

In config/ecommerce.php:

```
'models' => [
    'product' => App\Models\Product::class,
    // Other models...
],
```

#### Explanation:

[](#explanation)

By extending BaseProduct, you retain all the original functionality provided by the package. You can add new relationships, methods, accessors, and mutators in your custom Product model. The package will use your custom model throughout its operations.

Adding Custom Payment Gateways
------------------------------

[](#adding-custom-payment-gateways)

You can add new payment gateways by implementing the PaymentGatewayInterface.

Create a Custom Gateway Class

```
namespace App\Payments;

use Davidiwezulu\Ecommerce\Payments\PaymentGatewayInterface;

class CustomGateway implements PaymentGatewayInterface
{
    public function charge($amount, $paymentDetails)
    {
        // Implement charge logic
    }

    public function execute($paymentId, $payerId)
    {
        // Implement execute logic (if needed)
    }

    public function refund($transactionId)
    {
        // Implement refund logic
    }
}
```

### Register the Custom Gateway

[](#register-the-custom-gateway)

In config/ecommerce.php:

```
'payment_gateways' => [
    // Existing gateways...
    'custom_gateway' => [
        'class' => \App\Payments\CustomGateway::class,
        // Additional configuration...
    ],
],
```

License
-------

[](#license)

This package is open-sourced software licensed under the MIT license.

### Conclusion

[](#conclusion)

The Laravel E-commerce package provides a comprehensive solution for implementing e-commerce functionality in your Laravel application. With features like flexible tax calculations, seamless payment gateway integration, and customisable models, it offers a solid foundation for building robust online stores.

**Important:** Remember to configure the package appropriately before running migrations to ensure a smooth integration with your application.

For any questions or contributions, feel free to open an issue or submit a pull request on GitHub.

Thank you for choosing the Laravel E-commerce package!

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance48

Moderate activity, may be stable

Popularity7

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~201 days

Total

2

Last Release

388d ago

PHP version history (2 changes)v1.0.0PHP >=8.1

v1.1.0PHP >=8.2

### Community

Maintainers

![](https://www.gravatar.com/avatar/3697dfced26f3985512f9ab6f068ce20abb9c40a30cc83c8fa69d92db33d649a?d=identicon)[davidiwezulu](/maintainers/davidiwezulu)

---

Top Contributors

[![davidiwezulu](https://avatars.githubusercontent.com/u/35039663?v=4)](https://github.com/davidiwezulu "davidiwezulu (17 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/davidiwezulu-ecommerce/health.svg)

```
[![Health](https://phpackages.com/badges/davidiwezulu-ecommerce/health.svg)](https://phpackages.com/packages/davidiwezulu-ecommerce)
```

###  Alternatives

[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.5k25.9M107](/packages/laravel-cashier)[laravel/socialite

Laravel wrapper around OAuth 1 & OAuth 2 libraries.

5.7k96.9M674](/packages/laravel-socialite)[laravel/horizon

Dashboard and code-driven configuration for Laravel queues.

4.2k84.2M225](/packages/laravel-horizon)[laravel/ui

Laravel UI utilities and presets.

2.7k134.9M599](/packages/laravel-ui)[laravel/jetstream

Tailwind scaffolding for the Laravel framework.

4.1k19.8M136](/packages/laravel-jetstream)[internachi/modular

Modularize your Laravel apps

1.1k662.4k8](/packages/internachi-modular)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)