PHPackages                             miracuthbert/laravel-royalty - 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. [Utility & Helpers](/categories/utility)
4. /
5. miracuthbert/laravel-royalty

ActiveLibrary[Utility & Helpers](/categories/utility)

miracuthbert/laravel-royalty
============================

A user points package for Laravel that can be used to give rewards, loyalty or experience points with real time support

1.4.0(2y ago)825.1k↓42.9%17[1 issues](https://github.com/miracuthbert/laravel-royalty/issues)MITPHPPHP ^7.3|^8.0

Since Feb 23Pushed 2y ago3 watchersCompare

[ Source](https://github.com/miracuthbert/laravel-royalty)[ Packagist](https://packagist.org/packages/miracuthbert/laravel-royalty)[ RSS](/packages/miracuthbert-laravel-royalty/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (6)Dependencies (9)Versions (7)Used By (0)

Laravel Royalty
===============

[](#laravel-royalty)

A user points package for Laravel that can be used to give rewards, loyalty or experience points with real time support.

How does it work?
-----------------

[](#how-does-it-work)

Simply every point has an action file which when called will resolve the model for a given point.

The action file is used to assign points to a user.

The reason we use action (files) is:

- It makes it easy to track points.
- 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.

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

[](#installation)

Use composer to install the package:

```
composer require miracuthbert/laravel-royalty

```

Setup
-----

[](#setup)

The package takes advantage of Laravel Auto-Discovery, so it doesn't require you to manually add the ServiceProvider.

If you don't use auto-discovery, add the ServiceProvider to the providers array in `config/app.php`

```
Miracuthbert\Royalty\RoyaltyServiceProvider::class
```

You must then publish the `config` and `migrations` file.

### Using the Setup command

[](#using-the-setup-command)

You can do all the necessary setup using the `royalty:setup` in your command console

```
php artisan royalty:setup

```

> Update the keys in "config/royalty.php" before migrating your database You can set the model to be used for points.

If you want to reset either `config` or `migrations` use the commands below in your console

### Publish Config

[](#publish-config)

```
php artisan vendor:publish --provider=Miracuthbert\Royalty\RoyaltyServiceProvider --tag=royalty-config

```

> Setup the user `model` key in config to indicate which User model to use

### Publish Migrations

[](#publish-migrations)

```
php artisan vendor:publish --provider=Miracuthbert\Royalty\RoyaltyServiceProvider --tag=royalty-migrations

```

> Before migrating the database make sure you setup the user `model` key in config

### Publish Vue Components

[](#publish-vue-components)

A 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.

```
php artisan vendor:publish --provider=Miracuthbert\Royalty\RoyaltyServiceProvider --tag=royalty-components

```

> The package does not tie you to use a specific front-end framework to listen to the fired event, so feel free to experiment

Usage
-----

[](#usage)

### Setting the User model

[](#setting-the-user-model)

First, setup the user `model` key in the config.

Then add `CollectsPoints` trait in the respective model.

```
use CollectsPoints;
```

### Creating Points

[](#creating-points)

Let's take an example of a user completing a Lesson in a course, we can create a `CompletedLesson`.

#### Using Console Command

[](#using-console-command)

You can use the command:

```
php artisan royalty:action CompletedLesson

// with specific namespace
php artisan royalty:action Course\\CompletedLesson

```

This will create an action file under the `Royalty\Actions` folder in the `app` directory or a corresponding one as specified in the `config/royalty.php` file.

It will include:

- `key` method with the unique key which will be used to identify created from the slug of the `Action` name.

You can also use these options along with the command:

- `--key` to override the key generated from class name.
- `--name` to create the point in the database (use along with the `points` option).
- `--points` the points for the given action.
- `--description` the description of the point.

> If you just created the point file only you need to create a record with reference to the action in the database.

See [Adding Points in the Database](#adding-points-in-the-database) section on adding a point in the database.

#### Creating Manually

[](#creating-manually)

To create a point manually you need to create an `action` file and also a `record` referencing the action in the database.

##### Creating the Action File

[](#creating-the-action-file)

To create a point action file, you need to create a class that extends `Miracuthbert\Royalty\Actions\ActionAbstract`.

```
namespace App\Royalty\Actions;

use Miracuthbert\Royalty\Actions\ActionAbstract;

class CompletedLesson extends ActionAbstract
{
    /**
     * Set the action key.
     *
     * @return mixed
     */
    public function key()
    {
        return 'completed-lesson';
    }
}
```

##### Adding Points in the Database

[](#adding-points-in-the-database)

```
use Miracuthbert\Royalty\Models\Point;

$point = Point::create([
    'name' => 'Completed Lesson',
    'key' => 'completed-lesson',
    'description' => 'Reward for completing a lesson',
    'points' => 100,
]);
```

You can also create bulk points using, for example a seeder:

```
$points = [
    [
        'name' => 'Completed Lesson',
        'key' => 'completed-lesson',
        'points' => 100,
    ],
    [
        'name' => 'Completed Course',
        'key' => 'completed-course',
        'points' => 500,
    ],

    // grouped
    [
        'name' => 'Grades',
        'key' => 'grades',
        'points' => 100,
        'children' => [
            [
                'name' => 'Excellent',
                'points' => 100,
            ],
            [
                'name' => 'Very Good',
                'points' => 90,
            ],
            [
                'name' => 'Good',
                'points' => 80,
            ],
        ],
    ],
];

foreach ($points as $point) {
    $exists = Point::where('key', $point['key'])->first();

    if (!$exists) {
        Miracuthbert\Royalty\Models\Point::create($point);
    }
}
```

### Giving Points

[](#giving-points)

To give points, just call the `givePoints` method on an instance of a user.

```
// user instance
$user = User::find(1);
$user->givePoints(new CompletedLesson());

// using request user
$request->user()->givePoints(new CompletedLesson());

// using auth user
auth()->user()->givePoints(new CompletedLesson());
```

### Getting User's Points

[](#getting-users-points)

To get user points, just call the `points` method on an instance of a user chaining one of the following methods:

- `number`: The raw points value
- `number`: For a formatted number value, i.e `1,000`, `1,000,000`
- `shorthand`: For a formatted string value, i.e `1k`, `10.5k`, `1m`

```
// user instance
$user = User::find(1);
$user->points()->number();
$user->points()->shorthand();

// using request user
$request->user()->points()->number();
$request->user()->points()->shorthand();

// using auth user
auth()->user()->points()->number();
auth()->user()->points()->shorthand();
```

### Real-time

[](#real-time)

Whenever a user is given points a `PointsGiven` event is fired.

#### Broadcast Channel

[](#broadcast-channel)

It broadcasts to the `users` (private) channel as set in the `channel` key of `broadcast` in `config/royalty.php`.

> The channel should exist in `channels` file under routes or your respective user channel

An example of the channel route:

```
Broadcast::channel('users.{id}', function ($user, $id) {
    return (int) $user->id === (int) $id;
});
```

#### Listening to the Event

[](#listening-to-the-event)

You can then listen to it using the `points-given` or the set value of the `name` key under `broadcast` in `config/royalty.php`.

Example using Laravel Echo with Vue.js:

```
    Echo.private(`users.${this.userId}`)
        .listen('.points-given', (e) => {
            this.point = e.point
            this.userPoints = e.user_points
        })
```

##### Vue Component

[](#vue-component)

There is a Vue component included with the package. Use command below to publish it:

```
php artisan vendor:publish --provider=Miracuthbert\Royalty\RoyaltyServiceProvider --tag=royalty-components

```

The 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:

```
Vue.component('royalty-badge', require('./components/royalty/RoyaltyBadge.vue').default);

```

After 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:

```

```

Console Commands
----------------

[](#console-commands)

There are three commands within the package:

- `royalty:setup`: Used to setup the package files
- `royalty:action`: Used to create an action file and point
- `royalty:actions`: Used to list points and their related actions

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

If you discover a security vulnerability, please send an e-mail to Cuthbert Mirambo via . All security vulnerabilities will be promptly addressed.

Credits
-------

[](#credits)

- [Cuthbert Mirambo](https://github.com/miracuthbert)

License
-------

[](#license)

The project is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

###  Health Score

38

—

LowBetter than 85% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity38

Limited adoption so far

Community15

Small or concentrated contributor base

Maturity66

Established project with proven stability

 Bus Factor1

Top contributor holds 63.6% 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 ~269 days

Recently: every ~286 days

Total

6

Last Release

925d ago

PHP version history (3 changes)v1.0.0PHP ^7.1.3

1.1.1PHP >=7.3.0

1.3.0PHP ^7.3|^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/6a7cd612359c9e02072f9270834f3cddf8de0464cf1b6313b6b2aa9ab95a0df6?d=identicon)[miracuthbert](/maintainers/miracuthbert)

---

Top Contributors

[![miracuthbert](https://avatars.githubusercontent.com/u/13046285?v=4)](https://github.com/miracuthbert "miracuthbert (7 commits)")[![gogl92](https://avatars.githubusercontent.com/u/1505641?v=4)](https://github.com/gogl92 "gogl92 (4 commits)")

---

Tags

laravelloyalty-pointsmiracuthbertroyaltyuser-experience-pointsuser-pointsuser-rewards-pointslaravelmiracuthbertroyaltyloyalty-pointsuser-pointsuser-experience-pointsuser-rewards-points

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/miracuthbert-laravel-royalty/health.svg)

```
[![Health](https://phpackages.com/badges/miracuthbert-laravel-royalty/health.svg)](https://phpackages.com/packages/miracuthbert-laravel-royalty)
```

###  Alternatives

[barryvdh/laravel-ide-helper

Laravel IDE Helper, generates correct PHPDocs for all Facade classes, to improve auto-completion.

14.9k123.0M687](/packages/barryvdh-laravel-ide-helper)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k12.1M99](/packages/laravel-pulse)[spatie/laravel-enum

Laravel Enum support

3655.4M31](/packages/spatie-laravel-enum)[psalm/plugin-laravel

Psalm plugin for Laravel

3274.9M308](/packages/psalm-plugin-laravel)[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)

PHPackages © 2026

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