README

Laravel Achievements

Simple, elegant Achievements the Laravel way.

Requirements

The package has been developed and tested to work with the latest supported versions of PHP and Laravel as well as the following minimum requirements:

• Laravel 12 or 13
• PHP 8.2 for Laravel 12, or PHP 8.3 for Laravel 13

Version Compatibility

Installation

Install the package via Composer.

composer require tehwave/laravel-achievements

Publish migrations.

php artisan vendor:publish --tag="achievements-migrations"

Migrate the migrations.

php artisan migrate

As an optional choice, you may publish config as well.

php artisan vendor:publish --tag="achievements-config"

Usage

Laravel Achievements work much like Laravel's notifications.

$user = \App\User::find(1);

$user->achieve(new \App\Achievements\UsersFirstPost());

Creating Achievements

php artisan make:achievement UsersFirstPost

This command will place a fresh Achievement class in your new app/Achievements directory.

Each Achievement class contains a toDatabase method, that you may use to store additional data with the achievement, and a few properties for basic meta information.

Unlocking Achievements

Use Achiever trait on models that can unlock achievements.

<?php

namespace App;

use Illuminate\Database\Eloquent\Model;
use tehwave\Achievements\Traits\Achiever;

class User extends Model
{
    use Achiever;

    // ...
}

Achieve an achievement via the achieve method.

$user = \App\User::find(1);

$user->achieve(new \App\Achievements\UsersFirstPost());

...or use Achievement class to unlock achievements.

$user = \App\User::find(1);

\tehwave\Achievements\Achievement::unlock($user, new \App\Achievements\UsersFirstPost());

Accessing Achievements

Retrieve all of the entity's unlocked achievements.

$user = \App\User::find(1);

$user->achievements()->get();

Checking if entity has Achievement

On models with the Achiever trait, you may pass an Achievement instance to hasAchievement method to check if the specified achievement exist on the model.

$achievement = new \App\Achievements\UsersFirstPost();

$user = \App\User::find(1);

$user->hasAchievement($achievement);
// false

$user->achieve($achievement);

$user->hasAchievement($achievement);
// true

Should you not want to pass an instance, you may also pass the class name.

$user->hasAchievement(\App\Achievements\UsersFirstPost::class);

Tests

Run the following command to test the package.

composer test

Security

For any security related issues, send a mail to peterchrjoergensen+achievements@gmail.com instead of using the issue tracker.

Changelog

See CHANGELOG for details on what has changed.

Upgrade Guide

See UPGRADING for details on how to upgrade.

Contributions

See CONTRIBUTING for details on how to contribute.

Credits

• Peter Jørgensen
• All Contributors

Inspired by https://github.com/gstt/laravel-achievements

About

I work as a Web Developer in Denmark on Laravel and WordPress websites.

Follow me @tehwave on Twitter!

License

MIT License