API.php

<?php

/**
 * Matomo - free/libre analytics platform
 *
 * @link    https://matomo.org
 * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
 */

namespace Piwik\Plugins\Tour;

use Piwik\Piwik;
use Piwik\Plugins\Tour\Engagement\Levels;
use Piwik\Plugins\Tour\Engagement\Challenges;

/**
 * Provides API methods for Tour challenges and engagement levels.
 *
 * @method static \Piwik\Plugins\Tour\API getInstance()
 */
class API extends \Piwik\Plugin\API
{
    /**
     * @var Challenges
     */
    private $challenges;

    /**
     * @var Levels
     */
    private $levels;

    public function __construct(Challenges $challenges, Levels $levels)
    {
        $this->challenges = $challenges;
        $this->levels = $levels;
    }

    /**
     * Returns the available Tour challenges for the current super user.
     *
     * @return list<array{
     *     id: string,
     *     name: string,
     *     description: string,
     *     isCompleted: bool,
     *     isSkipped: bool,
     *     url: string
     * }> Tour challenge metadata including completion and skip state.
     */
    public function getChallenges(): array
    {
        Piwik::checkUserHasSuperUserAccess();

        $challenges = [];

        $login = Piwik::getCurrentUserLogin();

        foreach ($this->challenges->getChallenges() as $challenge) {
            if ($challenge->isDisabled()) {
                continue;
            }

            $challenges[] = [
                'id' => $challenge->getId(),
                'name' => $challenge->getName(),
                'description' => $challenge->getDescription(),
                'isCompleted' => $challenge->isCompleted($login),
                'isSkipped' => $challenge->isSkipped($login),
                'url' => $challenge->getUrl(),
            ];
        }

        return $challenges;
    }

    /**
     * Marks the specified Tour challenge as skipped for the current super user.
     *
     * @param string $id The challenge ID to skip.
     * @return true Returns `true` when the challenge was skipped successfully.
     */
    public function skipChallenge(string $id): bool
    {
        Piwik::checkUserHasSuperUserAccess();

        $login = Piwik::getCurrentUserLogin();

        foreach ($this->challenges->getChallenges() as $challenge) {
            if ($challenge->getId() === $id) {
                if (!$challenge->isCompleted($login)) {
                    $challenge->skipChallenge($login);
                    return true;
                }

                throw new \Exception('Challenge already completed');
            }
        }

        throw new \Exception('Challenge not found');
    }

    /**
     * Returns the current Tour level details for the current super user.
     *
     * @return array{
     *     description: string,
     *     currentLevel: int,
     *     currentLevelName: string,
     *     nextLevelName: string|null,
     *     numLevelsTotal: int,
     *     challengesNeededForNextLevel: int
     * } Tour level details including the current and next level names.
     */
    public function getLevel(): array
    {
        Piwik::checkUserHasSuperUserAccess();

        return [
            'description' => $this->levels->getCurrentDescription(),
            'currentLevel' => $this->levels->getCurrentLevel(),
            'currentLevelName' => $this->levels->getCurrentLevelName(),
            'nextLevelName' => $this->levels->getNextLevelName(),
            'numLevelsTotal' => $this->levels->getNumLevels(),
            'challengesNeededForNextLevel' => $this->levels->getNumChallengesNeededToNextLevel(),
        ];
    }
}