avoo/achievement-bundle

Achievement bundle

AchievementBundle

, _(*1)

Achievement bundle for Symfony 2, _(*2)

• Installation
• Configuration
• User Achievement class
• Doctrine configuration
• Achievement configuration
• Listener implementation
• Default Usage
• Default Progression

Installation

Require avoo/achievement-bundle into your composer.json file:, _(*3)

``` json { "require": { "avoo/achievement-bundle": "~1.0" } }, <sub>(*4)</sub>

Register the bundle in `app/AppKernel.php`:

``` php
// app/AppKernel.php
public function registerBundles()
{
    return array(
        // ...
        new Avoo\AchievementBundle\AvooAchievementBundle(),
    );
}

Default Configuration

User class

You need to implement Avoo\AchievementBundle\Model\UserInterface, consider the user class in AppBundle\Entity\User., <sub>(*5)</sub>

for FOS example:, <sub>(*6)</sub>

``` php namespace AppBundle\Entity;, <sub>(*7)</sub>

use Avoo\AchievementBundle\Model\UserInterface; use FOS\UserBundle\Model\User as BaseUser;, <sub>(*8)</sub>

/** * Class User */ class User extends BaseUser implements UserInterface { /** * @var integer $id */ protected $id;, <sub>(*9)</sub>

/**
 * @var array $achievements
 */
protected $achievements;

/**
 * {@inheritdoc}
 */
public function getAchievements()
{
    return $this->achievements;
}

}, <sub>(*10)</sub>

#### User Achievement class

**Class**

``` php
namespace AppBundle\Entity;

use Avoo\AchievementBundle\Entity\UserAchievement as BaseUserAchievement;
use Avoo\AchievementBundle\Model\UserInterface;

/**
 * Class UserAchievement
 */
class UserAchievement extends BaseUserAchievement
{
    /**
     * @var UserInterface $user
     */
    protected $user;
}

Doctrine configuration

In the user class:, <sub>(*11)</sub>

YML, <sub>(*12)</sub>

``` yml, <sub>(*13)</sub>

src/AppBundle/Resources/config/doctrine/User.orm.yml

AppBundle\Entity\User: type: entity oneToMany: achievements: targetEntity: AppBundle\Entity\UserAchievement mappedBy: user, <sub>(*14)</sub>

**XML**

``` xml


<doctrine-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mapping"
                  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                  xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mapping
                  http://doctrine-project.org/schemas/orm/doctrine-mapping.xsd">

    <entity name="AppBundle\Entity\User" table="fos_user">
        <one-to-many field="achievements" target-entity="AppBundle\Entity\UserAchievement" mapped-by="user" />
    </entity>

</doctrine-mapping>

Annotation, <sub>(*15)</sub>

``` php namespace Avoo\EloBundle\Entity;, <sub>(*16)</sub>

use Avoo\AchievementBundle\Model\UserInterface; use FOS\UserBundle\Model\User as BaseUser; use Doctrine\ORM\Mapping as ORM;, <sub>(*17)</sub>

class User extends BaseUser implement UserInterface { /** * @OneToMany(targetEntity="AppBundle\Entity\UserAchievement", mappedBy="user") */ protected $achievements;, <sub>(*18)</sub>

/**
 * {@inheritdoc}
 */
public function getAchievements()
{
    return $this->achievements;
}

}, <sub>(*19)</sub>

And now linked the user achievement class with your own user class.

**YML**

``` yml
# src/AppBundle/Resources/config/doctrine/UserAchievement.orm.yml
AppBundle\Entity\UserAchievement:
    type:  entity
    repositoryClass: Avoo\AchievementBundle\Repository\UserAchievementRepository 
    table: avoo_user_achievement
    id:
        id:
            type: integer
            generator:
                strategy: AUTO
    manyToOne:
        user:
            targetEntity: AppBundle\Entity\User
            inversedBy: achievements
            joinColumn:
                name: user_id
                referencedColumnName: id
                nullable: false

XML, <sub>(*20)</sub>

``` xml , <sub>(*21)</sub>

<entity name="AppBundle\Entity\UserAchievement" table="avoo_user_achievement" repository-class="Avoo\AchievementBundle\Repository\UserAchievementRepository">
    <id name="id" type="integer" column="id">
        <generator strategy="AUTO"/>
    </id>

    <many-to-one target-entity="AppBundle\Entity\User" field="user" inversed-by="achievements">
        <join-column name="user_id" nullable="false" />
    </many-to-one>
</entity>

, <sub>(*22)</sub>

**Annotation**

``` php
namespace Avoo\EloBundle\Entity;

use Avoo\AchievementBundle\Entity\UserAchievement as BaseUserAchievement;
use Doctrine\ORM\Mapping as ORM;

