PHPackages                             ahmedessam/sub-sphere - 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. [Payment Processing](/categories/payments)
4. /
5. ahmedessam/sub-sphere

ActiveLibrary[Payment Processing](/categories/payments)

ahmedessam/sub-sphere
=====================

A scalable, modular, and cleanly-structured Laravel package to manage subscription plans, pricing, features, and usage

v1.6.0(9mo ago)014MITPHPPHP ^8.1

Since Jul 1Pushed 9mo agoCompare

[ Source](https://github.com/aahmedessam30/sub-sphere)[ Packagist](https://packagist.org/packages/ahmedessam/sub-sphere)[ Docs](https://github.com/ahmedessam30/sub-sphere)[ RSS](/packages/ahmedessam-sub-sphere/feed)WikiDiscussions main Synced 1mo ago

READMEChangelog (9)Dependencies (8)Versions (10)Used By (0)

🌐 SubSphere
===========

[](#-subsphere)

[![Latest Version on Packagist](https://camo.githubusercontent.com/c7abeb910bb3444dc3ad3fd809c1268e2933ab75354841a426c56379ebee2162/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f61686d6564657373616d2f7375622d7370686572652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ahmedessam/sub-sphere)[![Total Downloads](https://camo.githubusercontent.com/27a8a41e6c35bfd5ebc949de19dcc8d2e0b5cccaebf0f2681bf5ba241511bcb8/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f61686d6564657373616d2f7375622d7370686572652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ahmedessam/sub-sphere)[![License](https://camo.githubusercontent.com/edfb405feb5bf6ceb1c21a5b2e44e5bd3c222c7cac4a6fce783acdd7c130fb16/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f61686d6564657373616d2f7375622d7370686572652e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/ahmedessam/sub-sphere)

A **headless Laravel subscription management package** that provides a complete, scalable, and modular solution for managing subscription plans, pricing, features, and usage tracking.

✨ Features
----------

[](#-features)

### 🎯 **Core Subscription Management**

[](#-core-subscription-management)

- **Multi-tier Plans** - Create unlimited subscription plans with flexible pricing options
- **Trial Support** - Separate trial subscriptions or trial periods within paid plans
- **Subscription Lifecycle** - Complete handling of start, cancel, resume, expire, and renewal
- **Grace Period** - Configurable grace periods after subscription expiry
- **Auto-renewal** - Automatic subscription renewal with payment integration hooks

### 📊 **Feature Usage & Limits**

[](#-feature-usage--limits)

- **Usage Tracking** - Track feature consumption with intelligent limit enforcement
- **Reset Behaviors** - Daily, monthly, yearly, or never-resetting usage limits
- **Flexible Features** - Boolean flags, numeric limits, or custom feature values
- **Real-time Validation** - Instant feature availability and usage checking

### 🌍 **Multi-language & Currency**

[](#-multi-language--currency)

- **Translation Support** - Full integration with Spatie Laravel Translatable
- **Multi-currency Pricing** - Support for multiple currencies with automatic fallbacks
- **Localized Content** - Translatable plan names, descriptions, and feature labels

### 🏗️ **Architecture & Design**

[](#️-architecture--design)

- **Fully Headless** - Backend-only package with no UI dependencies
- **Clean Architecture** - Models, Traits, Actions, Services, Events, Commands separation
- **Event-driven** - Comprehensive event system for extensibility
- **Database Agnostic** - Works with MySQL, PostgreSQL, SQLite, and more

### 🔧 **Developer Experience**

[](#-developer-experience)

- **Artisan Commands** - Automated expiration, renewal, and usage reset commands
- **Laravel Scheduler** - Built-in support for background task automation
- **Comprehensive Testing** - Full test coverage for reliability

---

📋 Requirements
--------------

[](#-requirements)

- **PHP**: 8.1 or higher
- **Laravel**: 9.0 or higher
- **Database**: MySQL 5.7+ / PostgreSQL 9.6+ / SQLite 3.8+ / SQL Server 2017+

---

� Installation
--------------

[](#-installation)

Install the package via Composer:

```
composer require ahmedessam/sub-sphere
```

### Publish Configuration & Migrations

[](#publish-configuration--migrations)

```
# Publish config file
php artisan vendor:publish --tag="sub-sphere-config"

# Publish migrations
php artisan vendor:publish --tag="sub-sphere-migrations"

# Run migrations
php artisan migrate
```

### Publish Translations (Optional)

[](#publish-translations-optional)

```
# Publish language files for customization
php artisan vendor:publish --tag="sub-sphere-translations"
```

---

⚙️ Configuration
----------------

[](#️-configuration)

The configuration file `config/sub-sphere.php` allows you to customize:

```
return [
    // Grace period after subscription expiry (days)
    'grace_period_days' => env('SUBSPHERE_GRACE_PERIOD_DAYS', 3),

    // Default trial period (days)
    'trial_period_days' => env('SUBSPHERE_TRIAL_PERIOD_DAYS', 14),

    // Auto-renewal default setting
    'auto_renewal_default' => env('SUBSPHERE_AUTO_RENEWAL_DEFAULT', true),

    // Multi-currency settings
    'currency' => [
        'default' => env('SUBSPHERE_DEFAULT_CURRENCY', 'USD'),
        'supported_currencies' => ['USD', 'EUR', 'GBP', 'EGP'],
    ],

    // Plan change behavior
    'plan_changes' => [
        'allow_downgrades' => env('SUBSPHERE_ALLOW_DOWNGRADES', true),
        'reset_usage_on_plan_change' => env('SUBSPHERE_RESET_USAGE_ON_PLAN_CHANGE', true),
    ],
];
```

---

🎯 Quick Start
-------------

[](#-quick-start)

### 1. Add the Trait to Your User Model

[](#1-add-the-trait-to-your-user-model)

```