PHPackages                             viveksingh/level-up - 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. viveksingh/level-up

ActiveLibrary

viveksingh/level-up
===================

This package allows users to gain experience points (XP) and progress through levels by performing actions on your site. It can provide a simple way to track user progress and implement gamification elements into your application

1.6(2y ago)01.6kMITPHPPHP ^8.1

Since Sep 29Pushed 2y agoCompare

[ Source](https://github.com/viveksinghhestabit/level-up)[ Packagist](https://packagist.org/packages/viveksingh/level-up)[ Docs](https://github.com/cjmellor/level-up)[ RSS](/packages/viveksingh-level-up/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (12)Versions (8)Used By (0)

[![Latest Version on Packagist](https://camo.githubusercontent.com/9069b0a2624ec9739dbdd17b1e26310dbcdbd3d4bbb8ebb572d862ed4baac885/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f636a6d656c6c6f722f6c6576656c2d75703f636f6c6f723d7267622532383536253230313839253230323438253239266c6162656c3d72656c65617365267374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/cjmellor/level-up)[![GitHub Tests Action Status](https://camo.githubusercontent.com/eba42a8934a069636bf1ab9d6cc60b6955cd0ad65bc5dd1647af7bc6dc329b4a/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f636a6d656c6c6f722f6c6576656c2d75702f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666f722d7468652d626164676526636f6c6f723d726762253238313334253230323339253230313238253239)](https://github.com/cjmellor/level-up/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/2a5bd120197b3883b1a92b864a66b1c4999ef9a2c2fc287382765093143cdf5e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f636a6d656c6c6f722f6c6576656c2d75702e7376673f636f6c6f723d7267622532383234392532303131352532303232253239267374796c653d666f722d7468652d6261646765)](https://packagist.org/packages/cjmellor/level-up)[![Packagist PHP Version](https://camo.githubusercontent.com/c3bf406e99a5388d6d84bba57a6a0683616f86518486613d91d20c5780457f0b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f636a6d656c6c6f722f6c6576656c2d75702f7068703f636f6c6f723d726762253238313635253230313830253230323532253239266c6f676f3d706870266c6f676f436f6c6f723d726762253238313635253230313830253230323532253239267374796c653d666f722d7468652d6261646765)](https://camo.githubusercontent.com/c3bf406e99a5388d6d84bba57a6a0683616f86518486613d91d20c5780457f0b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f636a6d656c6c6f722f6c6576656c2d75702f7068703f636f6c6f723d726762253238313635253230313830253230323532253239266c6f676f3d706870266c6f676f436f6c6f723d726762253238313635253230313830253230323532253239267374796c653d666f722d7468652d6261646765)[![Laravel Version](https://camo.githubusercontent.com/e4311e0cf130f34079ec9753e275d50884bd45a0185f13c6267f00edcdd3cd3b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d25354531302d7267622832333525323036382532303530293f7374796c653d666f722d7468652d6261646765266c6f676f3d6c61726176656c)](https://camo.githubusercontent.com/e4311e0cf130f34079ec9753e275d50884bd45a0185f13c6267f00edcdd3cd3b/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d25354531302d7267622832333525323036382532303530293f7374796c653d666f722d7468652d6261646765266c6f676f3d6c61726176656c)

This package allows users to gain experience points (XP) and progress through levels by performing actions on your site. It can provide a simple way to track user progress and implement gamification elements into your application

[![Banner](https://camo.githubusercontent.com/841a8f1927c71edd85504ce5c0c4b34282659ce18e0512c1afefe160e3df3cc1/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f4c6576656c25323055702e706e673f7468656d653d6461726b267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d636a6d656c6c6f722532466c6576656c2d7570267061747465726e3d746963546163546f65267374796c653d7374796c655f31266465736372697074696f6e3d456e61626c652b67616d696669636174696f6e2b7669612b58502532432b6c6576656c732532432b6c6561646572626f617264732532432b616368696576656d656e74732532432b616e642b64796e616d69632b6d756c7469706c69657273266d643d312673686f7757617465726d61726b3d3026666f6e7453697a653d313030707826696d616765733d70757a7a6c65267769647468733d6175746f)](https://camo.githubusercontent.com/841a8f1927c71edd85504ce5c0c4b34282659ce18e0512c1afefe160e3df3cc1/68747470733a2f2f62616e6e6572732e6265796f6e64636f2e64652f4c6576656c25323055702e706e673f7468656d653d6461726b267061636b6167654d616e616765723d636f6d706f7365722b72657175697265267061636b6167654e616d653d636a6d656c6c6f722532466c6576656c2d7570267061747465726e3d746963546163546f65267374796c653d7374796c655f31266465736372697074696f6e3d456e61626c652b67616d696669636174696f6e2b7669612b58502532432b6c6576656c732532432b6c6561646572626f617264732532432b616368696576656d656e74732532432b616e642b64796e616d69632b6d756c7469706c69657273266d643d312673686f7757617465726d61726b3d3026666f6e7453697a653d313030707826696d616765733d70757a7a6c65267769647468733d6175746f)

Installation
============

[](#installation)

You can install the package via composer:

```
composer require cjmellor/level-up

```

You can publish and run the migrations with:

```
php artisan vendor:publish --tag="level-up-migrations"
php artisan migrate

```

You can publish the config file with:

```
php artisan vendor:publish --tag="level-up-config"

```

This is the contents of the published config file:

```
return [
    /*
    |--------------------------------------------------------------------------
    | User Foreign Key
    |--------------------------------------------------------------------------
    |
    | This value is the foreign key that will be used to relate the Experience model to the User model.
    |
     */
    'user' => [
        'foreign_key' => 'user_id',
        'model' => App\Models\User::class,
    ],

    /*
    |--------------------------------------------------------------------------
    | Experience Table
    |--------------------------------------------------------------------------
    |
    | This value is the name of the table that will be used to store experience data.
    |
     */
    'table' => 'experiences',

    /*
    |-----------------------------------------------------------------------
    | Starting Level
    |-----------------------------------------------------------------------
    |
    | The level that a User starts with.
    |
    */
    'starting_level' => 1,

    /*
    |-----------------------------------------------------------------------
    | Multiplier Paths
    |-----------------------------------------------------------------------
    |
    | Set the path and namespace for the Multiplier classes.
    |
    */
    'multiplier' => [
        'enabled' => env(key: 'MULTIPLIER_ENABLED', default: true),
        'path' => env(key: 'MULTIPLIER_PATH', default: app_path(path: 'Multipliers')),
        'namespace' => env(key: 'MULTIPLIER_NAMESPACE', default: 'App\\Multipliers\\'),
    ],

    /*
    |-----------------------------------------------------------------------
    | Level Cap
    |-----------------------------------------------------------------------
    |
    | Set the maximum level a User can reach.
    |
    */
    'level_cap' => [
        'enabled' => env(key: 'LEVEL_CAP_ENABLED', default: true),
        'level' => env(key: 'LEVEL_CAP', default: 100),
        'points_continue' => env(key: 'LEVEL_CAP_POINTS_CONTINUE', default: true),
    ],

    /*
    | -------------------------------------------------------------------------
    | Audit
    | -------------------------------------------------------------------------
    |
    | Set the audit configuration.
    |
    */
    'audit' => [
        'enabled' => env(key: 'AUDIT_POINTS', default: false),
    ],

    /*
    | -------------------------------------------------------------------------
    | Record streak history
    | -------------------------------------------------------------------------
    |
    | Set the streak history configuration.
    |
    */
    'archive_streak_history' => [
        'enabled' => env(key: 'ARCHIVE_STREAK_HISTORY_ENABLED', default: true),
    ],

    /*
     | -------------------------------------------------------------------------
     | Default Streak Freeze Time
     | -------------------------------------------------------------------------
     |
     | Set the default time in days that a streak will be frozen for.
     |
     */
    'freeze_duration' => env(key: 'STREAK_FREEZE_DURATION', default: 1),
];
```

Usage
=====

[](#usage)

💯 Experience Points (XP)
------------------------

[](#experience-points-xp)

> **Note**
>
> XP is enabled by default. You can disable it in the config

Add the `GiveExperience` trait to your `User` model.

```
use LevelUp\Experience\Concerns\GiveExperience;

class User extends Model
{
    use GiveExperience;

    // ...
}
```

**Give XP points to a User**

```
$user->addPoints(10);
```

A new record will be added to the `experiences` table which stores the Users’ points. If a record already exists, it will be updated instead. All new records will be given a `level_id` of `1`.

> **Note**
>
> If you didn't set up your Level structure yet, a default Level of `1` will be added to get you started.

**Deduct XP points from a User**

```
$user->deductPoints(10);
```

**Set XP points to a User**

For an event where you just want to directly add a certain number of points to a User. Points can only be ***set*** if the User has an Experience Model.

```
$user->setPoints(10);
```

**Retrieve a Users’ points**

```
$user->getPoints();
```

### Multipliers

[](#multipliers)

Point multipliers can be used to modify the experience point value of an event by a certain multiplier, such as doubling or tripling the point value. This can be useful for implementing temporary events or promotions that offer bonus points.

To get started, you can use an Artisan command to crease a new Multiplier.

```
php artisan level-up:multiplier IsMonthDecember
```

This will create a file at `app\Multipliers\IsMonthDecember.php`.

Here is how the class looks:

```