Advanced Permissions w/ Code in concrete5 ver 5.6+


The permissions model changed drastically with the last version of concrete5. I had to migrate a project started last October to the newer core today. This post documents what I found out about updating things after spending all day trying to sort through the core.

The Problem

It seemed like a pretty simple thing, really. Well, maybe not quite that simple...

I have a dashboard page that people can use to create pages that represent communities. There is a 'simple' and a 'advanced' format for each. Those are copied from a hidden node off of the page root to keep page structure, the advanced starts out with mutliple pages beneath it, but the basic does not. The dashboard page is actually creating a custom 'community' object which interfaces with a couple of other custom objects that attach to it, and the page created when the community is added. This allows me to use page attributes on the custom object without creating my own attribute category but still validate them, since the custom object validates the attributes before creating the page / saving the form.  The custom object also has custom lists that allows them to be filtered both on the page attributes and on the associated custom objects.

It actually worked really well in 5.5 when I first wrote it. But when I started, all I had was wireframes. Now that we finally have the design for the site, so I was going to upgrade. Since there have been such improvements (well, besides the bugs) in 5.6 and we didn't have any content or anything to work on, I started in on the theme. Once I had that, I needed to add in data to match what I had in the previous site. I didn't really want to upgrade, so I started over from scratch.

I had installed my package when I started everything again, but didn't check that closely on how it installed. It made the single pages and everything, there were page types and the proper attributes, that means it's all working fine, right?

Not even close.

On install, it creates two new groups for managing the pages. Those groups need to have access to the dashboard sections that allow them to create and edit the pages and custom objects. I noticed that a page no longer being used any more was included today, so I went to fix the install to no longer create it.

That's when I noticed that my code was totally wrong. The permissions were all set up for 5.5 syntax (actually, it's probably older than that) and I needed to update.

No big deal, right? I already had done some research into setting advanced permissions in 5.6 for our Hutman News Add On, so I didn't think it would be too hard.

Updating the page permissions on the dashboard was pretty easy. It's a bit like this:

$dash = Page::getByPath('/dashboard');
$dash->assignPermissions(Group::getByID(GUEST_GROUP_ID), $viewOnly, -1);
$dash->assignPermissions(Group::getByID(REGISTERED_GROUP_ID), $viewOnly, -1);
$dash->assignPermissions(Group::getByID($communityAdministratorsID), $viewOnly);
$dash->assignPermissions(Group::getByID($communitySuperAdministratorsID), $viewOnly);
$dash->assignPermissions(Group::getByID(ADMIN_GROUP_ID), $adminPage);

Honestly, that's a lot better than it was before:

$def = SinglePage::add('/dashboard/communities', $pkg);
$def->update(array('cName' => t('Communities'), 'cDescription' => t('Manage Communities')));

$pxml->guests['canRead'] = false;
$pxml->registered['canRead'] = false;
$pxml->group[0]['gID'] = ADMIN_GROUP_ID;
$pxml->group[0]['canRead'] = true;
$pxml->group[0]['canWrite'] = true;
$pxml->group[0]['canApproveVersions'] = true;
$pxml->group[0]['canReadVersions'] = true;
$pxml->group[0]['canDelete'] = true;
$pxml->group[0]['canAdmin'] = true;
$pxml->group[1]['gID'] = $communitySuperAdministratorsID;
$pxml->group[1]['canRead'] = true;
$pxml->group[1]['canWrite'] = true;
$pxml->group[1]['canApproveVersions'] = true;
$pxml->group[1]['canReadVersions'] = true;
$pxml->group[1]['canDelete'] = true;
$pxml->group[1]['canAdmin'] = true;
$pxml->group[2]['gID'] = $communityAdministratorsID;
$pxml->group[2]['canRead'] = true;
$pxml->cInheritPermissionsFrom = "OVERRIDE";

Actually Trying To Get Advanced

The thing here was that I needed to do more than just set regular page permissions. I needed to allow only certain types of sub-pages underneath this section. That code wasn't really documented anywhere. In the GUI, it's pretty simple. You add a group to the "Add Sub Page" permission, choose what types they can do and hit save. 

It was pretty simple, if really verbose in 5.5:

$cAID = Group::getByName("Community Administrators")->getGroupID();
$cSAID = Group::getByName("Community Super Administrators")->getGroupID();

$perm = array();
// Overall Permissions 
$perm['cInheritPermissionsFrom'] = "OVERRIDE";
// subpages inherit permissions from this page
$perm['cOverrideTemplatePermissions'] = 1;
// subpages inherit permissions from page type defaults in dashboard
//$perm['cOverrideTemplatePermissions'] = 1;

