Introducing a new role "write" and possibility to define capabilities (#13163)

* started working on some ACL concept

* acl implementation

* add category

* small tweaks

* more tweaks

* more api methods and fixes

* cache capabilities

* various enhancements, fixes, tweaks

* more tweaks

* added more tests and fixed some bugs

* fix parameter

* make sure to be BC

* make sure to be BC

* fix some tests

* more apis, translations, changelog entry, ...

* update db

* correct error message

* fix capabilities were not detected in tests

* directly access provider

* fix and add test

* JS api to check capabilities, better structure for capabilities in tests

* add ability to inject permissions

* apply review changes

* fix test

7 files changed, 338 insertions, 0 deletions

diff --git a/core/Access/CapabilitiesProvider.php b/core/Access/CapabilitiesProvider.php
new file mode 100644
index 0000000000..358782eaca
--- /dev/null
+++ b/core/Access/CapabilitiesProvider.php
@@ -0,0 +1,108 @@
+<?php
+/**
+ * Piwik - free/libre analytics platform
+ *
+ * @link http://piwik.org
+ * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ *
+ */
+namespace Piwik\Access;
+
+use Exception;
+use Piwik\CacheId;
+use Piwik\Piwik;
+use Piwik\Cache as PiwikCache;
+
+class CapabilitiesProvider
+{
+    /**
+     * @return Capability[]
+     */
+    public function getAllCapabilities()
+    {
+        $cacheId = CacheId::siteAware(CacheId::languageAware('Capabilities'));
+        $cache   = PiwikCache::getTransientCache();
+
+        if (!$cache->contains($cacheId)) {
+            $capabilities = array();
+
+            /**
+             * Triggered to add new capabilities.
+             *
+             * **Example**
+             *
+             *     public function addCapabilities(&$capabilities)
+             *     {
+             *         $capabilities[] = new MyNewCapabilitiy();
+             *     }
+             *
+             * @param Capability[] $reports An array of reports
+             * @internal
+             */
+            Piwik::postEvent('Access.Capability.addCapabilities', array(&$capabilities));
+
+            /**
+             * Triggered to filter / restrict capabilities.
+             *
+             * **Example**
+             *
+             *     public function filterCapabilities(&$capabilities)
+             *     {
+             *         foreach ($capabilities as $index => $capability) {
+             *              if ($capability->getId() === 'tagmanager_write') {}
+             *                  unset($capabilities[$index]); // remove the given capability
+             *              }
+             *         }
+             *     }
+             *
+             * @param Capability[] $reports An array of reports
+             * @internal
+             */
+            Piwik::postEvent('Access.Capability.filterCapabilities', array(&$capabilities));
+
+            $capabilities = array_values($capabilities);
+
+            $cache->save($cacheId, $capabilities);
+            return $capabilities;
+        }
+
+        return $cache->fetch($cacheId);
+    }
+
+    /**
+     * @param $capabilityId
+     * @return Capability|null
+     */
+    public function getCapability($capabilityId)
+    {
+        foreach ($this->getAllCapabilities() as $capability) {
+            if ($capabilityId === $capability->getId()) {
+                return $capability;
+            }
+        }
+    }
+
+    public function getAllCapabilityIds()
+    {
+        $ids = array();
+        foreach ($this->getAllCapabilities() as $capability) {
+            $ids[] = $capability->getId();
+        }
+        return $ids;
+    }
+
+    public function isValidCapability($capabilityId)
+    {
+        $capabilities = $this->getAllCapabilityIds();
+
+        return in_array($capabilityId, $capabilities, true);
+    }
+
+    public function checkValidCapability($capabilityId)
+    {
+        if (!$this->isValidCapability($capabilityId)) {
+            $capabilities = $this->getAllCapabilityIds();
+            throw new Exception(Piwik::translate("UsersManager_ExceptionAccessValues", implode(", ", $capabilities)));
+        }
+    }
+}
diff --git a/core/Access/Capability.php b/core/Access/Capability.php
new file mode 100644
index 0000000000..2d2896d67e
--- /dev/null
+++ b/core/Access/Capability.php
@@ -0,0 +1,29 @@
+<?php
+/**
+ * Piwik - free/libre analytics platform
+ *
+ * @link http://piwik.org
+ * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ *
+ */
+namespace Piwik\Access;
+
+abstract class Capability
+{
+    abstract public function getId();
+    abstract public function getName();
+    abstract public function getCategory();
+    abstract public function getDescription();
+    abstract public function getIncludedInRoles();
+
+    public function getHelpUrl()
+    {
+        return '';
+    }
+
+    public function hasRoleCapability($idRole)
+    {
+        return in_array($idRole, $this->getIncludedInRoles(), true);
+    }
+
+}
diff --git a/core/Access/Role.php b/core/Access/Role.php
new file mode 100644
index 0000000000..ae6cf57a24
--- /dev/null
+++ b/core/Access/Role.php
@@ -0,0 +1,22 @@
+<?php
+/**
+ * Piwik - free/libre analytics platform
+ *
+ * @link http://piwik.org
+ * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ *
+ */
+namespace Piwik\Access;
+
+abstract class Role
+{
+    abstract public function getName();
+    abstract public function getId();
+    abstract public function getDescription();
+
+    public function getHelpUrl()
+    {
+        return '';
+    }
+
+}
diff --git a/core/Access/Role/Admin.php b/core/Access/Role/Admin.php
new file mode 100644
index 0000000000..9496a9742b
--- /dev/null
+++ b/core/Access/Role/Admin.php
@@ -0,0 +1,40 @@
+<?php
+/**
+ * Piwik - free/libre analytics platform
+ *
+ * @link http://piwik.org
+ * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ *
+ */
+namespace Piwik\Access\Role;
+
+use Piwik\Access\Role;
+use Piwik\Piwik;
+
+class Admin extends Role
+{
+    const ID = 'admin';
+
+    public function getName()
+    {
+        return Piwik::translate('UsersManager_PrivAdmin');
+    }
+
+    public function getId()
+    {
+        return self::ID;
+    }
+
+    public function getDescription()
+    {
+        return Piwik::translate('UsersManager_PrivAdminDescription', array(
+            Piwik::translate('UsersManager_PrivWrite')
+        ));
+    }
+
+    public function getHelpUrl()
+    {
+        return 'https://matomo.org/faq/general/faq_69/';
+    }
+
+}
diff --git a/core/Access/Role/View.php b/core/Access/Role/View.php
new file mode 100644
index 0000000000..c84d1288f5
--- /dev/null
+++ b/core/Access/Role/View.php
@@ -0,0 +1,39 @@
+<?php
+/**
+ * Piwik - free/libre analytics platform
+ *
+ * @link http://piwik.org
+ * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ *
+ */
+namespace Piwik\Access\Role;
+
+use Piwik\Access\Role;
+use Piwik\Piwik;
+
+class View extends Role
+{
+    const ID = 'view';
+
+    public function getName()
+    {
+        return Piwik::translate('UsersManager_PrivView');
+    }
+
+    public function getId()
+    {
+        return self::ID;
+    }
+
+    public function getDescription()
+    {
+        return Piwik::translate('UsersManager_PrivViewDescription');
+    }
+
+    public function getHelpUrl()
+    {
+        return 'https://matomo.org/faq/general/faq_70/';
+    }
+
+
+}
diff --git a/core/Access/Role/Write.php b/core/Access/Role/Write.php
new file mode 100644
index 0000000000..fb0c891688
--- /dev/null
+++ b/core/Access/Role/Write.php
@@ -0,0 +1,38 @@
+<?php
+/**
+ * Piwik - free/libre analytics platform
+ *
+ * @link http://piwik.org
+ * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ *
+ */
+namespace Piwik\Access\Role;
+
+use Piwik\Access\Role;
+use Piwik\Piwik;
+
+class Write extends Role
+{
+    const ID = 'write';
+
+    public function getName()
+    {
+        return Piwik::translate('UsersManager_PrivWrite');
+    }
+
+    public function getId()
+    {
+        return self::ID;
+    }
+
+    public function getDescription()
+    {
+        return Piwik::translate('UsersManager_PrivWriteDescription');
+    }
+
+    public function getHelpUrl()
+    {
+        return '';
+    }
+
+}
diff --git a/core/Access/RolesProvider.php b/core/Access/RolesProvider.php
new file mode 100644
index 0000000000..564d74d860
--- /dev/null
+++ b/core/Access/RolesProvider.php
@@ -0,0 +1,62 @@
+<?php
+/**
+ * Piwik - free/libre analytics platform
+ *
+ * @link http://piwik.org
+ * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ *
+ */
+namespace Piwik\Access;
+
+use Piwik\Access\Role\Admin;
+use Piwik\Access\Role\View;
+use Piwik\Access\Role\Write;
+use Piwik\Piwik;
+use Exception;
+
+class RolesProvider
+{
+    /**
+     * @return Role[]
+     */
+    public function getAllRoles()
+    {
+        return array(
+            new View(),
+            new Write(),
+            new Admin()
+        );
+    }
+
+    /**
+     * Returns the list of the existing Access level.
+     * Useful when a given API method requests a given acccess Level.
+     * We first check that the required access level exists.
+     *
+     * @return array
+     */
+    public function getAllRoleIds()
+    {
+        $ids = array();
+        foreach ($this->getAllRoles() as $role) {
+            $ids[] = $role->getId();
+        }
+        return $ids;
+    }
+
+    public function isValidRole($roleId)
+    {
+        $roles = $this->getAllRoleIds();
+
+        return in_array($roleId, $roles, true);
+    }
+
+    public function checkValidRole($roleId)
+    {
+        if (!$this->isValidRole($roleId)) {
+            $roles = $this->getAllRoleIds();
+            throw new Exception(Piwik::translate("UsersManager_ExceptionAccessValues", implode(", ", $roles)));
+        }
+    }
+
+}