class UserAchievement extends BaseUserAchievement
{
    /**
     * @ORM\Id
     * @ORM\Column(type="integer")
     * @ORM\GeneratedValue(strategy="AUTO")
     */
    protected $id;

    /**
     * @ORM\ManyToOne(targetEntity="AppBundle\Entity\UserAchievement", inversedBy="achievements")
     * @ORM\JoinColumn(name="user_id", referencedColumnName="id")
     */
    protected $user;
}

Achievement configuration

Define the user achievement class, <sub>(*23)</sub>

``` yaml, <sub>(*24)</sub>

app/config/config.yml

avoo_achievement: user_achievement_class: AppBundle\Entity\UserAchievement, <sub>(*25)</sub>

**Add achievement**

``` yaml
# app/config/config.yml
avoo_achievement:
    achievements:
        my_category: # it's the category of achievements
            my_super_achievement:
                class: AppBundle\Listener\SuperAchievementListener #The class handle the event.
                name: Test #Achievement name (Use the real name or the translate file, ex: achievement.global.my_super_achievement.name).
                value: 3 #The value for unlock achievement, must be an integer or float.
                description: My super description #Optional field. The achievement description, you can use the translation file.
                image: bundles/app/images/my_beautiful_image.png #Optional field.
            mega_achievement:
                class: AppBundle\Listener\OtherListener
                name: achievement.my_super_achievement.mega_achievement.name
                description: achievement.my_super_achievement.mega_achievement.description
                value: 100
        other_category:
            mega_achievement:
                class: AppBundle\Listener\OtherListener
                name: Achievement name
                value: 50

Listener implementation

Achievement listener example

``` php namespace AppBundle\Listener;, <sub>(*26)</sub>

use Avoo\AchievementBundle\Listener\AchievementListener;, <sub>(*27)</sub>

/** * Class SuperAchievementListener * */ class SuperAchievementListener extends AchievementListener { }, <sub>(*28)</sub>

That's all.

Default Usage
-------------

**Be careful, if you want to see the achievement progress, you need to be logged!**

You can use the default achievement rendering in your views:

``` twig
{{ render(controller('AvooAchievementBundle:Achievement:overview')) }} {# List all achievements #}

{{ render(controller('AvooAchievementBundle:Achievement:categories')) }} {# List of achievements categories #}

{{ render(controller('AvooAchievementBundle:Achievement:achievementsByCategory', {'category' : 'my_category'})) }} {# All achievements for unique category #}

{{ render(controller('AvooAchievementBundle:Achievement:locked')) }} {# Locked achievements #}

{{ render(controller('AvooAchievementBundle:Achievement:inProgress')) }} {# Achievements in progress #}

{{ render(controller('AvooAchievementBundle:Achievement:unlocked')) }} {# Unlocked achievements #}

{{ render(controller('AvooAchievementBundle:Achievement:latest', {'limit', 2})) }} {# The last earned achievements (limit is optional) #}

{{ render(controller('AvooAchievementBundle:Achievement:earnedByCategory')) }} {# The list of earned achievements by categories #}

Default Progression

Progress example: ``` php public function indexAction(Request $request) { $achievement = $this->get('avoo_achievement');, <sub>(*29)</sub>

$achievement->get('my_category.my_super_achievement')->progress(2); // Return true or false

}, <sub>(*30)</sub>

Check if current achievement is earned:
``` php
public function indexAction(Request $request)
{
    $achievement = $this->get('avoo_achievement');

    $achievement->get('my_category.my_super_achievement')->isComplete(); // Return true or false
}

Achievement validation, you can implement your own validation process with isValid function in your listener class: ``` php namespace AppBundle\Listener;, <sub>(*31)</sub>

use Avoo\AchievementBundle\Listener\AchievementListener;, <sub>(*32)</sub>

/** * Class SuperAchievementListener * */ class SuperAchievementListener extends AchievementListener { public function isValid($object = null) { //My validation process } }, <sub>(*33)</sub>

And now call:

``` php
public function indexAction(Request $request)
{
    $listener = $this->get('avoo_achievement')->get('my_category.my_super_achievement');
    if ($listener->isValid()) {
        $listener->progress(1);
    }
}

Or override progress function: ``` php namespace AppBundle\Listener;, <sub>(*34)</sub>

use Avoo\AchievementBundle\Listener\AchievementListener;, <sub>(*35)</sub>

/** * Class SuperAchievementListener * */ class SuperAchievementListener extends AchievementListener { public function progress($value) { //My progress process } }, <sub>(*36)</sub>

```, <sub>(*37)</sub>

License

This bundle is released under the MIT license. See the complete license in the bundle:, <sub>(*38)</sub>

License, <sub>(*39)</sub>