// edit permissions
$perm['collectionRead'] = array();
$perm['collectionRead'][] = "gID:" . GUEST_GROUP_ID;
$perm['collectionRead'][] = "gID:" . REGISTERED_GROUP_ID;
$perm['collectionRead'][] = "gID:" . ADMIN_GROUP_ID;
$perm['collectionRead'][] = "gID:" . $cAID;
$perm['collectionRead'][] = "gID:" . $cSAID;
$perm['collectionRead'][] = "uID:" . $data['uID'];
$perm['collectionReadVersions'] = array();
$perm['collectionReadVersions'][] = "gID:" . ADMIN_GROUP_ID;
$perm['collectionReadVersions'][] = "gID:" . $cSAID;
$perm['collectionReadVersions'][] = "uID:" . $data['uID'];
$perm['collectionWrite'] = array();
$perm['collectionWrite'][] = "gID:" . ADMIN_GROUP_ID;
$perm['collectionWrite'][] = "gID:" . $cSAID;
$perm['collectionWrite'][] = "uID:" . $data['uID'];
$perm['collectionApprove'] = array();
$perm['collectionApprove'][] = "gID:" . ADMIN_GROUP_ID;
$perm['collectionApprove'][] = "gID:" . $cSAID;
$perm['collectionApprove'][] = "uID:" . $data['uID'];
$perm['collectionDelete'] = array();
$perm['collectionDelete'][] = "gID:" . ADMIN_GROUP_ID;
$perm['collectionDelete'][] = "gID:" . $cSAID;
$perm['collectionAdmin'] = array();
$perm['collectionAdmin'][] = "gID:" . ADMIN_GROUP_ID;
$perm['collectionAdmin'][] = "gID:" . $cSAID;
$perm['collectionAdmin'][] = "uID:" . $data['uID'];

// sub page permissions

$ccalendarCTID = CollectionType::getByHandle('community_calendar')->getCollectionTypeID();
$cgalleryCTID = CollectionType::getByHandle('community_gallery')->getCollectionTypeID();
$cinfoCTID = CollectionType::getByHandle('community_info')->getCollectionTypeID();
$clocationCTID = CollectionType::getByHandle('community_location')->getCollectionTypeID();
$eventCTID = CollectionType::getByHandle('event_page')->getCollectionTypeID();

$perm['collectionAddSubCollection'] = array();
$perm['collectionAddSubCollection'][$ccalendarCTID] = array();
$perm['collectionAddSubCollection'][$ccalendarCTID][] = "gID:" . ADMIN_GROUP_ID;
$perm['collectionAddSubCollection'][$ccalendarCTID][] = "gID:" . $cSAID;
$perm['collectionAddSubCollection'][$ccalendarCTID][] = "uID:" . $data['uID'];

$perm['collectionAddSubCollection'][$cgalleryCTID] = array();
$perm['collectionAddSubCollection'][$cgalleryCTID][] = "gID:" . ADMIN_GROUP_ID;
$perm['collectionAddSubCollection'][$cgalleryCTID][] = "gID:" . $cSAID;
$perm['collectionAddSubCollection'][$cgalleryCTID][] = "uID:" . $data['uID'];

$perm['collectionAddSubCollection'][$cinfoCTID] = array();
$perm['collectionAddSubCollection'][$cinfoCTID][] = "gID:" . ADMIN_GROUP_ID;
$perm['collectionAddSubCollection'][$cinfoCTID][] = "gID:" . $cSAID;
$perm['collectionAddSubCollection'][$cinfoCTID][] = "uID:" . $data['uID'];

$perm['collectionAddSubCollection'][$clocationCTID] = array();
$perm['collectionAddSubCollection'][$clocationCTID][] = "gID:" . ADMIN_GROUP_ID;
$perm['collectionAddSubCollection'][$clocationCTID][] = "gID:" . $cSAID;
$perm['collectionAddSubCollection'][$clocationCTID][] = "uID:" . $data['uID'];

$perm['collectionAddSubCollection'][$eventCTID] = array();
$perm['collectionAddSubCollection'][$eventCTID][] = "gID:" . ADMIN_GROUP_ID;
$perm['collectionAddSubCollection'][$eventCTID][] = "gID:" . $cSAID;
$perm['collectionAddSubCollection'][$eventCTID][] = "uID:" . $data['uID'];


It's a lot more involved, but really, it's not complicated. It was a quite simple matter to figure out how to set this up, even though there really wasn't much for documentation at all. Just looking at the $_POST values from the ajax submit gets you a lot of the way there.

