{"id":32610530,"url":"https://github.com/maize-tech/laravel-badges","last_synced_at":"2025-10-30T13:50:15.619Z","repository":{"id":198179693,"uuid":"700398365","full_name":"maize-tech/laravel-badges","owner":"maize-tech","description":"This package lets you easily add badge mechanics to your application","archived":false,"fork":false,"pushed_at":"2025-08-18T04:07:39.000Z","size":102,"stargazers_count":36,"open_issues_count":1,"forks_count":7,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-10-05T08:57:00.360Z","etag":null,"topics":["badges","gamification","laravel","php"],"latest_commit_sha":null,"homepage":"","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/maize-tech.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-10-04T14:19:57.000Z","updated_at":"2025-09-22T15:06:03.000Z","dependencies_parsed_at":"2025-07-19T17:18:18.672Z","dependency_job_id":"fc121eda-b545-4753-8240-a07236dd0bb8","html_url":"https://github.com/maize-tech/laravel-badges","commit_stats":null,"previous_names":["maize-tech/laravel-badges"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/maize-tech/laravel-badges","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maize-tech%2Flaravel-badges","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maize-tech%2Flaravel-badges/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maize-tech%2Flaravel-badges/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maize-tech%2Flaravel-badges/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maize-tech","download_url":"https://codeload.github.com/maize-tech/laravel-badges/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maize-tech%2Flaravel-badges/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":281818074,"owners_count":26566858,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-30T02:00:06.501Z","response_time":61,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["badges","gamification","laravel","php"],"created_at":"2025-10-30T13:50:13.992Z","updated_at":"2025-10-30T13:50:15.613Z","avatar_url":"https://github.com/maize-tech.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"/art/socialcard-dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"/art/socialcard-light.png\"\u003e\n  \u003cimg src=\"/art/socialcard-light.png\" alt=\"Social Card of Laravel Badges\"\u003e\n\u003c/picture\u003e\n\u003c/p\u003e\n\n# Laravel Badges\n\n[![Latest Version on Packagist](https://img.shields.io/packagist/v/maize-tech/laravel-badges.svg?style=flat-square)](https://packagist.org/packages/maize-tech/laravel-badges)\n[![GitHub Tests Action Status](https://img.shields.io/github/actions/workflow/status/maize-tech/laravel-badges/run-tests.yml?branch=main\u0026label=tests\u0026style=flat-square)](https://github.com/maize-tech/laravel-badges/actions?query=workflow%3Arun-tests+branch%3Amain)\n[![GitHub Code Style Action Status](https://img.shields.io/github/actions/workflow/status/maize-tech/laravel-badges/fix-php-code-style-issues.yml?branch=main\u0026label=code%20style\u0026style=flat-square)](https://github.com/maize-tech/laravel-badges/actions?query=workflow%3A\"Fix+PHP+code+style+issues\"+branch%3Amain)\n[![Total Downloads](https://img.shields.io/packagist/dt/maize-tech/laravel-badges.svg?style=flat-square)](https://packagist.org/packages/maize-tech/laravel-badges)\n\nThis package lets you easily add badge mechanics to your application.\n\n## Installation\n\nYou can install the package via composer:\n\n```bash\ncomposer require maize-tech/laravel-badges\n```\n\nYou can publish the config and migration files and run the migrations with:\n\n```bash\nphp artisan badges:install\n```\n\nThis is the contents of the published config file:\n\n```php\nreturn [\n\n    /*\n    |--------------------------------------------------------------------------\n    | Badge model\n    |--------------------------------------------------------------------------\n    |\n    | Here you may specify the fully qualified class name of the badge model.\n    |\n    */\n\n    'model' =\u003e Maize\\Badges\\Models\\BadgeModel::class,\n\n    /*\n    |--------------------------------------------------------------------------\n    | Badges\n    |--------------------------------------------------------------------------\n    |\n    | Here you may specify the list of fully qualified class name of badges.\n    |\n    */\n\n    'badges' =\u003e [\n        // App\\Badges\\FirstLogin::class,\n    ],\n\n];\n```\n\n## Usage\n\n### Basic\n\nTo 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:\n\n```php\n\u003c?php\n\nnamespace App\\Models;\n\nuse Illuminate\\Foundation\\Auth\\User as Authenticatable;\nuse Maize\\Badges\\HasBadges;\nuse Maize\\Badges\\InteractsWithBadges;\n\nclass User extends Authenticatable implements HasBadges\n{\n    use InteractsWithBadges;\n}\n```\n\nOnce 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:\n\n```php\n\u003c?php\n\nnamespace App\\Badges;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Maize\\Badges\\Badge;\n\nclass FirstLogin extends Badge\n{\n    public static function isAwarded(Model $model): bool\n    {\n        return $model-\u003elogins()-\u003eexists();\n    }\n}\n```\n\nOnce done, don't forget to list the newly created badge within the `badges` list under `config/badges.php`:\n\n```php\n'badges' =\u003e [\n    App\\Badges\\FirstLogin::class,\n],\n```\n\n### Progressable badges\n\nIf your badge can have progress, you should extend the `Maize\\Badges\\ProgressableBadge` class and implement both the `getTotal` and `getCurrent` abstract methods:\n\n```php\n\u003c?php\n\nnamespace App\\Badges;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Maize\\Badges\\ProgressableBadge;\n\nclass FiveLogins extends ProgressableBadge\n{\n    public static function getTotal(): int\n    {\n        return 5;\n    }\n\n    public static function getCurrent(Model $model): bool\n    {\n        return $model-\u003elogins()-\u003ecount();\n    }\n}\n```\n\nUnder the hoods, the `isAwarded` method checks if `getCurrent` is equals or greater than `getTotal`.\n\n### Badge metadata\n\nWhat is a badge without a name or description?\n\nTo accomplish this, you can override the `metadata` method within all badge classes.\n\nHere is an example implementation using Laravel built-in translation method and the badge slug:\n\n```php\n\u003c?php\n\nnamespace App\\Badges;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Maize\\Badges\\Badge;\n\nclass FirstLogin extends Badge\n{\n    public static function isAwarded(Model $model): bool\n    {\n        return $model-\u003elogins()-\u003eexists();\n    }\n    \n    public static function metadata(): array\n    {\n        $slug = static::slug();\n\n        return [\n            'name' =\u003e __(\"badges.{$slug}.name\"),\n            'description' =\u003e __(\"badges.{$slug}.name\"),\n        ];    \n    }\n}\n```\n\nOnce done, you can retrieve the metadata using both the badge class and the `BadgeModel` entities:\n\n```php\nuse App\\Badges\\FirstLogin;\nuse Maize\\Badges\\Models\\BadgeModel;\n\n$user-\u003egiveBadge(FirstLogin::class);\n\n$user-\u003ebadges()-\u003efirst()-\u003emetadata; // returns the list of metadata attributes\n\n$user-\u003ebadges()-\u003efirst()-\u003egetMetadata('description'); // returns the attribute with key 'description'\n\nFirstLogin::metadata(); // returns the list of metadata attributes\n\nFirstLogin::getMetadata('description'); // returns the metadata attribute with key 'description'\n```\n\n### Custom badge slug\n\nAll badges have a default slug used when storing a badge awarded event into the database.\n\nThe default slug is the badge's fully qualified class name.\nFor example, `FirstLogin` badge's slug would be `App\\Badges\\FirstLogin`.\n\nYou can however customize the default behaviour overriding the `slug` method.\n\nHere is an example using the badge's class basename in kebab case:\n\n```php\n\u003c?php\n\nnamespace App\\Badges;\n\nuse Illuminate\\Database\\Eloquent\\Model;\nuse Maize\\Badges\\Badge;\n\nclass FirstLogin extends Badge\n{\n    public static function slug(): string\n    {\n        return str(static::class)\n            -\u003eclassBasename()\n            -\u003ekebab()\n            -\u003etoString(); // returns 'first-login'\n    }\n\n    public static function isAwarded(Model $model): bool\n    {\n        return $model-\u003elogins()-\u003eexists();\n    }\n}\n```\n\nBeware that all badge classes should have a unique slug to prevent inconsistencies.\n\n### Giving a badge\n\nYou can give a badge to any entity implementing the `HasBadges` interface using one of the following methods:\n\n```php\nuse App\\Badges\\FirstLogin;\n\n$user-\u003egiveBadge(FirstLogin::class);\n\nFirstLogin::giveTo($user);\n```\n\nWhen giving a badge, the `isAwarded` method will be evaluated to make sure the entity meets the conditions.\n\nEvery time a badge is given, a `BadgeAwarded` event will also be fired.\n\n### Check if a badge is awarded\n\nTo check if an entity has a badge, you can use the `hasBadge` method:\n\n```php\nuse App\\Badges\\FirstLogin;\n\n$user-\u003ehasBadge(FirstLogin::class)\n```\n\n### Retrieve awarded badges\n\nTo retrieve all badges awarded by an entity, you can use the `badges` relationship which returns a list of `BadgeModel` entities.\n\n```php\nuse Maize\\Badges\\Models\\BadgeModel;\n\n$user-\u003ebadges-\u003emap-\u003ebadge; // returns the list of awarded badges slug\n```\n\n### Sync badges\n\nTo 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.\n\n```php\n$user-\u003esyncBadges();\n```\n\n### Scheduling badges cleanup\n\nThe 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`:\n\nYou may schedule the command using the `schedule` method of the console kernel (usually located under the `App\\Console` directory):\n\n```php\nuse Maize\\Badges\\Commands\\ClearBadgesCommand;\n\n$schedule-\u003ecommand(ClearBadgesCommand::class)-\u003edaily();\n```\n\n## Testing\n\n```bash\ncomposer test\n```\n\n## Changelog\n\nPlease see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.\n\n## Contributing\n\nPlease see [CONTRIBUTING](https://github.com/maize-tech/.github/blob/main/CONTRIBUTING.md) for details.\n\n## Security Vulnerabilities\n\nPlease review [our security policy](https://github.com/maize-tech/.github/security/policy) on how to report security vulnerabilities.\n\n## Credits\n\n- [Riccardo Dalla Via](https://github.com/riccardodallavia)\n- [All Contributors](../../contributors)\n\n## License\n\nThe MIT License (MIT). Please see [License File](LICENSE.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaize-tech%2Flaravel-badges","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaize-tech%2Flaravel-badges","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaize-tech%2Flaravel-badges/lists"}