PHPackages samehdoush/subscriptions - 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. samehdoush/subscriptions ActiveLibrary samehdoush/subscriptions ======================== This is my package subscriptions 1115[1 PRs](https://github.com/samehdoush/subscriptions/pulls)PHP Since Sep 4Pushed 2y ago1 watchersCompare [ Source](https://github.com/samehdoush/subscriptions)[ Packagist](https://packagist.org/packages/samehdoush/subscriptions)[ RSS](/packages/samehdoush-subscriptions/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependenciesVersions (2)Used By (0) Laravel subscriptions ===================== [](#laravel-subscriptions) [![Latest Version on Packagist](https://camo.githubusercontent.com/b4cbd79f84711ef3474e8e244f1130c9d44c96ef79170c17811b7c60505388df/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f73616d6568646f7573682f737562736372697074696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/samehdoush/subscriptions)[![GitHub Tests Action Status](https://camo.githubusercontent.com/85de408a717e8d7cedc5fb3e4e1bae8a176f2bcf8e7ea14488b67d8b89ecc517/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f73616d6568646f7573682f737562736372697074696f6e732f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/samehdoush/subscriptions/actions?query=workflow%3Arun-tests+branch%3Amain)[![GitHub Code Style Action Status](https://camo.githubusercontent.com/3da4e3e48abfe577d02260f64f9f1ceadaeafc7c216f3aa19b44413cc1d83f9b/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f73616d6568646f7573682f737562736372697074696f6e732f6669782d7068702d636f64652d7374796c652d6973737565732e796d6c3f6272616e63683d6d61696e266c6162656c3d636f64652532307374796c65267374796c653d666c61742d737175617265)](https://github.com/samehdoush/subscriptions/actions?query=workflow%3A%22Fix+PHP+code+style+issues%22+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/2b6c325566eb720727b90af1dfbce71c591f9aa265fafd07e0f15e47deeb113e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f73616d6568646f7573682f737562736372697074696f6e732e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/samehdoush/subscriptions) Laravel Subscribable is a flexible plans and subscription management system for Laravel, with the required tools to run your SAAS like services efficiently. It's simple architecture, accompanied by powerful underlying to afford solid platform for your business. Support us ---------- [](#support-us) [![](https://camo.githubusercontent.com/0d896e34364f7416484a7c67cac1c89bd6a54eb2545f62854f390ade8999d5ae/68747470733a2f2f6769746875622d6164732e73332e65752d63656e7472616c2d312e616d617a6f6e6177732e636f6d2f737562736372697074696f6e732e6a70673f743d31)](https://spatie.be/github-ad-click/subscriptions) We invest a lot of resources into creating [best in class open source packages](https://spatie.be/open-source). You can support us by [buying one of our paid products](https://spatie.be/open-source/support-us). We highly appreciate you sending us a postcard from your hometown, mentioning which of our package(s) you are using. You'll find our address on [our contact page](https://spatie.be/about-us). We publish all received postcards on [our virtual postcard wall](https://spatie.be/open-source/postcards). The idea is inspired by [rinvex/laravel-subscriptions](https://github.com/rinvex/laravel-subscriptions) ------------------------------------------------------------------------------------------------------- [](#the-idea-is-inspired-by-rinvexlaravel-subscriptions) Installation ------------ [](#installation) You can install the package via composer: ``` composer require samehdoush/subscriptions ``` Auto install ------------ [](#auto-install) ``` php artisan subscriptions:install ``` OR -- [](#or) You can publish and run the migrations with: ``` php artisan vendor:publish --tag="subscriptions-migrations" php artisan migrate ``` You can publish the config file with: ``` php artisan vendor:publish --tag="subscriptions-config" ``` This is the contents of the published config file: ``` return [ ]; ``` Optionally, you can publish the views using ``` php artisan vendor:publish --tag="subscriptions-views" ``` Usage ----- [](#usage) ``` $subscriptions = new Samehdoush\Subscriptions(); echo $subscriptions->echoPhrase('Hello, Samehdoush!'); ``` Usage ----- [](#usage-1) ### Add Subscriptions to User model [](#add-subscriptions-to-user-model) \*\* Subscriptions\*\* has been specially made for Eloquent and simplicity has been taken very serious as in any other Laravel related aspect. To add Subscription functionality to your User model just use the `\Samehdoush\Subscriptions\Traits\HasPlanSubscriptions` trait like this: ``` namespace App\Models; use Samehdoush\Subscriptions\Traits\HasPlanSubscriptions; use Illuminate\Foundation\Auth\User as Authenticatable; class User extends Authenticatable { use HasPlanSubscriptions; } ``` That's it, we only have to use that trait in our User model! Now your users may subscribe to plans. > **Note:** you can use `HasPlanSubscriptions` trait on any subscriber model, it doesn't have to be the user model, in fact any model will do. ### Create a Plan [](#create-a-plan) ``` $plan = \Samehdoush\Subscriptions\Models\Plan::create([ 'name' => 'Pro', 'description' => 'Pro plan', 'price' => 9.99, 'signup_fee' => 1.99, 'invoice_period' => 1, 'invoice_interval' => 'month', 'trial_period' => 15, 'trial_interval' => 'day', 'sort_order' => 1, 'currency' => 'USD', ]); // Create multiple plan features at once $plan->features()->saveMany([ new PlanFeature(['name' => 'listings', 'value' => 50, 'sort_order' => 1]), new PlanFeature(['name' => 'pictures_per_listing', 'value' => 10, 'sort_order' => 5]), new PlanFeature(['name' => 'listing_duration_days', 'value' => 30, 'sort_order' => 10, 'resettable_period' => 1, 'resettable_interval' => 'month']), new PlanFeature(['name' => 'listing_title_bold', 'value' => 'Y', 'sort_order' => 15]) ]); ``` ### Get Plan Details [](#get-plan-details) You can query the plan for further details, using the intuitive API as follows: ``` $plan = \Samehdoush\Subscriptions\Models\Plan::find(1); // Get all plan features $plan->features; // Get all plan subscriptions $plan->planSubscriptions; // Check if the plan is free $plan->isFree(); // Check if the plan has trial period $plan->hasTrial(); // Check if the plan has grace period $plan->hasGrace(); ``` Both `$plan->features` and `$plan->planSubscriptions` are collections, driven from relationships, and thus you can query these relations as any normal Eloquent relationship. E.g. `$plan->features()->where('name', 'listing_title_bold')->first()`. ### Get Feature Value [](#get-feature-value) Say you want to show the value of the feature *pictures\_per\_listing* from above. You can do so in many ways: ``` // Use the plan instance to get feature's value $amountOfPictures = $plan->getFeatureBySlug('pictures_per_listing')->value; // Query the feature itself directly $amountOfPictures = \Samehdoush\Subscriptions\Models\PlanFeature::where('slug', 'pictures_per_listing')->first()->value; // Get feature value through the subscription instance $amountOfPictures = \Samehdoush\Subscriptions\Models\PlanSubscription::find(1)->getFeatureValue('pictures_per_listing'); ``` ### Create a Subscription [](#create-a-subscription) You can subscribe a user to a plan by using the `newSubscription()` function available in the `HasPlanSubscriptions` trait. First, retrieve an instance of your subscriber model, which typically will be your user model and an instance of the plan your user is subscribing to. Once you have retrieved the model instance, you may use the `newSubscription` method to create the model's subscription. ``` $user = User::find(1); $plan = \Samehdoush\Subscriptions\Models\Plan::find(1); $user->newPlanSubscription('main', $plan); $user->newPlanSubscriptionWithOutTrail('main', $plan); // without trial ``` The first argument passed to `newSubscription` method should be the title of the subscription. If your application offer a single subscription, you might call this `main` or `primary`, while the second argument is the plan instance your user is subscribing to, and there's an optional third parameter to specify custom start date as an instance of `Carbon\Carbon` (by default if not provided, it will start now). ### Change the Plan [](#change-the-plan) You can change subscription plan easily as follows: ``` $plan = \Samehdoush\Subscriptions\Models\Plan::find(2); $subscription = \Samehdoush\Subscriptions\Models\PlanSubscription::find(1); // Change subscription plan $subscription->changePlan($plan); ``` If both plans (current and new plan) have the same billing frequency (e.g., `invoice_period` and `invoice_interval`) the subscription will retain the same billing dates. If the plans don't have the same billing frequency, the subscription will have the new plan billing frequency, starting on the day of the change and *the subscription usage data will be cleared*. Also if the new plan has a trial period and it's a new subscription, the trial period will be applied. ### Feature Options [](#feature-options) Plan features are great for fine-tuning subscriptions, you can top-up certain feature for X times of usage, so users may then use it only for that amount. Features also have the ability to be resettable and then it's usage could be expired too. See the following examples: ``` // Find plan feature $feature = \Samehdoush\Subscriptions\Models\PlanFeature::where('name', 'listing_duration_days')->first(); // Get feature reset date $feature->getResetDate(new \Carbon\Carbon()); ``` ### Subscription Feature Usage [](#subscription-feature-usage) There's multiple ways to determine the usage and ability of a particular feature in the user subscription, the most common one is `canUseFeature`: The `canUseFeature` method returns `true` or `false` depending on multiple factors: - Feature *is enabled*. - Feature value isn't `0`/`false`/`NULL`. - Or feature has remaining uses available. ``` $user->planSubscription('main')->canUseFeature('listings'); ``` Other feature methods on the user subscription instance are: - `getFeatureUsage`: returns how many times the user has used a particular feature. - `getFeatureRemainings`: returns available uses for a particular feature. - `getFeatureRemainingsOrText `: returns available uses for a particular feature but if -1 return text unlimited. - `getFeatureValue`: returns the feature value. > All methods share the same signature: e.g. `$user->planSubscription('main')->getFeatureUsage('listings');`. ### Record Feature Usage [](#record-feature-usage) In order to effectively use the ability methods you will need to keep track of every usage of each feature (or at least those that require it). You may use the `recordFeatureUsage` method available through the user `subscription()` method: ``` $user->planSubscription('main')->recordFeatureUsage('listings'); ``` The `recordFeatureUsage` method accept 3 parameters: the first one is the feature's name, the second one is the quantity of uses to add (default is `1`), and the third one indicates if the addition should be incremental (default behavior), when disabled the usage will be override by the quantity provided. E.g.: ``` // Increment by 2 $user->planSubscription('main')->recordFeatureUsage('listings', 2); // Override with 9 $user->planSubscription('main')->recordFeatureUsage('listings', 9, false); ``` ### Reduce Feature Usage [](#reduce-feature-usage) Reducing the feature usage is *almost* the same as incrementing it. Here we only *substract* a given quantity (default is `1`) to the actual usage: ``` $user->planSubscription('main')->reduceFeatureUsage('listings', 2); ``` ### Clear The Subscription Usage Data [](#clear-the-subscription-usage-data) ``` $user->planSubscription('main')->usage()->delete(); ``` ### Check Subscription Status [](#check-subscription-status) For a subscription to be considered active *one of the following must be `true`*: - Subscription has an active trial. - Subscription `ends_at` is in the future. ``` $user->subscribedTo($planId); ``` Alternatively you can use the following methods available in the subscription model: ``` $user->planSubscription('main')->active(); $user->planSubscription('main')->canceled(); $user->planSubscription('main')->ended(); $user->planSubscription('main')->onTrial(); ``` > Canceled subscriptions with an active trial or `ends_at` in the future are considered active. ### Renew a Subscription [](#renew-a-subscription) To renew a subscription you may use the `renew` method available in the subscription model. This will set a new `ends_at` date based on the selected plan and *will clear the usage data* of the subscription. ``` $user->planSubscription('main')->renew(); ``` *Canceled subscriptions with an ended period can't be renewed.* ### Cancel a Subscription [](#cancel-a-subscription) To cancel a subscription, simply use the `cancel` method on the user's subscription: ``` $user->planSubscription('main')->cancel(); ``` By default the subscription will remain active until the end of the period, you may pass `true` to end the subscription *immediately*: ``` $user->planSubscription('main')->cancel(true); ``` ### Scopes [](#scopes) #### Subscription Model [](#subscription-model) ``` // Get subscriptions by plan $subscriptions = \Samehdoush\Subscriptions\Models\PlanSubscription::byPlanId($plan_id)->get(); // Get bookings of the given user $user = \App\Models\User::find(1); $bookingsOfSubscriber = \Samehdoush\Subscriptions\Models\PlanSubscription::ofSubscriber($user)->get(); // Get subscriptions with trial ending in 3 days $subscriptions = \Samehdoush\Subscriptions\Models\PlanSubscription::findEndingTrial(3)->get(); // Get subscriptions with ended trial $subscriptions = \Samehdoush\Subscriptions\Models\PlanSubscription::findEndedTrial()->get(); // Get subscriptions with period ending in 3 days $subscriptions = \Samehdoush\Subscriptions\Models\PlanSubscription::findEndingPeriod(3)->get(); // Get subscriptions with ended period $subscriptions = \Samehdoush\Subscriptions\Models\PlanSubscription::findEndedPeriod()->get(); ``` ### Models [](#models) \*\* Subscriptions\*\* uses 4 models: ``` Samehdoush\Subscriptions\Models\Plan; Samehdoush\Subscriptions\Models\PlanFeature; Samehdoush\Subscriptions\Models\PlanSubscription; Samehdoush\Subscriptions\Models\PlanSubscriptionUsage; ``` Testing ------- [](#testing) ``` composer test ``` Changelog --------- [](#changelog) Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. Contributing ------------ [](#contributing) Please see [CONTRIBUTING](CONTRIBUTING.md) for details. Security Vulnerabilities ------------------------ [](#security-vulnerabilities) Please review [our security policy](../../security/policy) on how to report security vulnerabilities. Credits ------- [](#credits) - [sameh doush](https://github.com/samehdoush) - [All Contributors](../../contributors) License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 17 — LowBetter than 6% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity12 Limited adoption so far Community10 Small or concentrated contributor base Maturity23 Early-stage or recently created project Bus Factor1 Top contributor holds 96.2% 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. ### Community Maintainers ![](https://www.gravatar.com/avatar/2c15e375de9134defa30a075f635514e7b5d27af9bdb0c63a156273da5995e10?d=identicon)[samehdoush](/maintainers/samehdoush) --- Top Contributors [![samehdoush](https://avatars.githubusercontent.com/u/48515888?v=4)](https://github.com/samehdoush "samehdoush (50 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")[![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4)](https://github.com/github-actions[bot] "github-actions[bot] (1 commits)") ### Embed Badge ![Health badge](/badges/samehdoush-subscriptions/health.svg) ``` [![Health](https://phpackages.com/badges/samehdoush-subscriptions/health.svg)](https://phpackages.com/packages/samehdoush-subscriptions) ``` PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)