How to create roles programmatically

rloyola

Hi,

I have a cutom plugin that needs to create a new role when enabled. Is there a way to do this?

Thanks

R_J

There is no way like there is for e.g. permissions and that is for a reason, I'd say. I cannot imagine many use cases for such a requirement. Maybe a wiki and you want to create a lector role so that this can be used. But that would impose a special workflow to the plugin user, something which would fit for some and would be wrong for others. Therefore I think it is a bad idea to create a role in a plugin.

 

But given that you have asked quite a lot of "how to do this and that in a plugin" and that you haven't published any plugin, I guess this question is also not connected to a plugin that you will publish. Therefore I don't invest much time in telling you that you should better use permissions and leave the role design to the forum owner.

As I said above: there is no automatism like "registerPermissions" in the addon.json. In a plugin there can be a setup() method which is called when the plugin is enabled. If there are any structural changes necessary, like editing/adding a table in the database or even ensuring that there is a special config setting, the corresponding code should be in a method structure(). If you have done that, your plugins setup method could look like that:

public function setup() {
    $this->structure();
}

 

The advantage is that on a yourforum/utility/structure call, all enabled plugins structure methods will be invoked. How a role can be defined, can be seen in the /applications/dashboard/settings/structure.php file:

$RoleModel = new RoleModel();

if (!$RoleTableExists || $Drop) {
   // Define default roles.
   $RoleModel->Database = $Database;
   $RoleModel->SQL = $SQL;
   $Sort = 1;
   $RoleModel->define(['Name' => 'Guest', 'Type' => RoleModel::TYPE_GUEST, 'RoleID' => 2, 'Sort' => $Sort++, 'Deletable' => '0', 'CanSession' => '0', 'Description' => t('Guest Role Description', 'Guests can only view content. Anyone browsing the site who is not signed in is considered to be a "Guest".')]);
   $RoleModel->define(['Name' => 'Unconfirmed', 'Type' => RoleModel::TYPE_UNCONFIRMED, 'RoleID' => 3, 'Sort' => $Sort++, 'Deletable' => '0', 'CanSession' => '1', 'Description' => t('Unconfirmed Role Description', 'Users must confirm their emails before becoming full members. They get assigned to this role.')]);

 

As you can see, you just need to create or get an instance of the RoleModel and use its method define(). But you should only provide Name, Description and Type and leave the rest to be filled out by the model.

 A role without permissions is quite useless by the way. There is no clone() method or anything like that so if you set up a role completely by yourself, you have to define its permissions. If you do not know how to do this (and you're still convinced creating a role in a plugin is a good idea), take a look at the structure file referenced above or inside the structure.php file in the /applications/vanilla/settings folder.

By the way: I assume that you are doing this for some customer. Creating a role is design decision if you ask me, nothing a plugin should do automatically. The content responsible person or the forum admin should be responsible for that.

rloyola

Thanks for all the help especially for the extra information. I trust your experience in this.