5.6 is so amazingly, radically different in how everything works. All of the stuff that happens from the time you open the edit properties dialog involves a ton of different models, tools files, and elements. At one point I had at least 40 files open and was trying to follow how things passed through them and reverse engineer it to figure out where to go for a simple kind of 'shortcut' method to get where I needed to be.

It took me ALL DAMN DAY to figure it out. I had another dev in the #concrete5 room on freenode (Raverix on try and help me out. He came up with a few working bits of code, but nothing that I could figure out how to modify to do exactly what I wanted to do. And it was assuming a lot of stuff would be hard coded when I needed to know how to get the values properly from  things properly. I don't know where the IDs for several things are coming from, they were part of URL parameters in most of the tools requests, but how the objects fit together to generate those IDs was not straightforward at all. His last solution apparently worked, but with a core modification to make getID() on the Concrete5_Model_PermissionAccess model. I personally don't mind overriding the core, but when making code for clients that don't use our white labeled version and code that will be used in other places (this might very well become another marketplace add on) I don't want to go that route if there's a way around it.

Finding The Answer

I had been going through the files for a long, long time when I finally found what I needed. I'd been tracing stuff, then running searches for function and variable names to find different files that used it. The place that actually had what I was looking for was in the 5.6 upgrade script : {site_root}/concrete/helpers/upgrade/version_560.php

If I had of thought about it more before trying to find the answer, I could have known that the answer would be in this file. Back in the day (before XML/db installations) the site install controller taught me a ton about how to use the API to do stuff. All the pages, attributes, permissions, etc were installed via the API back when I started. There was even a start on custom installs via a menu (long before 'default' and 'empty' and 'whatever you make if you are smart enough to create your own') where the dropdown would control what creation script was included. 

Of course the upgrade script would have it. It has to modify the permissions from the old syntax. While that means some straight-from-the-db stuff and exploding strings containing the permissions, it was 90% of the way there.

These were the two functions that were key:

// This is actually where I looked, but it seems like the next function would be better. 
// This function updates permissions for page type masters, I think.

