API for Developers

This page is for developers integrating UserPoints with Joomla extensions. It assumes familiarity with PHP and Joomla 4/5 extension development.

UserPoints is released under the GNU/GPL licence. It started life as AlphaUserPoints in 2008 and has been fully namespaced and modernised for Joomla 4 and 5.

How UserPoints Works

UserPoints awards (or deducts) points when a rule is triggered. A rule is identified by a short string called the rule key — for example up_login or sysplgup_buypoints. When your code calls UserPoints::newpoints('rule_name'), UserPoints looks up the published rule with that name, checks frequency and eligibility, and records the transaction.

Rules are configured by the site administrator in the UserPoints backend. You define what rules exist via an XML file (described below); the administrator controls how many points each rule awards.

Calling the API

UserPoints uses PSR-4 autoloading. Include the namespace and check the class exists before calling, so your code degrades gracefully on sites without UserPoints:

use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

if (class_exists(UserPoints::class)) {
    UserPoints::newpoints('rule_name');
}

This awards points to the currently logged-in user.

Award Points to a Different User

To credit another user — for example, to award an article author when someone reads their article — obtain that user's UserPoints referral ID first:

use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

if (class_exists(UserPoints::class)) {
    $referreid = UserPoints::getAnyUserReferreID($authorUserID);
    if ($referreid) {
        UserPoints::newpoints('rule_name', $referreid);
    }
}

Prevent Duplicate Awards

To ensure a user only earns points once for a specific action, pass a key reference. UserPoints checks for an existing record with the same key and skips the award if one exists:

use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

if (class_exists(UserPoints::class)) {
    $keyreference = UserPoints::buildKeyreference('rule_name', $itemId);
    UserPoints::newpoints('rule_name', '', $keyreference);
}

Attach Information Data

Add a descriptive string that will appear in the activity log for reference:

use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

if (class_exists(UserPoints::class)) {
    $keyreference = UserPoints::buildKeyreference('rule_name', $itemId);
    UserPoints::newpoints('rule_name', '', $keyreference, 'Order #12345');
}

Variable Point Amounts

When the number of points should vary per transaction (for example, proportional to a purchase total), pass the amount via the $randompoints parameter. Use a negative value to deduct points:

use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

if (class_exists(UserPoints::class)) {
    $keyreference = UserPoints::buildKeyreference('rule_name', $itemId);
    UserPoints::newpoints('rule_name', '', $keyreference, '', -1450);
}

Check Whether the Operation Succeeded

Pass true as the $feedback parameter to get a boolean return value. This is useful when you need to confirm a user has enough points before allowing an action:

use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

if (class_exists(UserPoints::class)) {
    $keyreference = UserPoints::buildKeyreference('up_purchasewithvirtuemart', $transactionID);
    if (UserPoints::newpoints('up_purchasewithvirtuemart', '', $keyreference, 'Product AM-5245', -1290, true)) {
        // points successfully deducted — proceed with order
    }
}

If the user does not have enough points for a deduction, newpoints returns false and displays a notice to the user. You can allow negative balances via the Allow Negative Account configuration option.

Bypass User-Level Restrictions

Pass 1 as the $force parameter to remove any rule restriction based on user group (guest, registered, special):

UserPoints::newpoints('rule_name', '', '', '', 0, false, 1);

Display a Custom Message

Pass a string as $frontmessage to show an additional system message to the user alongside the standard points notification:

UserPoints::newpoints('rule_name', '', '', '', 0, false, 0, 'Thank you for your contribution!');

Full Signature

UserPoints::newpoints(
    string $plugin_function,
    string $referrerid    = '',
    string $keyreference  = '',
    string $datareference = '',
    int    $randompoints  = 0,
    bool   $feedback      = false,
    int    $force         = 0,
    string $frontmessage  = ''
);

Defining Rules via XML

Extensions that integrate with UserPoints should ship a file called userpoints_rule.xml anywhere inside their extension directory. UserPoints scans the components/, modules/, and plugins/ trees during auto-detect, so the file will be found wherever your extension lives. This file tells UserPoints what rules the extension provides. The site administrator can then trigger Auto-detect from the UserPoints control panel to import them automatically.

