New events + some other misc changes (#13388)

* Add Access.modifyUserAccess event.

* Add some template events & use request::process for LanguagesManager API.

* Use the result of Sites.setSites in SitesManager API.

* More comments for Site::setSitesFromArray().

* fixing plugin test.

2 files changed, 41 insertions, 2 deletions

diff --git a/core/Access.php b/core/Access.php
index 591ac4ba38..9d06fc05a4 100644
--- a/core/Access.php
+++ b/core/Access.php
@@ -221,8 +221,8 @@ class Access
         } elseif (isset($this->login)) {
             if (empty($this->idsitesByAccess['view'])
                 && empty($this->idsitesByAccess['write'])
-                && empty($this->idsitesByAccess['admin'])) {
-
+                && empty($this->idsitesByAccess['admin'])
+            ) {
                 // we join with site in case there are rows in access for an idsite that doesn't exist anymore
                 // (backward compatibility ; before we deleted the site without deleting rows in _access table)
                 $accessRaw = $this->getRawSitesWithSomeViewAccess($this->login);
@@ -243,6 +243,35 @@ class Access
                         }
                     }
                 }
+
+                /**
+                 * Triggered after the initial access levels and permissions for the current user are loaded. Use this
+                 * event to modify the current user's permissions (for example, making sure every user has view access
+                 * to a specific site).
+                 *
+                 * **Example**
+                 *
+                 *     function (&$idsitesByAccess, $login) {
+                 *         if ($login == 'somespecialuser') {
+                 *             return;
+                 *         }
+                 *
+                 *         $idsitesByAccess['view'][] = $mySpecialIdSite;
+                 *     }
+                 *
+                 * @param array[] &$idsitesByAccess The current user's access levels for individual sites. Maps role and
+                 *                                  capability IDs to list of site IDs, eg:
+                 *
+                 *                                  ```
+                 *                                  [
+                 *                                      'view' => [1, 2, 3],
+                 *                                      'write' => [4, 5],
+                 *                                      'admin' => [],
+                 *                                  ]
+                 *                                  ```
+                 * @param string $login The current user's login.
+                 */
+                Piwik::postEvent('Access.modifyUserAccess', [&$this->idsitesByAccess, $this->login]);
             }
         }
     }
diff --git a/core/Site.php b/core/Site.php
index ec8efbe01c..e1071b58b2 100644
--- a/core/Site.php
+++ b/core/Site.php
@@ -136,6 +136,7 @@ class Site
      * @param $idSite
      * @param $infoSite
      * @throws Exception if website or idsite is invalid
+     * @internal
      */
     public static function setSiteFromArray($idSite, $infoSite)
     {
@@ -149,12 +150,19 @@ class Site
     /**
      * Sets the cached Site data with a non-associated array of site data.
      *
+     * This method will trigger the `Sites.setSites` event modifying `$sites` before setting cached
+     * site data. In other words, this method will change the site data before it is cached and then
+     * return the modified array.
+     *
      * @param array $sites The array of sites data. eg,
      *
      *                         array(
      *                             array('idsite' => '1', 'name' => 'Site 1', ...),
      *                             array('idsite' => '2', 'name' => 'Site 2', ...),
      *                         )
+     * @return array The modified array.
+     * @deprecated
+     * @internal
      */
     public static function setSitesFromArray($sites)
     {
@@ -168,6 +176,8 @@ class Site
 
             self::setSiteFromArray($idSite, $site);
         }
+
+        return $sites;
     }
 
     /**