{"id":22239009,"url":"https://github.com/laravelcm/laravel-subscriptions","last_synced_at":"2025-12-30T09:24:14.381Z","repository":{"id":197832997,"uuid":"699255056","full_name":"laravelcm/laravel-subscriptions","owner":"laravelcm","description":"Laravel Subscriptions is a flexible plans and subscription management system for Laravel.","archived":false,"fork":false,"pushed_at":"2024-11-01T20:50:02.000Z","size":450,"stargazers_count":126,"open_issues_count":7,"forks_count":20,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-12-02T09:57:14.954Z","etag":null,"topics":["subscription","subscription-management"],"latest_commit_sha":null,"homepage":"","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laravelcm.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"mckenziearts"}},"created_at":"2023-10-02T09:05:45.000Z","updated_at":"2024-11-30T18:40:49.000Z","dependencies_parsed_at":"2024-07-22T10:36:33.266Z","dependency_job_id":"26eb9f7a-2d15-41d7-9b64-739d77ef06be","html_url":"https://github.com/laravelcm/laravel-subscriptions","commit_stats":null,"previous_names":["laravelcm/laravel-subscriptions"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laravelcm%2Flaravel-subscriptions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laravelcm%2Flaravel-subscriptions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laravelcm%2Flaravel-subscriptions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laravelcm%2Flaravel-subscriptions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laravelcm","download_url":"https://codeload.github.com/laravelcm/laravel-subscriptions/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227843591,"owners_count":17827999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["subscription","subscription-management"],"created_at":"2024-12-03T03:17:33.348Z","updated_at":"2025-12-30T09:24:14.344Z","avatar_url":"https://github.com/laravelcm.png","language":"PHP","funding_links":["https://github.com/sponsors/mckenziearts"],"categories":["Plugins List"],"sub_categories":["Filament Sticky Notes"],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://github.com/laravelcm/laravel.cm/raw/main/art/logo.svg\" height=\"250\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003ca href=\"https://laravel.com\"\u003e\n        \u003cimg alt=\"Laravel v10.x\" src=\"https://img.shields.io/badge/Laravel-v10.x-FF2D20\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/laravelcm/laravel-subscriptions/actions\"\u003e\n        \u003cimg src=\"https://github.com/laravelcm/laravel-subscriptions/workflows/Tests/badge.svg\" alt=\"Build Status\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/laravelcm/laravel-subscriptions/actions/workflows/pint.yml\"\u003e\n        \u003cimg src=\"https://github.com/laravelcm/laravel-subscriptions/actions/workflows/pint.yml/badge.svg\" alt=\"Coding Standards\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://packagist.org/packages/laravelcm/laravel-subscriptions\"\u003e\n        \u003cimg src=\"https://img.shields.io/packagist/dt/laravelcm/laravel-subscriptions\" alt=\"Total Downloads\"\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://packagist.org/packages/laravelcm/laravel-subscriptions\"\u003e\n        \u003cimg src=\"https://img.shields.io/packagist/v/laravelcm/laravel-subscriptions.svg?label=Packagist\" alt=\"Packagist\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://github.com/laravelcm/laravel-subscriptions/blob/main/LICENSE\"\u003e\n        \u003cimg src=\"https://img.shields.io/packagist/l/laravelcm/laravel-subscriptions.svg?label=License\" alt=\"Packagist\" /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n# Laravel Subscriptions\n\n**Laravel Subscriptions** is a flexible plans and subscription management system for Laravel, with the required tools to run your SAAS like services efficiently. \nIt's simple architecture, accompanied by powerful underlying to afford solid platform for your business.\n\n## Considerations\n\n- Payments are out of scope for this package.\n- You may want to extend some of the core models, in case you need to override the logic behind some helper methods like `renew()`, `cancel()` etc. E.g.: when cancelling a subscription you may want to also cancel the recurring payment attached.\n\n\n## Installation\n\n1. Install the package via composer:\n    ```shell\n    composer require laravelcm/laravel-subscriptions\n    ```\n\n2. Publish resources (migrations and config files):\n    ```shell\n    php artisan vendor:publish --provider=\"Laravelcm\\Subscriptions\\SubscriptionServiceProvider\"\n    ```\n\n3. Execute migrations via the following command:\n    ```shell\n    php artisan migrate\n    ```\n\n4. Done!\n\n\n## Usage\n\n### Add Subscriptions to User model\n\n**Laravel 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 `\\Rinvex\\Subscriptions\\Traits\\HasPlanSubscriptions` trait like this:\n\n```php\nnamespace App\\Models;\n\nuse Laravelcm\\Subscriptions\\Traits\\HasPlanSubscriptions;\nuse Illuminate\\Foundation\\Auth\\User as Authenticatable;\n\nclass User extends Authenticatable\n{\n    use HasPlanSubscriptions;\n}\n```\n\nThat's it, we only have to use that trait in our User model! Now your users may subscribe to plans.\n\n\u003e **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.\n\n### Create a Plan\n\n```php\nuse Laravelcm\\Subscriptions\\Models\\Plan;\nuse Laravelcm\\Subscriptions\\Models\\Feature;\nuse Laravelcm\\Subscriptions\\Interval;\n\n$plan = Plan::create([\n    'name' =\u003e 'Pro',\n    'description' =\u003e 'Pro plan',\n    'price' =\u003e 9.99,\n    'signup_fee' =\u003e 1.99,\n    'invoice_period' =\u003e 1,\n    'invoice_interval' =\u003e Interval::MONTH-\u003evalue,\n    'trial_period' =\u003e 15,\n    'trial_interval' =\u003e Interval::DAY-\u003evalue,\n    'sort_order' =\u003e 1,\n    'currency' =\u003e 'USD',\n]);\n\n// Create multiple plan features at once\n$plan-\u003efeatures()-\u003esaveMany([\n    new Feature(['name' =\u003e 'listings', 'value' =\u003e 50, 'sort_order' =\u003e 1]),\n    new Feature(['name' =\u003e 'pictures_per_listing', 'value' =\u003e 10, 'sort_order' =\u003e 5]),\n    new Feature(['name' =\u003e 'listing_duration_days', 'value' =\u003e 30, 'sort_order' =\u003e 10, 'resettable_period' =\u003e 1, 'resettable_interval' =\u003e 'month']),\n    new Feature(['name' =\u003e 'listing_title_bold', 'value' =\u003e 'Y', 'sort_order' =\u003e 15])\n]);\n```\n\n### Get Plan Details\n\nYou can query the plan for further details, using the intuitive API as follows:\n\n```php\nuse Laravelcm\\Subscriptions\\Models\\Plan;\n\n$plan = Plan::find(1);\n\n// Get all plan features                \n$plan-\u003efeatures;\n\n// Get all plan subscriptions\n$plan-\u003esubscriptions;\n\n// Check if the plan is free\n$plan-\u003eisFree();\n\n// Check if the plan has trial period\n$plan-\u003ehasTrial();\n\n// Check if the plan has grace period\n$plan-\u003ehasGrace();\n```\n\nBoth `$plan-\u003efeatures` and `$plan-\u003esubscriptions` are collections, driven from relationships, and thus you can query these relations as any normal Eloquent relationship. E.g. `$plan-\u003efeatures()-\u003ewhere('name', 'listing_title_bold')-\u003efirst()`.\n\n### Get Feature Value\n\nSay you want to show the value of the feature _pictures_per_listing_ from above. You can do so in many ways:\n\n```php\nuse Laravelcm\\Subscriptions\\Models\\Feature;\nuse Laravelcm\\Subscriptions\\Models\\Subscription;\n\n// Use the plan instance to get feature's value\n$amountOfPictures = $plan-\u003egetFeatureBySlug('pictures_per_listing')-\u003evalue;\n\n// Query the feature itself directly\n$amountOfPictures = Feature::where('slug', 'pictures_per_listing')-\u003efirst()-\u003evalue;\n\n// Get feature value through the subscription instance\n$amountOfPictures = Subscription::find(1)-\u003egetFeatureValue('pictures_per_listing');\n```\n\n### Create a Subscription\n\nYou 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.\n\n```php\nuse Laravelcm\\Subscriptions\\Models\\Plan;\nuse App\\Models\\User;\n\n$user = User::find(1);\n$plan = Plan::find(1);\n\n$user-\u003enewPlanSubscription('main', $plan);\n```\n\nThe 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).\n\n### Change the Plan\n\nYou can change subscription plan easily as follows:\n\n```php\nuse Laravelcm\\Subscriptions\\Models\\Plan;\nuse Laravelcm\\Subscriptions\\Models\\Subscription;\n\n$plan = Plan::find(2);\n$subscription = Subscription::find(1);\n\n// Change subscription plan\n$subscription-\u003echangePlan($plan);\n```\n\nIf 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.\n\n### Feature Options\n\nPlan 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:\n\n```php\nuse Laravelcm\\Subscriptions\\Models\\Feature;\n\n// Find plan feature\n$feature = Feature::where('name', 'listing_duration_days')-\u003efirst();\n\n// Get feature reset date\n$feature-\u003egetResetDate(new \\Carbon\\Carbon());\n```\n\n### Subscription Feature Usage\n\nThere's multiple ways to determine the usage and ability of a particular feature in the user subscription, the most common one is `canUseFeature`:\n\nThe `canUseFeature` method returns `true` or `false` depending on multiple factors:\n\n- Feature _is enabled_.\n- Feature value isn't `0`/`false`/`NULL`.\n- Or feature has remaining uses available.\n\n```php\n$user-\u003eplanSubscription('main')-\u003ecanUseFeature('listings');\n```\n\nOther feature methods on the user subscription instance are:\n\n- `getFeatureUsage`: returns how many times the user has used a particular feature.\n- `getFeatureRemainings`: returns available uses for a particular feature.\n- `getFeatureValue`: returns the feature value.\n\n\u003e All methods share the same signature: e.g. `$user-\u003eplanSubscription('main')-\u003egetFeatureUsage('listings');`.\n\n### Record Feature Usage\n\nIn 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:\n\n```php\n$user-\u003eplanSubscription('main')-\u003erecordFeatureUsage('listings');\n```\n\nThe `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.:\n\n```php\n// Increment by 2\n$user-\u003eplanSubscription('main')-\u003erecordFeatureUsage('listings', 2);\n\n// Override with 9\n$user-\u003eplanSubscription('main')-\u003erecordFeatureUsage('listings', 9, false);\n```\n\n### Reduce Feature Usage\n\nReducing the feature usage is _almost_ the same as incrementing it. Here we only _substract_ a given quantity (default is `1`) to the actual usage:\n\n```php\n$user-\u003eplanSubscription('main')-\u003ereduceFeatureUsage('listings', 2);\n```\n\n### Clear The Subscription Usage Data\n\n```php\n$user-\u003eplanSubscription('main')-\u003eusage()-\u003edelete();\n```\n\n### Check Subscription Status\n\nFor a subscription to be considered active _one of the following must be `true`_:\n\n- Subscription has an active trial.\n- Subscription `ends_at` is in the future.\n\n```php\n$user-\u003esubscribedTo($planId);\n```\n\nAlternatively you can use the following methods available in the subscription model:\n\n```php\n$user-\u003eplanSubscription('main')-\u003eactive();\n$user-\u003eplanSubscription('main')-\u003ecanceled();\n$user-\u003eplanSubscription('main')-\u003eended();\n$user-\u003eplanSubscription('main')-\u003eonTrial();\n```\n\n\u003e Canceled subscriptions with an active trial or `ends_at` in the future are considered active.\n\n### Renew a Subscription\n\nTo 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.\n\n```php\n$user-\u003eplanSubscription('main')-\u003erenew();\n```\n\n_Canceled subscriptions with an ended period can't be renewed._\n\n### Cancel a Subscription\n\nTo cancel a subscription, simply use the `cancel` method on the user's subscription:\n\n```php\n$user-\u003eplanSubscription('main')-\u003ecancel();\n```\n\nBy default the subscription will remain active until the end of the period, you may pass `true` to end the subscription _immediately_:\n\n```php\n$user-\u003eplanSubscription('main')-\u003ecancel(true);\n```\n\n### Scopes\n\n#### Subscription Model\n\n```php\nuse Laravelcm\\Subscriptions\\Models\\Subscription;\nuse App\\Models\\User;\n\n// Get subscriptions by plan\n$subscriptions = Subscription::byPlanId($plan_id)-\u003eget();\n\n// Get bookings of the given user\n$user = User::find(1);\n$bookingsOfSubscriber = Subscription::ofSubscriber($user)-\u003eget(); \n\n// Get subscriptions with trial ending in 3 days\n$subscriptions = Subscription::findEndingTrial(3)-\u003eget();\n\n// Get subscriptions with ended trial\n$subscriptions = Subscription::findEndedTrial()-\u003eget();\n\n// Get subscriptions with period ending in 3 days\n$subscriptions = Subscription::findEndingPeriod(3)-\u003eget();\n\n// Get subscriptions with ended period\n$subscriptions = Subscription::findEndedPeriod()-\u003eget();\n```\n\n### Models\n\n**Laravel Subscriptions** uses 4 models:\n\n```php\nLaravelcm\\Subscriptions\\Models\\Plan;\nLaravelcm\\Subscriptions\\Models\\Feature;\nLaravelcm\\Subscriptions\\Models\\Subscription;\nLaravelcm\\Subscriptions\\Models\\SubscriptionUsage;\n```\n\n## Changelog\n\nRefer to the [Changelog](CHANGELOG.md) for a full history of the project.\n\n\n## Support\n\nThe following support channels are available at your fingertips:\n\n- [Chat on Telegram](https://laravel.cm/telegram)\n- [Help on Email](mailto:developers@laravel.cm)\n- [Follow on Twitter](https://twitter.com/laravelcm)\n\n\n## Contributing \u0026 Protocols\n\nThank you for considering contributing to this project! The contribution guide can be found in [CONTRIBUTING.md](CONTRIBUTING.md).\n\nBug reports, feature requests, and pull requests are very welcome.\n\n- [Versioning](CONTRIBUTING.md#versioning)\n- [Pull Requests](CONTRIBUTING.md#pull-requests)\n- [Coding Standards](CONTRIBUTING.md#coding-standards)\n- [Feature Requests](CONTRIBUTING.md#feature-requests)\n- [Git Flow](CONTRIBUTING.md#git-flow)\n\n\n## Security Vulnerabilities\n\nIf you discover a security vulnerability within this project, please send an e-mail to [developers@laravel.cm](help@rinvex.com). All security vulnerabilities will be promptly addressed.\n\n\n## About Laravel Cameroon\n\nThe community of PHP and Laravel developers in Cameroon, the largest gathering of developers in Cameroon.\n\n\n## License\n\nThis software is released under [The MIT License (MIT)](LICENSE).\n\n(c) 2018-2023 Laravel Cameroun, Some rights reserved.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaravelcm%2Flaravel-subscriptions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaravelcm%2Flaravel-subscriptions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaravelcm%2Flaravel-subscriptions/lists"}