protected function migratePagePermissionPageTypes() {
	$db = Loader::db();
	$tables = $db->MetaTables();
	if (!in_array('PagePermissionPageTypes', $tables)) {
		return false;

	$r = $db->Execute('select distinct cID from PagePermissionPageTypes order by cID asc');	
	$pk = PermissionKey::getByHandle('add_subpage');
	while ($row = $r->FetchRow()) {
		$args = array();
		$entities = array();
		$ro = $db->Execute('select ctID, uID, gID from PagePermissionPageTypes where cID = ?', array($row['cID']));
		while ($row2 = $ro->FetchRow()) { 
			$pe = $this->migrateAccessEntity($row2);			
			if (!$pe) {
			if (!in_array($pe, $entities)) {
				$entities[] = $pe;				
			$args['allowExternalLinksIncluded'][$pe->getAccessEntityID()] = 1;
			$args['pageTypesIncluded'][$pe->getAccessEntityID()] = 'C';
			$args['ctIDInclude'][$pe->getAccessEntityID()][] = $row2['ctID'];
		$co = Page::getByID($row['cID']);
		if (is_object($co) && (!$co->isError())) { 
			$pt = $pk->getPermissionAssignmentObject();
			$pa = $pk->getPermissionAccessObject();
			if (!is_object($pa)) {
				$pa = PermissionAccess::create($pk);
			foreach($entities as $pe) {
				$pa->addListItem($pe, false, PagePermissionKey::ACCESS_TYPE_INCLUDE);	

// Even though I didn't use it, this is probably the better function to look at...

protected function migratePagePermissions() {
	$db = Loader::db();
	$tables = $db->MetaTables();
	if (!in_array('PagePermissions', $tables)) {
		return false;
	// first, we fix permissions that are set to override but are pointing to another page. They shouldn't do that.
	$db->Execute('update Pages set cInheritPermissionsFromCID = cID where cInheritPermissionsFrom = "OVERRIDE"');
	// permissions
	$waSet = array(
	if (PERMISSIONS_MODEL == 'simple') {
		$waSet[] = PermissionKey::getByHandle('approve_page_versions');
		$waSet[] = PermissionKey::getByHandle('delete_page_versions');
		$waSet[] = PermissionKey::getByHandle('add_subpage');
	$permissionMap = array(
		'r' => array(PermissionKey::getByHandle('view_page')),
		'rv' => array(PermissionKey::getByHandle('view_page_versions')),
		'wa' => $waSet,
		'adm' => array(
		'dc' => array(
		'av' => array(
		'db' => array(PermissionKey::getByHandle('edit_page_contents'))	

	$r = $db->Execute('select * from PagePermissions order by cID asc');	
	while ($row = $r->FetchRow()) {
		$pe = $this->migrateAccessEntity($row);
		if (!$pe) {
		$permissions = $this->getPermissionsArray($row['cgPermissions']);
		$co = Page::getByID($row['cID']);
		foreach($permissions as $p) {
			$permissionsToApply = $permissionMap[$p];
			foreach($permissionsToApply as $pko) {
				$pt = $pko->getPermissionAssignmentObject();
				$pa = $pko->getPermissionAccessObject();
				if (!is_object($pa)) {
					$pa = PermissionAccess::create($pko);
				$pa->addListItem($pe, false, PagePermissionKey::ACCESS_TYPE_INCLUDE);	

// This was the key part. I really didn't get what the "AccessEntities" were or how to use them
// I didn't even know there were different classes. But I knew I needed them to actually assign
// permissions to the pages. I still don't quite understand them. Wish there was better documentation...

protected function migrateAccessEntity($row) {
	if ($row['uID'] > 0) {
		$ui = UserInfo::getByID($row['uID']);
		if ($ui) { 
			$pe = UserPermissionAccessEntity::getOrCreate($ui);
	} else {
		$g = Group::getByID($row['gID']);
		if ($g) { 
			$pe = GroupPermissionAccessEntity::getOrCreate($g);
	return $pe;		

I know, I should probably try and get better at figuring things out without code samples, but a lot of stuff like this I do have trouble with. When I see something like the code from the upgrade controller, it's all together, there's not a lot of ambiguity, it's not passing things through multiple files via ajax and elements.

It's really the access entity getOrCreate that was the key. From what I can tell, and I haven't done a lot of testing, it seems like this creates a unique entry for any object that can have permissions. There are several different types you can specify:

  • group
  • user
  • group_set
  • group_combination
  • page_owner
  • file_uploader

I don't know how to use file_uploader or page_owner, but the others seem pretty straightforward. So before you actually assign permissions to an object like a page for one of those groups, you have to create a PermissionAccessEntity object, which keeps a reference to the type that it is. There are also tables for groups, users, etc, that tie back to the PermissionAccessEntities table, which then ties into the PermissionAccessEntitiesTypes table.

So, once you create an entity for a user or group or whatever, that ID is used to tie it to the permissions on any object. So when you add a user to the permission set for a page, you need to pass in the UserInfo object for that user and either get or create a key that can be bound to. Once it exists, it can be used to reference whatever that ID ties to. So it could be permissions for a page, or a file, or whatever, but they would all use the same identifier.

At least, that's my rudimentary understanding of what's happening after spending today trying to reverse engineer it.

It makes sense, but knowing what objects to access was pretty hard to figure out. I'm still not really sure how they're all supposed to fit together, honestly. But I was able to figure out at least this much. I think that there are other models for the ones I'm not using to create the other kinds of objects. After I figured out how to do it, I kind of stopped trying to figure it out.

Next Steps

I think I'm really going to need to do a lot more research into this and a lot of experiments in order to figure out what's actually going on between all these different items. Looking at it, it really does seem like a much better system. If it's correctly understood, you could create custom permissions for custom objects and attach workflows to them so that other people have to approve whatever is done to those objects. There is so much potential power here that it's pretty insane. I'm not sure how it is in other systems, but to me it seems a lot more thought out than what I've seen in the other content management systems that I've used. 

I really wish that there was better documentation on it, though. Really, that's one of the biggest gripes that people have with the system. I learned a whole lot of what I know by simply reading the core and stepping through things that I didn't understand through the debugger. But really, is that a solution for most people? I have people come into the IRC room all the time that are obviously good programmers with a lot of experience doing things that simply can't figure out how to do "X" in c5. I've also seen a lot of code that was sent to me to fix by developers that obviously had been using object oriented PHP for a long time, but had no idea whatsoever how to do simple things. 

Stuff like this, for sure it's more complicated. But it's things that serious developers need to know how to do and that need an easy, defined API for doing in code. Every new version of concrete5 has tons of awesome new features, and a lot of them are really easy to understand. But some of the most important features? They're not documented at all, and at best have a footnote in the version notes. The documentation also doesn't make any reference to what version it's for, so you could be looking at something completely out of date for what you want to do. Most of the core architecture, concepts, etc, are the same. Creating a theme? Exactly the same process as what I did 4 years ago.

But things like how to use advanced permissions as a developer? Nothing. I couldn't even find anyone else wanting to do something like this and asking questions. It makes me wonder if there are many people out there trying to do this kind of stuff, and where they are? 

At any rate, I'm happy that I figured out at least this much. I just wish that it wasn't pretty much an entire day of production trying to figure out what to do for such a simple task.