{"id":37390260,"url":"https://github.com/miracuthbert/laravel-royalty","last_synced_at":"2026-01-16T05:29:32.265Z","repository":{"id":52253969,"uuid":"246706446","full_name":"miracuthbert/laravel-royalty","owner":"miracuthbert","description":"A user points package for Laravel that can be used to give rewards, loyalty or experience points with real time support","archived":false,"fork":false,"pushed_at":"2023-10-30T15:15:16.000Z","size":37,"stargazers_count":80,"open_issues_count":1,"forks_count":16,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-09-17T22:53:31.535Z","etag":null,"topics":["laravel","loyalty-points","miracuthbert","royalty","user-experience-points","user-points","user-rewards-points"],"latest_commit_sha":null,"homepage":null,"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/miracuthbert.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-03-12T00:13:54.000Z","updated_at":"2025-03-01T20:50:44.000Z","dependencies_parsed_at":"2022-08-22T11:31:21.857Z","dependency_job_id":null,"html_url":"https://github.com/miracuthbert/laravel-royalty","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"purl":"pkg:github/miracuthbert/laravel-royalty","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miracuthbert%2Flaravel-royalty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miracuthbert%2Flaravel-royalty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miracuthbert%2Flaravel-royalty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miracuthbert%2Flaravel-royalty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/miracuthbert","download_url":"https://codeload.github.com/miracuthbert/laravel-royalty/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/miracuthbert%2Flaravel-royalty/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28477250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T03:13:13.607Z","status":"ssl_error","status_checked_at":"2026-01-16T03:11:47.863Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":["laravel","loyalty-points","miracuthbert","royalty","user-experience-points","user-points","user-rewards-points"],"created_at":"2026-01-16T05:29:32.127Z","updated_at":"2026-01-16T05:29:32.246Z","avatar_url":"https://github.com/miracuthbert.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Laravel Royalty\n\nA user points package for Laravel that can be used to give rewards, loyalty or experience points with real time support.\n\n## How does it work?\n\nSimply every point has an action file which when called will resolve the model for a given point.\n\nThe action file is used to assign points to a user.\n\nThe reason we use action (files) is:\n\n- It makes it easy to track points.\n- It's easier to switch out points eg. you want to bump up the points a user gets on completing a lesson from `50` to `100`, you just create a new action and you replace the old one.\n\n## Installation\n\nUse composer to install the package:\n\n```\ncomposer require miracuthbert/laravel-royalty\n```\n\n## Setup\n\nThe package takes advantage of Laravel Auto-Discovery, so it doesn't require you to manually add the ServiceProvider.\n\nIf you don't use auto-discovery, add the ServiceProvider to the providers array in `config/app.php`\n\n```php\nMiracuthbert\\Royalty\\RoyaltyServiceProvider::class\n```\n\nYou must then publish the `config` and `migrations` file.\n\n### Using the Setup command\n\nYou can do all the necessary setup using the `royalty:setup` in your command console\n\n```\nphp artisan royalty:setup\n```\n\n\u003e Update the keys in \"config/royalty.php\" before migrating your database \n\u003e You can set the model to be used for points.\n\nIf you want to reset either `config` or `migrations` use the commands below in your console\n\n### Publish Config\n\n```\nphp artisan vendor:publish --provider=Miracuthbert\\Royalty\\RoyaltyServiceProvider --tag=royalty-config\n```\n\n\u003e Setup the user `model` key in config to indicate which User model to use\n\n### Publish Migrations\n\n```\nphp artisan vendor:publish --provider=Miracuthbert\\Royalty\\RoyaltyServiceProvider --tag=royalty-migrations\n```\n\n\u003e Before migrating the database make sure you setup the user `model` key in config\n\n### Publish Vue Components\n\nA simple Vue component is included to display a user's points in real-time anytime they are given points. See [Real-time](#real-time) section under usage for more.\n\n```\nphp artisan vendor:publish --provider=Miracuthbert\\Royalty\\RoyaltyServiceProvider --tag=royalty-components\n```\n\n\u003e The package does not tie you to use a specific front-end framework to listen to the fired event, so feel free to experiment \n\n## Usage\n\n### Setting the User model\n\nFirst, setup the user `model` key in the config.\n\nThen add `CollectsPoints` trait in the respective model.\n\n```php\nuse CollectsPoints;\n```\n\n### Creating Points\n\nLet's take an example of a user completing a Lesson in a course, we can create a `CompletedLesson`.\n\n#### Using Console Command\n\nYou can use the command:\n\n```\nphp artisan royalty:action CompletedLesson\n\n// with specific namespace\nphp artisan royalty:action Course\\\\CompletedLesson\n```\n\nThis will create an action file under the `Royalty\\Actions` folder in the `app` directory \nor a corresponding one as specified in the `config/royalty.php` file. \n\nIt will include:\n\n- `key` method with the unique key which will be used to identify created from the slug of the `Action` name.\n\nYou can also use these options along with the command:\n\n- `--key` to override the key generated from class name.\n- `--name` to create the point in the database (use along with the `points` option).\n- `--points` the points for the given action.\n- `--description` the description of the point.\n\n\u003e If you just created the point file only you need to create a record with reference to the action in the database.\n\nSee [Adding Points in the Database](#adding-points-in-the-database) section on adding a point in the database.\n\n#### Creating Manually\n\nTo create a point manually you need to create an `action` file and also a `record` referencing the action in the database.\n\n##### Creating the Action File\n\nTo create a point action file, you need to create a class that extends `Miracuthbert\\Royalty\\Actions\\ActionAbstract`.\n\n```php\nnamespace App\\Royalty\\Actions;\n\nuse Miracuthbert\\Royalty\\Actions\\ActionAbstract;\n\nclass CompletedLesson extends ActionAbstract\n{\n    /**\n     * Set the action key.\n     *\n     * @return mixed\n     */\n    public function key()\n    {\n        return 'completed-lesson';\n    }\n}\n```\n\n##### Adding Points in the Database\n\n```php\nuse Miracuthbert\\Royalty\\Models\\Point;\n\n$point = Point::create([\n    'name' =\u003e 'Completed Lesson',\n    'key' =\u003e 'completed-lesson',\n    'description' =\u003e 'Reward for completing a lesson',\n    'points' =\u003e 100,\n]);\n```\n\nYou can also create bulk points using, for example a seeder:\n\n```php\n$points = [\n    [\n        'name' =\u003e 'Completed Lesson',\n        'key' =\u003e 'completed-lesson',\n        'points' =\u003e 100,\n    ],\n    [\n        'name' =\u003e 'Completed Course',\n        'key' =\u003e 'completed-course',\n        'points' =\u003e 500,\n    ],\n    \n    // grouped\n    [\n        'name' =\u003e 'Grades',\n        'key' =\u003e 'grades',\n        'points' =\u003e 100,\n        'children' =\u003e [\n            [\n                'name' =\u003e 'Excellent',\n                'points' =\u003e 100,\n            ],\n            [\n                'name' =\u003e 'Very Good',\n                'points' =\u003e 90,\n            ],\n            [\n                'name' =\u003e 'Good',\n                'points' =\u003e 80,\n            ],\n        ],\n    ],\n];\n\nforeach ($points as $point) {\n    $exists = Point::where('key', $point['key'])-\u003efirst();\n\n    if (!$exists) {\n        Miracuthbert\\Royalty\\Models\\Point::create($point);\n    }\n} \n```\n\n### Giving Points\n\nTo give points, just call the `givePoints` method on an instance of a user.\n\n```php\n// user instance\n$user = User::find(1);\n$user-\u003egivePoints(new CompletedLesson());\n\n// using request user\n$request-\u003euser()-\u003egivePoints(new CompletedLesson());\n\n// using auth user\nauth()-\u003euser()-\u003egivePoints(new CompletedLesson());\n```\n\n### Getting User's Points\n\nTo get user points, just call the `points` method on an instance of a user chaining one of the following methods:\n\n- `number`: The raw points value\n- `number`: For a formatted number value, i.e `1,000`, `1,000,000`\n- `shorthand`: For a formatted string value, i.e `1k`, `10.5k`, `1m`\n\n```php\n// user instance\n$user = User::find(1);\n$user-\u003epoints()-\u003enumber();\n$user-\u003epoints()-\u003eshorthand();\n\n// using request user\n$request-\u003euser()-\u003epoints()-\u003enumber();\n$request-\u003euser()-\u003epoints()-\u003eshorthand();\n\n// using auth user\nauth()-\u003euser()-\u003epoints()-\u003enumber();\nauth()-\u003euser()-\u003epoints()-\u003eshorthand();\n```\n\n### Real-time\n\nWhenever a user is given points a `PointsGiven` event is fired.\n\n#### Broadcast Channel\n\nIt broadcasts to the `users` (private) channel as set in the `channel` key of `broadcast` in `config/royalty.php`.\n\n\u003e The channel should exist in `channels` file under routes or your respective user channel\n\nAn example of the channel route:\n\n```php\nBroadcast::channel('users.{id}', function ($user, $id) {\n    return (int) $user-\u003eid === (int) $id;\n});\n```\n\n#### Listening to the Event\n\nYou can then listen to it using the `points-given` or the set value of the `name` key under `broadcast` in `config/royalty.php`.\n\nExample using Laravel Echo with Vue.js:\n\n```vue\n    Echo.private(`users.${this.userId}`)\n        .listen('.points-given', (e) =\u003e {\n            this.point = e.point\n            this.userPoints = e.user_points\n        })\n```\n\n##### Vue Component\n\nThere is a Vue component included with the package. Use command below to publish it:\n\n```\nphp artisan vendor:publish --provider=Miracuthbert\\Royalty\\RoyaltyServiceProvider --tag=royalty-components\n```\n\nThe published component will be placed in your `resources/js/components` directory. Once the components have been published, you should register them in your `resources/js/app.js` file:\n\n```\nVue.component('royalty-badge', require('./components/royalty/RoyaltyBadge.vue').default);\n```\n\nAfter registering the component, make sure to run `npm run dev` to recompile your assets. Once you have recompiled your assets, you may drop the components into one of your application's templates to get started:\n\n```\n\u003croyalty-badge\n  :user-id=\"{{ auth()-\u003euser()-\u003eid }}\"\n  initial-points=\"{{ auth()-\u003euser()-\u003epoints()-\u003eshorthand() }}\"\n/\u003e\n```\n\n## Console Commands\n\nThere are three commands within the package:\n\n- `royalty:setup`: Used to setup the package files\n- `royalty:action`: Used to create an action file and point\n- `royalty:actions`: Used to list points and their related actions\n\n## Security Vulnerabilities\n\nIf you discover a security vulnerability, please send an e-mail to Cuthbert Mirambo via [miracuthbert@gmail.com](mailto:miracuthbert@gmail.com). All security vulnerabilities will be promptly addressed.\n\n## Credits\n\n- [Cuthbert Mirambo](https://github.com/miracuthbert)\n\n## License\n\nThe project is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiracuthbert%2Flaravel-royalty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmiracuthbert%2Flaravel-royalty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiracuthbert%2Flaravel-royalty/lists"}