<?php

namespace OpenMind\System;

/**
 * Global user roles: a volatile list of roles present throughout the application.
 * The list is not linked to users.
 */
class UserRoles
{
	private const F3_KEY = 'USERROLES';

	/**
	 * Initialize the global user-role list when it does not exist.
	 *
	 * @side-effects Creates the global user-role list when needed.
	 */
	public function __construct()
	{
		global $f3;

		if ($f3->get(self::F3_KEY) === null) {
			$f3->set(self::F3_KEY, []);
		}
	}

	/**
	 * Get all defined user roles.
	 *
	 * @return array All configured user roles.
	 * @side-effects Reads the global user-role list.
	 */
	public static function getAllRoles(): array
	{
		global $f3;

		return $f3->get(self::F3_KEY);
	}

	/**
	 * Retrieve the value for a permission.
	 *
	 * @param string $permissionName Permission name to retrieve.
	 * @return mixed Configured permission value.
	 * @side-effects Reads the global user-role list.
	 */
	public function get(string $permissionName)
	{
		global $f3;

		return $f3->get(self::F3_KEY)[$permissionName];
	}

	/**
	 * Add a new permission to the roles list.
	 *
	 * @param string $permissionName Permission name to add.
	 * @return void
	 * @side-effects Mutates the global user-role list.
	 */
	public function add(string $permissionName)
	{
		global $f3;

		$roles = &$f3->ref(self::F3_KEY);
		$roles[] = $permissionName;
	}
}