Example — the Remository integration file:

<?xml version="1.0" encoding="UTF-8"?>
<userpoints>
    <component>com_remository</component>
    <rules>
        <rule>
            <name>Upload</name>
            <description>Give points when a new file is uploaded</description>
            <plugin_function>up_remository_up</plugin_function>
            <fixed_points>true</fixed_points>
            <category>ot</category>
            <display_message>1</display_message>
            <email_notification>1</email_notification>
        </rule>
        <rule>
            <name>Download</name>
            <description>Take points when a file is downloaded</description>
            <plugin_function>up_remository_down</plugin_function>
            <fixed_points>false</fixed_points>
            <category>ot</category>
            <display_message>1</display_message>
            <email_notification>1</email_notification>
        </rule>
    </rules>
</userpoints>

Category Codes

Method Codes

Add a <method> element to a rule to control how often it can fire per user:

Reading User Information

Get a User's Full Profile

use BlackSheepResearch\Component\UserPoints\Site\UserPoints;

$profile = UserPoints::getUserInfo($referreid);
// or by Joomla user ID:
$profile = UserPoints::getUserInfo('', $userId);

Returns an object with these fields:

$profile->name            // full name (from Joomla users table)
$profile->username        // login username
$profile->registerDate    // Joomla registration date
$profile->lastvisitDate   // last Joomla login date
$profile->email           // email address
$profile->userid          // Joomla user ID
$profile->referreid       // UserPoints referral ID
$profile->points          // current point total
$profile->max_points      // per-user point ceiling (0 = use global setting)
$profile->nummedals       // count of medals earned
$profile->last_update     // timestamp of last points change
$profile->referraluser    // referral ID of the user who referred this user
$profile->referrees       // count of users referred by this user
$profile->blocked         // 1 if UserPoints account is suspended
$profile->avatar          // avatar filename
$profile->levelrank       // current rank ID
$profile->leveldate       // date rank was last changed
$profile->profileviews    // number of times this profile page has been viewed
$profile->published       // 1 if the UserPoints account is publicly visible
$profile->shareinfos      // whether the user shares profile information
$profile->upnid           // internal UserPoints node ID

Get the Current Point Total

$total = UserPoints::getCurrentTotalPoints($referreid);
// or by Joomla user ID:
$total = UserPoints::getCurrentTotalPoints('', $userId);

Get a User's Referral ID

$referreid = UserPoints::getAnyUserReferreID($userId);

Get Profile and Users List URLs

$profileUrl = UserPoints::getAupLinkToProfil($userId);
$listUrl    = UserPoints::getAupUsersURL();

Get a User's Medals

$medals = UserPoints::getUserMedals($referreid);
// or by Joomla user ID:
$medals = UserPoints::getUserMedals('', $userId);

Each item in the returned array has:

->id
->rank          (medal name)
->description   (reason awarded)
->image         (image filename)

To display medal images:

use BlackSheepResearch\Component\UserPoints\Administrator\Models\Image;
foreach (UserPoints::getUserMedals('', $userId) as $medal) {
    echo Image::imageHTML($medal->image);
}

Note that UserPoints::getMedalsLivePath(); is deprecated and no longer returns a value;

Get the Next Rank a User Can Achieve

$nextRank = UserPoints::getNextUserRank($referreid, $userId, $currentRank);

Returns an object with:

->id
->rank          (rank name)
->description
->levelpoints   (points needed to reach this rank)
->icon
->image

Get the Activity List

$activities = UserPoints::getListActivity($type = 'all', $userid = 'all', $numrows = 0);

Each row contains:

->insert_date
->referreid
->points
->datareference
->rule_name
->plugin_function
->category

Get the Installed Version

$version = UserPoints::getUpVersion();

Plugin Events

UserPoints fires the following events that your plugins can hook into:

An example plugin showing the parameters available for each event is included in the UserPoints package at plugins/userpoints/example/.