Download the PHP package maize-tech/laravel-badges without Composer

# Laravel Badges [](https://packagist.org/packages/maize-tech/laravel-badges) [](https://github.com/maize-tech/laravel-badges/actions?query=workflow%3Arun-tests+branch%3Amain) [](https://github.com/maize-tech/laravel-badges/actions?query=workflow%3A"Fix+PHP+code+style+issues"+branch%3Amain) [](https://packagist.org/packages/maize-tech/laravel-badges) This package lets you easily add badge mechanics to your application. ## Installation You can install the package via composer: You can publish the config and migration files and run the migrations with: This is the contents of the published config file: ## Usage ### Basic To use the package, firstly you should implement the `Maize\Badges\HasBadges` interface and apply the `Maize\Badges\InteractsWithBadges` trait to all models who can have badges: Once done, all you have to do is define a class for each badge, extend the `Maize\Badges\Badge` class and implement the `isAwarded` abstract method: Once done, don't forget to list the newly created badge within the `badges` list under `config/badges.php`: ### Progressable badges If your badge can have progress, you should extend the `Maize\Badges\ProgressableBadge` class and implement both the `getTotal` and `getCurrent` abstract methods: Under the hoods, the `isAwarded` method checks if `getCurrent` is equals or greater than `getTotal`. ### Badge metadata What is a badge without a name or description? To accomplish this, you can override the `metadata` method within all badge classes. Here is an example implementation using Laravel built-in translation method and the badge slug: Once done, you can retrieve the metadata using both the badge class and the `BadgeModel` entities: ### Custom badge slug All badges have a default slug used when storing a badge awarded event into the database. The default slug is the badge's fully qualified class name. For example, `FirstLogin` badge's slug would be `App\Badges\FirstLogin`. You can however customize the default behaviour overriding the `slug` method. Here is an example using the badge's class basename in kebab case: Beware that all badge classes should have a unique slug to prevent inconsistencies. ### Giving a badge You can give a badge to any entity implementing the `HasBadges` interface using one of the following methods: When giving a badge, the `isAwarded` method will be evaluated to make sure the entity meets the conditions. Every time a badge is given, a `BadgeAwarded` event will also be fired. ### Check if a badge is awarded To check if an entity has a badge, you can use the `hasBadge` method: ### Retrieve awarded badges To retrieve all badges awarded by an entity, you can use the `badges` relationship which returns a list of `BadgeModel` entities. ### Sync badges To sync all badges for a given entity, you can use the `syncBadges` method, which retrieves all badges within the `badges` list under `config/badges.php` and checks whether it can be awarded or not. ### Scheduling badges cleanup The package also comes with the `badges:clear` command, which automatically deletes all stored badges which are not anymore listed within the `badges` list under `config/badges.php`: You may schedule the command using the `schedule` method of the console kernel (usually located under the `App\Console` directory): ## Testing ## Changelog Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently. ## Contributing Please see [CONTRIBUTING](https://github.com/maize-tech/.github/blob/main/CONTRIBUTING.md) for details. ## Security Vulnerabilities Please review [our security policy](https://github.com/maize-tech/.github/security/policy) on how to report security vulnerabilities. ## Credits - [Riccardo Dalla Via](https://github.com/riccardodallavia) - [All Contributors](../../contributors) ## License The MIT License (MIT). Please see [License File](LICENSE.md) for more information.