1. This site uses cookies. By continuing to use this site, you are agreeing to our use of cookies. Learn More.

[Docs] Adding Permissions

Discussion in 'Developing Plugins' started by Nick, Sep 27, 2009.

  1. Nick

    Nick Well-Known Member

    Every user is given a role, for example admin or member, and then plugins assign default permissions to those roles. Here's how:

    1. Add your default permissions

    This example function sets default permissions for admin, member and other users. Admins can sing and dance, members can only sing, and others can't do anything. Copy the code into your plugin's install function and edit it to suit your needs:

    PHP:
        /**
         * Install settings if they don't already exist
         */
        
    public function install_plugin($h)
        {
            
    // Permissions
            
    $site_perms $h->getDefaultPermissions('all');
            if (!isset(
    $site_perms['can_sing'])) { 
                
    $perms['options']['can_sing'] = array('yes''no');
                
    $perms['options']['can_dance'] = array('yes''no');
                
                
    $perms['can_sing']['admin'] = 'yes';
                
    $perms['can_sing']['member'] = 'yes';
                
    $perms['can_sing']['default'] = 'no';
                
                
    $perms['can_dance']['admin'] = 'yes';
                
    $perms['can_dance']['member'] = 'no';
                
    $perms['can_dance']['default'] = 'no';
                          
                
    $h->updateDefaultPermissions($perms);
            }
        }
    When the plugin is installed, Hotaru saves two copies in the database - site perms and base perms. In Hotaru 1.0, these are both the same, but in later versions we plan to make a Permissions Manager which will allow admins to customize the site perms, leaving the originals in base perms alone so they can be reverted if necessary.

    The "all" in the getDefaultPermissions function call returns site permissions for all roles. This is required.

    The if conditional is used to see if the permissions have previously been installed. If they have, we skip installing them again.

    The updateDefaultPermissions function call updates both site and base perms.

    We don't use Boolean true or false values because you're not limited to just yes and no. You can extend the array with other choices, too. Some possibilities are:

    • mod - "moderated". You could set up email notification or some kind of pending queue for moderated actions.
    • own - Enable users to perform actions on their own content, e.g. editing their own comments, posts, etc.
    • limit - limit the number of times a user can perform a certain action.
    While those labels are purely suggestions, it would be sensible for developers to stick to common language. If a permission label varies between "own", "self" and "mine", things might get messy.

    2. Add permission tests

    Using your new permissions is quite simple. Here's an example:

    PHP:
    if ($h->currentUser->getPermission('can_sing') == 'yes') { 
        
    $this->playMusic() // call this plugin's playMusic function 
    } else { 
        
    $h->message $h->lang['singing_permission_denied'];
        
    $h->messageType 'red';
        
    $h->showMessage();
    }
    Notes:
     
    Last edited: Jan 6, 2010

Share This Page