Permissions in Phorum 5
=======================

This document describes the way the permission system of Phorum works.
It is targeted at developers that need inside information on the
API calls that are related to permission handling.

Table of contents:

1. Checking user permissions
2. Modifying user permissions
3. Some final notes


1. Checking user permissions
-------------------------------------------------------------------------------

   First and foremost, your code should use the function called
   phorum_user_access_allowed() to check for a given user permission
   in the current forum. However, if you find yourself needing to check
   the permisssion directly, here is some information.
   
   Permissions are stored using a bitmask. To check for a certain permission, 
   simply use the bitwise AND (&) operator to match the permission against the
   user's permissions.
   
   For example, if we want to check if a user has permission to read
   a particular forum, we would use the following if statement:
   
      if($PHORUM["user"]["permissions"] & PHORUM_USER_ALLOW_READ){
          // the user can read this forum
      } else {
          // the user can NOT read this forum
      }


2. Modifying user permissions
-------------------------------------------------------------------------------

   If you need to modify the permissions, use the bitwise OR (|) to add
   a permission or the bitwise XOR (^) to remove a permission. After you
   make the change, save the user. Here is some example code:
   
      // add new topic permissions
      $permissions = $PHORUM["user"]["permissions"] | PHORUM_USER_ALLOW_NEW_TOPIC;
      $userdata = array(
          "user_id" => $PHORUM["user"]["user_id"],
          "permissions" => $permissions
      );
      phorum_user_save($userdata);
  
      // remove new topic permissions
      $permissions = $PHORUM["user"]["permissions"] ^ PHORUM_USER_ALLOW_NEW_TOPIC;
      $userdata = array(
          "user_id" => $PHORUM["user"]["user_id"],
          "permissions" => $permissions
      );
      phorum_user_save($userdata);
   

3. Some final notes
-------------------------------------------------------------------------------

   That should be all you need to know about the Phorum permission system.
   Here is some stuff that helped explain this to the other developers:
   
   > select (256 | 16);  
   > That OR's the two numbers together.
   > you get 272
   > then:
   > select 16 & 272;
   > That returns 16.
   > So, in our data, the 272 represents what is in the database.
   > The 16 would be one of the permission constancts
   > Our constants would look like this:
   >     define("PHORUM_USER_ALLOW_READ", 1);  
   >     define("PHORUM_USER_ALLOW_REPLY", 2); 
   >     define("PHORUM_USER_ALLOW_EDIT", 4); 
   >     define("PHORUM_USER_ALLOW_NEW_TOPIC", 8); 
   >     define("PHORUM_USER_ALLOW_UPLOAD", 16); 
   >     define("PHORUM_USER_ALLOW_ATTACH", 32); 
   >     define("PHORUM_USER_ALLOW_MODERATE_MESSAGES", 64); 
   >     define("PHORUM_USER_ALLOW_MODERATE_USERS", 128); 
   >     define("PHORUM_USER_ALLOW_FORUM_PROPERTIES", 256); 
   > To give someone read and reply, we would set their perm to 1 | 2
   > Then, to check it, we would $user_perm_value & $perm == $perm
   > or in sql
   > where permission & $perm = $perm
   
   Another example to show that the = $perm can be left out:
   
   > select 1 | 2
   > read, reply
   > = 3
   > select 3 & 16
   > =0