Make a hierarchy in roles

This is more understandable for users.

Security/ProvideRoleHierarchyInterface.php

@@ -0,0 +1,42 @@
+<?php
+/*
+ * Copyright (C) 2017 Champs Libres Cooperative <info@champs-libres.coop>
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+namespace Chill\MainBundle\Security;
+
+/**
+ * Give a hierarchy for the role. 
+ * 
+ * This hierarchy allow to sort roles, which is useful in UI
+ *
+ * @author Julien Fastré <julien.fastre@champs-libres.coop>
+ */
+interface ProvideRoleHierarchyInterface extends ProvideRoleInterface
+{
+    /**
+     * Return an array of roles, where keys are the hierarchy, and values
+     * an array of roles.
+     * 
+     * Example: 
+     * 
+     * ```
+     * [ 'Title' => [ 'CHILL_FOO_SEE', 'CHILL_FOO_UPDATE' ] ]
+     * ```
+     * 
+     * @return array where keys are the hierarchy, and values an array of roles: `[ 'title' => [ 'CHILL_FOO_SEE', 'CHILL_FOO_UPDATE' ] ]`
+     */
+    public function getRolesWithHierarchy();
+}

Security/RoleProvider.php

@@ -32,6 +32,16 @@ class RoleProvider
      */
     private $providers = array();
     
+    /**
+     * an array where keys are the role, and value is the title
+     * for the given role.
+     * 
+     * Null when not initialized.
+     *
+     * @var array|null
+     */
+    private $rolesTitlesCache = null;
+    
     /**
      * Add a role provider
      * 
@@ -75,4 +85,52 @@ class RoleProvider
         return $roles;
     }
     
+    /**
+     * initialize the array for caching role and titles
+     * 
+     */
+    private function initializeRolesTitlesCache()
+    {
+        // break if already initialized
+        if ($this->rolesTitlesCache !== null) {
+            return;
+        }
+        
+        foreach ($this->providers as $provider) {
+            if ($provider instanceof ProvideRoleHierarchyInterface) {
+                foreach ($provider->getRolesWithHierarchy() as $title => $roles) {
+                    foreach($roles as $role) {
+                        $this->rolesTitlesCache[$role] = $title;
+                    }
+                }
+            } else {
+                if ($provider->getRoles() !== null) {
+                    $this->rolesTitlesCache = \array_merge(
+                        $this->rolesTitlesCache, 
+                        \array_fill_keys($provider->getRoles(), null)
+                        );
+                }
+            }
+        }
+    }
+    
+    /**
+     * Get the title for each role.
+     * 
+     * @param string $role
+     * @return string the title of the role
+     */
+    public function getRoleTitle($role)
+    {
+        $this->initializeRolesTitlesCache();
+        
+        if (! \array_key_exists($role, $this->rolesTitlesCache)) {
+            // this case might happens when the role is not described in 
+            // `getRolesWithHierarchy`
+            return null;
+        }
+        
+        return $this->rolesTitlesCache[$role];
+    }
+    
 }