MINOR Testing and documenting "super-admin" behaviour on "ADMIN" permission in Subsite::accessible_sites() and Subsite::hasMainSitePermission()

README.md

@@ -67,7 +67,7 @@ This example would let you create subsites such as ''wellington.mycompany.com''
 
 If you would like to be able to choose any domain for your subsite, rather than subdomains off a common base, then list top-level domains in your ''set_allowed_domains()'' list.
 
-In this example, your subsite name, eg, ''silverstripe'', will be appended to a much shorter base domain, eg, ''co.nz'', or ''org''.  This would let you create subsites with domains such as ''silverstripe.org'' or ''example.co.nz''
+In this example, your subsite name (e.g. ''silverstripe''), will be appended to a much shorter base domain (e.g.  ''co.nz'', or ''org'').  This would let you create subsites with domains such as ''silverstripe.org'' or ''example.co.nz''
 
 *mysite/_config.php*
 
@@ -96,6 +96,14 @@ You can mix the two together, if you want to have some subsites hosted off subdo
 
 Note that every site also has a ''www.''-prefixed version of the domain available.  For example, if your subsite is accessible from ''wellington.example.org'' then it will also be accessible from '''www.wellington.example.org''.
 
+### Permissions ###
+
+Groups can be associated with one or more subsites, in which case the granted permissions
+only apply to this subsite. Even the `ADMIN` permission only grants super-user rights on certain
+subsites by default. If you want to create a super-user regardless of subsites association,
+please use the `Group.AccessAllSubsites` property ("Give this group access to all subsites"),
+together with the `ADMIN` permission.
+
 ### Access created domains
 
 Once you have created some subsites/domains in your admin, you can check the overall functionality of subsites by

code/Subsite.php

@@ -359,6 +359,19 @@ JS;
 	
 	}
 
+	/**
+	 * Checks if a member can be granted certain permissions, regardless of the subsite context.
+	 * Similar logic to {@link Permission::checkMember()}, but only returns TRUE
+	 * if the member is part of a group with the "AccessAllSubsites" flag set.
+	 * If more than one permission is passed to the method, at least one of them must
+	 * be granted for if to return TRUE.
+	 * 
+	 * @todo Allow permission inheritance through group hierarchy.
+	 * 
+	 * @param Member Member to check against. Defaults to currently logged in member
+	 * @param Array Permission code strings. Defaults to "ADMIN".
+	 * @return boolean
+	 */
 	static function hasMainSitePermission($member = null, $permissionCodes = array('ADMIN')) {
 		if(!is_array($permissionCodes))
 			user_error('Permissions must be passed to Subsite::hasMainSitePermission as an array', E_USER_ERROR);
@@ -433,6 +446,8 @@ JS;
 	 * @param $permCode array|string Either a single permission code or an array of permission codes.
 	 * @param $includeMainSite If true, the main site will be included if appropriate.
 	 * @param $mainSiteTitle The label to give to the main site
+	 * @param $member
+	 * @return DataObjectSet of {@link Subsite} instances
 	 */
 	function accessible_sites($permCode, $includeMainSite = false, $mainSiteTitle = "Main site", $member = null) {
 		// Rationalise member arguments

tests/SubsiteTest.php

@@ -124,6 +124,46 @@ class SubsiteTest extends SapphireTest {
 			'Test 3',
 		), $adminSiteTitles);
 	}
+	
+	function testhasMainSitePermission() {
+		$admin = $this->objFromFixture('Member', 'admin');
+		$subsite1member = $this->objFromFixture('Member', 'subsite1member');
+		$subsite1admin = $this->objFromFixture('Member', 'subsite1admin');
+		$allsubsitesauthor = $this->objFromFixture('Member', 'allsubsitesauthor');
+		
+		$this->assertTrue(
+			Subsite::hasMainSitePermission($admin), 
+			'Default permissions granted for super-admin'
+		);
+		$this->assertTrue(
+			Subsite::hasMainSitePermission($admin, array("ADMIN")), 
+			'ADMIN permissions granted for super-admin'
+		);
+		$this->assertFalse(
+			Subsite::hasMainSitePermission($subsite1admin, array("ADMIN")), 
+			'ADMIN permissions (on main site) denied for subsite1 admin'
+		);
+		$this->assertFalse(
+			Subsite::hasMainSitePermission($subsite1admin, array("CMS_ACCESS_CMSMain")), 
+			'CMS_ACCESS_CMSMain (on main site) denied for subsite1 admin'
+		);
+		$this->assertFalse(
+			Subsite::hasMainSitePermission($allsubsitesauthor, array("ADMIN")), 
+			'ADMIN permissions (on main site) denied for CMS author with edit rights on all subsites'
+		);
+		$this->assertTrue(
+			Subsite::hasMainSitePermission($allsubsitesauthor, array("CMS_ACCESS_CMSMain")), 
+			'CMS_ACCESS_CMSMain (on main site) granted for CMS author with edit rights on all subsites'
+		);
+		$this->assertFalse(
+			Subsite::hasMainSitePermission($subsite1member, array("ADMIN")), 
+			'ADMIN (on main site) denied for subsite1 subsite1 cms author'
+		);
+		$this->assertFalse(
+			Subsite::hasMainSitePermission($subsite1member, array("CMS_ACCESS_CMSMain")), 
+			'CMS_ACCESS_CMSMain (on main site) denied for subsite1 cms author'
+		);
+	}
 
 	function testDuplicateSubsite() {
 		// get subsite1 & create page

tests/SubsiteTest.yml

@@ -87,6 +87,15 @@ Group:
       Code: subsite2_group
       AccessAllSubsites: 0
       Subsites: =>Subsite_Template.subsite2
+   subsite1admins:
+      Title: subsite1admins
+      Code: subsite1admins
+      AccessAllSubsites: 0
+      Subsites: =>Subsite_Template.subsite1
+   allsubsitesauthors:
+      Title: allsubsitesauthors
+      Code: allsubsitesauthors
+      AccessAllSubsites: 1
 Permission:
    admin:
       Code: ADMIN
@@ -97,12 +106,21 @@ Permission:
    accesscmsmain2:
       Code: CMS_ACCESS_CMSMain
       GroupID: =>Group.subsite2_group
+   accesscmsmain3:
+      Code: CMS_ACCESS_CMSMain
+      GroupID: =>Group.subsite1admins
+   accesscmsmain4:
+      Code: CMS_ACCESS_CMSMain
+      GroupID: =>Group.allsubsitesauthors
    securityaccess1:
       Code: CMS_ACCESS_SecurityAdmin
       GroupID: =>Group.subsite1_group
    securityaccess2:
       Code: CMS_ACCESS_SecurityAdmin
       GroupID: =>Group.subsite2_group
+   adminsubsite1:
+      Code: ADMIN
+      GroupID: =>Group.subsite1admins
 
 Member:
    admin:
@@ -116,4 +134,10 @@ Member:
       Groups: =>Group.subsite1_group
    subsite2member:
       Email: subsite2member@test.com
-      Groups: =>Group.subsite2_group
+      Groups: =>Group.subsite2_group
+   subsite1admin:
+      Email: subsite1admin@test.com
+      Groups: =>Group.subsite1admins
+   allsubsitesauthor:
+      Email: allsubsitesauthor@test.com
+      Groups: =>Group.allsubsitesauthors