Source for file user-defs.php

Documentation is available at user-defs.php

  1. <?php
  2. /* ******************************************************************** */
  3. /* CATALYST PHP Source Code */
  4. /* -------------------------------------------------------------------- */
  5. /* This program is free software; you can redistribute it and/or modify */
  6. /* it under the terms of the GNU General Public License as published by */
  7. /* the Free Software Foundation; either version 2 of the License, or */
  8. /* (at your option) any later version. */
  9. /* */
  10. /* This program is distributed in the hope that it will be useful, */
  11. /* but WITHOUT ANY WARRANTY; without even the implied warranty of */
  12. /* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the */
  13. /* GNU General Public License for more details. */
  14. /* */
  15. /* You should have received a copy of the GNU General Public License */
  16. /* along with this program; if not, write to: */
  17. /* The Free Software Foundation, Inc., 59 Temple Place, Suite 330, */
  18. /* Boston, MA 02111-1307 USA */
  19. /* -------------------------------------------------------------------- */
  20. /* */
  21. /* Filename: user-defs.php */
  22. /* Author: Paul Waite */
  23. /* Description: Definitions for managing USERS */
  24. /* */
  25. /* ******************************************************************** */
  26. /** @package core *//**
  27. * The user class
  28. * This class managed users. It pre-supposes a particular database
  29. * structure based on three tables: uuser, ugroup, and uuser_group.
  30. * Please see the example schemas for Phplib for further details.
  31. * @package core
  32. */
  33. class user {
  34. /** Login user id, string */
  35.  
  36. var $userid = "";
  37. /** True if user record is valid */
  38.  
  39. var $valid = false;
  40. /** Optional authorisation hash code */
  41.  
  42. var $auth_code = "";
  43. /** Full name */
  44.  
  45. var $name = "";
  46. /** Text password (encrypted or plain) */
  47.  
  48. var $password = "";
  49. /** Password encryption flag */
  50.  
  51. var $encrypted_passwords = false;
  52. /** User e-mail address */
  53.  
  54. var $email = "";
  55. /** User type: arbitrary textual type */
  56.  
  57. var $user_type = "";
  58. /** True of user is active/enabled */
  59.  
  60. var $enabled = false;
  61. /** Total logins so far */
  62.  
  63. var $total_logins = 0;
  64. /** Limit of logins allowed (0=unlimited) */
  65.  
  66. var $limit_logins = 0;
  67. /** True if user has a group membership */
  68.  
  69. var $hasgroups = false;
  70. /** Array of group membership names (strings) */
  71.  
  72. var $group_names = array();
  73. /** Group membership details in full, as associative array */
  74.  
  75. var $group_info;
  76. /** Group membership count */
  77.  
  78. var $user_groups_cnt = 0;
  79. /** Complete user record as an associative array */
  80.  
  81. var $user_record;
  82. /** List of IP addresses this user will be auto-logged-in from. */
  83.  
  84. var $IP;
  85. /** Flag, true if user has auto-login IP addresses */
  86.  
  87. var $hasIPlist = false;
  88. // .....................................................................
  89. /**
  90. * Constructor
  91. * Create a new user object.
  92. * @param string $userid User ID of the user
  93. */
  94. function user($userid="") {
  95. $this->userid = $userid;
  96. // A special case provided for making a brand new
  97. // user object for a new user record..
  98. if ($userid == "#new#") {
  99. // A new user profile..
  100. $this->valid = true;
  101. $this->name = "--enter user name--";
  102. $this->user_type = "user";
  103. $this->group_info[2] = "User"; // User
  104. $this->group_names[] = "User"; // User
  105. $this->user_groups_cnt = 1;
  106. $this->hasgroups = true;
  107. $this->userid = "<enter user id>";
  108. }
  109. // A normal user..
  110. else {
  111. // If id supplied, get user details..
  112. if ($userid != "") {
  113. $this->get_user_by_id($userid);
  114. }
  115. }
  116. return $this->valid;
  117. } // user
  118. // .....................................................................
  119. /**
  120. * Set the password encryption flag. If passed in true, then we will be
  121. * assuming that new passwords should be encrypted, and password checks
  122. * will try encryption first, then fall back to basic.
  123. * @param string $mode True if we are encrypting passwords, else false
  124. */
  125. function set_encrypted_passwords($mode=true) {
  126. $this->encrypted_passwords = $mode;
  127. } // set_encrypted_passwords
  128. // .....................................................................
  129. /**
  130. * Set the user login password. Store it according to the encryption
  131. * mode. We assume a plain text password is being supplied.
  132. * NB: Axyl-encrypted passwords always have an 'axenc_' prefix.
  133. * @param string $plainpass Plain text password to set for this user
  134. * $return string The password which is going to be stored
  135. */
  136. function set_password($plainpass) {
  137. if ($this->encrypted_passwords) {
  138. $password = "axenc_" . md5($password);
  139. }
  140. $this->password = $password;
  141. $this->user_record["password"] = $password;
  142. return $password;
  143. } // set_password
  144. // .....................................................................
  145. /**
  146. * Authenticate a user
  147. * Tries all types of authentication we know about using the parameters
  148. * passed to it.
  149. * @param string $authid Unique user ID, authorization code or IP
  150. * @param string $password Password for the user
  151. * @return integer Login type code
  152. */
  153. function authenticate($authid, $password="") {
  154. $login_type = authenticate_userid($authid, $password);
  155. if ($login_type == LOGIN_UNKNOWN) {
  156. $login_type = authenticate_ip($authid);
  157. if ($login_type == LOGIN_UNKNOWN) {
  158. $login_type = authenticate_authid($authid);
  159. }
  160. }
  161. return $login_type;
  162. } // authenticate
  163. // .....................................................................
  164. /**
  165. * Authenticate a user by userid/password.
  166. * @param string $userid Unique user ID of the user
  167. * @param string $password Password for the user
  168. * @return integer Login type code
  169. */
  170. function authenticate_userid($userid, $password="") {
  171. $login_type = LOGIN_UNKNOWN;
  172. // Guest authentication..
  173. if (stristr($userid, "guest")) {
  174. if ($this->user("guest") && $this->enabled) {
  175. $login_type = LOGIN_BY_GUEST;
  176. }
  177. }
  178. // Authentication by userid and password..
  179. elseif ($this->get_user_by_id($userid)) {
  180. if ($this->enabled) {
  181. // First try to match plain text..
  182. if ($this->password == $password) {
  183. $login_type = LOGIN_BY_PASSWD;
  184. debugbr("authenticated: plaintext password", DBG_DEBUG);
  185. if ($this->encrypted_passwords) {
  186. debugbr("warning: password should be encrypted!", DBG_DEBUG);
  187. }
  188. }
  189. else {
  190. // Try encrypted password match..
  191. $password = "axenc_" . md5($password);
  192. if ($this->password == $password) {
  193. $login_type = LOGIN_BY_PASSWD;
  194. debugbr("authenticated: encrypted password", DBG_DEBUG);
  195. if (!$this->encrypted_passwords) {
  196. debugbr("warning: password should be UN-encrypted!", DBG_DEBUG);
  197. }
  198. }
  199. }
  200. }
  201. }
  202. // Flag and return result..
  203. if ($login_type != LOGIN_UNKNOWN) debugbr("user '$userid' was authenticated", DBG_DEBUG);
  204. else {
  205. $this->valid = false;
  206. debugbr("user '$userid' failed authentication.", DBG_DEBUG);
  207. }
  208. return $login_type;
  209. } // authenticate_userid
  210. // .....................................................................
  211. /**
  212. * Authenticate a user by IP address
  213. * @param string $ip IP address of remote host accessing this site
  214. * @return integer Login type code
  215. */
  216. function authenticate_ipaddress($ip) {
  217. $login_type = LOGIN_UNKNOWN;
  218. // Authentication by IP..
  219. if ($this->get_user_by_ip($ip)) {
  220. if ($this->enabled) {
  221. $login_type = LOGIN_BY_IP;
  222. }
  223. }
  224. // Flag and return result..
  225. if ($login_type != LOGIN_UNKNOWN) debugbr("IP address '$ip' was authenticated", DBG_DEBUG);
  226. else {
  227. $this->valid = false;
  228. debugbr("IP address '$ip' failed authentication.", DBG_DEBUG);
  229. }
  230. return $login_type;
  231. } // authenticate_ipaddress
  232. // .....................................................................
  233. /**
  234. * Authenticate a user by authorisation ID
  235. * @param string $authid Authorisation code/id of the user
  236. * @return integer Login type code
  237. */
  238. function authenticate_authid($authid) {
  239. $login_type = LOGIN_UNKNOWN;
  240. // Authentication by unique authorsation code..
  241. if ($this->get_user_by_auth_code($authid)) {
  242. if ($this->enabled) {
  243. $login_type = LOGIN_BY_AUTHCODE;
  244. }
  245. }
  246. // Flag and return result..
  247. if ($login_type != LOGIN_UNKNOWN) debugbr("authid '$authid' was authenticated", DBG_DEBUG);
  248. else {
  249. $this->valid = false;
  250. debugbr("user '$authid' failed authentication.", DBG_DEBUG);
  251. }
  252. return $login_type;
  253. } // authenticate_authid
  254. // .....................................................................
  255. /**
  256. * Get user by ID
  257. * Internal function to return the user record from id.
  258. * @param string $userid Unique user ID
  259. * @return bool True if the user was found with the given user ID
  260. */
  261. function get_user_by_id($userid) {
  262. debug_trace($this);
  263. $this->valid = false;
  264. debugbr("get_user_by_id: getting '$userid'", DBG_DEBUG);
  265. $qu = dbrecordset("SELECT * FROM ax_user WHERE user_id='" . addslashes($userid) . "'");
  266. if ($qu->hasdata) {
  267. $this->user_record = $qu->current_row;
  268. $this->valid = true;
  269. $this->assign_vars();
  270. }
  271. debug_trace();
  272. return $this->valid;
  273. } // get_user_by_id
  274. // .....................................................................
  275. /**
  276. * Get user by Authorisation Code
  277. * Internal function to return the user record from auth_code. The
  278. * authorisation code is usually a string containing a complex key
  279. * generated by something like MD5 or better.
  280. * @param string $auth_code Authorisation code to match for this user
  281. * @return bool True if the user was found with the given authorisation code
  282. */
  283. function get_user_by_auth_code($auth_code) {
  284. debug_trace($this);
  285. $this->valid = false;
  286. debugbr("get_user_by_auth_code: getting '$auth_code'", DBG_DEBUG);
  287. $qu = dbrecordset("SELECT * FROM ax_user WHERE auth_code='$auth_code'");
  288. if ($qu->hasdata) {
  289. $this->user_record = $qu->current_row;
  290. $this->valid = true;
  291. $this->assign_vars();
  292. }
  293. debug_trace();
  294. return $this->valid;
  295. } // get_user_by_auth_code
  296. // .....................................................................
  297. /**
  298. * Get user by IP
  299. * Internal function to return the user record which has IP address(es)
  300. * which coincide with the client IP address being used for this access.
  301. * @param string $ip Allowed IP host or network to allow logins from
  302. * @return bool True if a user was found with matching IP address
  303. */
  304. function get_user_by_ip($ip) {
  305. global $RESPONSE;
  306. debug_trace($this);
  307. debugbr("get_user_by_ip: getting '$ip'", DBG_DEBUG);
  308. $this->valid = false;
  309. if ($ip != "") {
  310. if (is_ipaddress($ip)) {
  311. switch ($RESPONSE->datasource->dbtype()) {
  312. case "postgres":
  313. // PostgreSQL support special inet datatype..
  314. $qu = dbrecordset("SELECT * FROM ax_user_ip WHERE ip >>= inet '$ip'");
  315. break;
  316. default:
  317. // All others use string comparison..
  318. $qu = dbrecordset("SELECT * FROM ax_user_ip WHERE ip='$ip'");
  319. }
  320. if ($qu->hasdata) {
  321. $userid = $qu->field("user_id");
  322. $ipcount = $qu->rowcount;
  323. $qu = dbrecordset("SELECT * FROM ax_user WHERE user_id='". addslashes($userid) . "'");
  324. if ($qu->hasdata) {
  325. $this->user_record = $qu->current_row;
  326. $this->valid = true;
  327. $this->assign_vars();
  328. debugbr("IP auth success. User=$this->userid", DBG_DEBUG);
  329. }
  330. $qip = dbrecordset("SELECT * FROM ax_user_ip WHERE user_id='". addslashes($userid) . "'");
  331. if ($qip->hasdata) {
  332. if (isset($this->IP)) unset($this->IP);
  333. $this->hasIPlist = true;
  334. do {
  335. $this->IP[] = $qip->field("ip");
  336. } while ($qip->get_next());
  337. }
  338. // Warning for badly defined IP login data..
  339. if ($ipcount > 1) {
  340. log_sys("WARNING: IP-based login overlap: $ipcount matches for Remote IP='$ip'");
  341. }
  342. }
  343. else {
  344. debugbr("get_user_by_ip: failed to authenticate '$ip'", DBG_DEBUG);
  345. }
  346. }
  347. }
  348. debug_trace();
  349. return $this->valid;
  350. } // get_user_by_ip
  351. // ....................................................................
  352. /**
  353. * Get user Authorisation Code
  354. * Return this user's unique authorisation code; generate
  355. * one if it isn't there yet, from userid and current time.
  356. * @return string The authorisation code for the current user
  357. */
  358. function get_auth_code() {
  359. if ($this->valid) {
  360. if ($this->auth_code == "") {
  361. debug_trace($this);
  362. $seed = $this->userid . $this->name . microtime();
  363. $this->auth_code = md5($seed);
  364. $this->user_record["auth_code"] = $this->auth_code;
  365. dbcommand("UPDATE ax_user SET auth_code='$this->auth_code' WHERE user_id='" . addslashes($this->userid) . "'");
  366. debug_trace();
  367. }
  368. return $this->auth_code;
  369. }
  370. else {
  371. return false;
  372. }
  373. } // get_auth_code
  374. // ....................................................................
  375. /**
  376. * Get user groups info
  377. * For this user, populate the group data for this object. We
  378. * read the uuser_group and ugroup tables and populate the
  379. * two variables @see $user_groups and @see $group_info
  380. * @return string The groups list for the user, delimited by pipe ("|")
  381. */
  382. function get_groups() {
  383. // Initialise..
  384. $ugroups = "";
  385. if (isset($this->group_info)) unset($this->group_info);
  386.  
  387. // User group data acquisition..
  388. $q = "SELECT *";
  389. $q .= " FROM ax_user_group ug, ax_group g";
  390. $q .= " WHERE ug.user_id='" . addslashes($this->userid) . "'";
  391. $q .= " AND g.group_id=ug.group_id";
  392. $group = dbrecordset($q);
  393. if ($group->hasdata) {
  394. $this->hasgroups = true;
  395. do {
  396. $groupid = $group->field("group_id");
  397. $groupname = $group->field("group_desc");
  398. $this->group_info[$groupid] = $groupname;
  399. if ($ugroups != "") $ugroups .= "|";
  400. $ugroups .= $groupname;
  401. } while ($group->get_next());
  402. }
  403. // Force guest users into Guest group..
  404. if (stristr($this->userid, "guest")) {
  405. $ugroups = "Guest";
  406. }
  407. // Assign the group list and count..
  408. $this->group_names = explode("|", $ugroups);
  409. $this->user_groups_cnt = count($this->group_names);
  410.  
  411. // A by-product..
  412. return $ugroups;
  413. } // get_groups
  414. // ....................................................................
  415. /**
  416. * Assign user variables
  417. * Internal function to assign variables from new record..
  418. * @access private
  419. */
  420. function assign_vars() {
  421. global $RESPONSE;
  422. debug_trace($this);
  423. if ($this->valid) {
  424. $this->userid = stripslashes($this->user_record["user_id"]);
  425. $this->name = stripslashes($this->user_record["full_name"]);
  426. $this->email = $this->user_record["email"];
  427. $this->password = $this->user_record["password"];
  428. if (!$this->encrypted_passwords) {
  429. $this->password = stripslashes($this->password);
  430. }
  431. $this->auth_code = $this->user_record["auth_code"];
  432. $this->user_type = $this->user_record["user_type"];
  433. $this->enabled = $RESPONSE->datasource->bool_from_db_value($this->user_record["enabled"]);
  434. $this->total_logins = $this->user_record["total_logins"];
  435. $this->limit_logins = $this->user_record["limit_logins"];
  436. // Get groups info..
  437. $this->get_groups();
  438. }
  439. else {
  440. $this->name = "Error: User not found";
  441. $this->user_type = "user";
  442. }
  443. debug_trace();
  444. } // assign_vars
  445. // ....................................................................
  446. /**
  447. * Is user a member of a named group. The argument passed in must be a
  448. * single group name string (ie. not a numeric group id) which is defined
  449. * in the database.
  450. * Return true if the user is a member of the named group.
  451. * @param string $groupname Name of the group we are checking user membership of
  452. * @return bool True if the user is a member of the group, else false
  453. */
  454. function ismemberof_group($groupname) {
  455. $found = false;
  456. for ($i = 0; $i < $this->user_groups_cnt; $i++) {
  457. if (!strcasecmp(trim($this->group_names[$i]), trim($groupname))) {
  458. $found = true;
  459. break;
  460. }
  461. } // for
  462. return $found;
  463. } // ismemberof_group
  464. // ....................................................................
  465. /**
  466. * Is user a member of one group of many
  467. * Check user against a list of groups, return true if member of at
  468. * least one of them. The list in $groupnames can be either a comma-delimited
  469. * string of group names, OR an array of group names.
  470. * @param mixed $groupnames_list Comma-delimited list OR array of group names
  471. * @return bool True if user is member of at least one of the groups, else false
  472. */
  473. function ismemberof_group_in($groupnames_list) {
  474. if (is_string($groupnames_list)) {
  475. if (trim($groupnames_list) == "") {
  476. return true;
  477. }
  478. $groupnames = explode(",", $groupnames_list);
  479. }
  480. else {
  481. $groupnames = $groupnames_list;
  482. }
  483. $found = false;
  484. if (count($groupnames) == 0) {
  485. return true;
  486. }
  487. foreach ($groupnames as $groupname) {
  488. $found = $this->ismemberof_group($groupname);
  489. if ($found) break;
  490. }
  491. return $found;
  492. } // ismemberof_group_in
  493. // ....................................................................
  494. /**
  495. * Is user a member of a group with ID
  496. * Return true if the user is a member of the group with given ID.
  497. * @param string $groupid ID of the group we are checking user membership of
  498. * @return bool True if the user is a member of the group, else false
  499. */
  500. function ismemberof_group_with_id($groupid) {
  501. if (!isset($this->group_info)) {
  502. $this->get_groups();
  503. }
  504. return (isset($this->group_info[$groupid]));
  505. } // ismemberwith_groupid
  506. // ....................................................................
  507. /**
  508. * Return true if the current user is a valid one. This is false when the
  509. * user has not been authorised, or the user ID wasn't found etc. It is
  510. * an error condition for this to be false.
  511. * @return bool True if the current user object is valid
  512. */
  513. function isvalid() {
  514. return $this->valid;
  515. } // isvalid
  516. // ....................................................................
  517. /**
  518. * Get group IDs list
  519. * Return a string with the comma-delimited list of group ids which this
  520. * user belongs to in it. This is useful for using in an SQL statement like:
  521. * WHERE group_id IN (group_ids_list())
  522. * for example. Note we only access the database to populate $this->group_info
  523. * when we need to, not every session.
  524. * @param string $delim Delimiter character (defaults to comma)
  525. * @return string List of group ID's comma-delimited
  526. */
  527. function group_ids_list($delim=",") {
  528. if (!isset($this->group_info)) {
  529. $this->get_groups();
  530. }
  531. $gplist = array();
  532. if (isset($this->group_info)) {
  533. foreach ($this->group_info as $gid => $gdesc) {
  534. $gplist[] = $gid;
  535. }
  536. }
  537. return implode($delim, $gplist);
  538. } // group_ids_list
  539. // ....................................................................
  540. /**
  541. * Get group names list
  542. * Return a string with the comma-delimited list of group names which this
  543. * user belongs to in it. Eg. "Editor,Author,Admin"
  544. * @param string $delim Delimiter character (defaults to comma)
  545. * @return string List of group name's comma-delimited
  546. */
  547. function group_names_list($delim=",") {
  548. if (!isset($this->group_info)) {
  549. $this->get_groups();
  550. }
  551. $gplist = array();
  552. if (isset($this->group_info)) {
  553. foreach ($this->group_info as $gid => $gdesc) {
  554. $gplist[] = $gdesc;
  555. }
  556. }
  557. return implode($delim, $gplist);
  558. } // group_names_list
  559. // ....................................................................
  560. /**
  561. * Get friendly name
  562. * Make a 'friendly' name from a full one. Good for "Dear... ,"
  563. * @return string Friendly name for the current user
  564. */
  565. function friendlyName() {
  566. if ($this->valid) {
  567. $splitname = explode(" ", $this->name);
  568. $mate = trim($splitname[0]);
  569. if ($mate == "") $mate = $this->name;
  570. return $mate;
  571. }
  572. else return "Invalid User";
  573. } // friendlyName
  574.  
  575.  
  576.  
  577. } // user class
  578. // ----------------------------------------------------------------------
  579.  
  580. /**
  581. * The Authorised User class
  582. * This derived class just allows us a different way of defining
  583. * a new user, when we know their authorisation code.
  584. * @package core
  585. */
  586. class authorised_user extends user {
  587. // .....................................................................
  588. /**
  589. * Constructor
  590. * Create a new authorised user object.
  591. * @param string $auth_code Authorisation code of the user
  592. */
  593. function authorised_user($auth_code="") {
  594. $this->user();
  595. if ($auth_code != "") {
  596. $this->get_user_by_auth_code($auth_code);
  597. }
  598. } // authorised_user
  599.  
  600.  
  601.  
  602. } // authorised_user class
  603. // ----------------------------------------------------------------------
  604.  
  605. /**
  606. * The Permissions class. This generic class manages permissions for a
  607. * set of "agents" which are identified by a supplied "id". The permissions
  608. * are the standard Create, Read, Update, Delete or any combination by
  609. * ORing these values together.
  610. * @package core
  611. */
  612. // ACCESS MODES
  613. /** Permission to create items */
  614. ("PERM_CREATE", 0x01);
  615. /** Permission to read/view items */
  616. ("PERM_READ", 0x02);
  617. /** Permission to update/modify items */
  618. ("PERM_UPDATE", 0x04);
  619. /** Permission to delete items */
  620. ("PERM_DELETE", 0x08);
  621.  
  622. /** All permitted */
  623. ("PERM_ALL", 0x0f);
  624. /** Nothing permitted */
  625. ("PERM_NONE", 0x00);
  626.  
  627. // PERMISSION RETURN CODES
  628. /** Permission is given */
  629. ("PERM_ALLOWED", 1);
  630. /** Permission is refused */
  631. ("PERM_DISALLOWED", 2);
  632. /** Permission is undefined */
  633. ("PERM_UNDEFINED", 3);
  634.  
  635. /** The default agent ID */
  636. ("DEFAULT_AGENT", "__perm_default_agent__");
  637.  
  638. // ......................................................................
  639. /**
  640. * The permissions class. This class encpasulates a set of permissions
  641. * which can be managed and tested by the associated methods.
  642. * @package core
  643. */
  644. class permissions {
  645. /** Array of permisssions. This is an associative array with the
  646. key being the identifier of an agent which can be permitted or
  647. disallowed from accessing things, and the value being a
  648. permission code as defined above. */
  649. var $perms = array();
  650. // .....................................................................
  651. /**
  652. * Constructor
  653. * Create a new permissions object with an optional permissions set.
  654. * @param mixed $perms If provided, must be an array of permissions
  655. */
  656. function permissions($perms=false) {
  657. // Always include default perm..
  658. $this->permit(DEFAULT_AGENT, PERM_READ);
  659. if ( is_array($perms) ) {
  660. $this->perms = $perms;
  661. }
  662. } // permissions
  663. // .....................................................................
  664. /**
  665. * Assign the default permission. This is the permission which is applied
  666. * if the supplied agent is not recognised.
  667. * @param integer $perm The default permission to apply for unrecognised agents
  668. */
  669. function setdefault($perm) {
  670. $this->permit(DEFAULT_AGENT, $perm);
  671. } // setdefault
  672. // .....................................................................
  673. /**
  674. * Assign the given agent(s) the given access permission. The first paramter
  675. * is a (comma) delimited list of agent IDs to assign the permission to.
  676. * @param mixed $agentids Agents to assign the permission to (array or delimited string)
  677. * @param integer $perm The permission of combination of perms to assign
  678. * @param string $delim The delimiter string separating agent IDs (default comma)
  679. */
  680. function permit($agentids, $perm, $delim=",") {
  681. if (is_array($agentids)) $agents = $agentids;
  682. else $agents = explode($delim, $agentids);
  683. foreach ($agents as $agentid) {
  684. $this->perms[$agentid] = $perm;
  685. }
  686. } // permit
  687. // .....................................................................
  688. /**
  689. * Un-assign the given agent(s) the given access permission. The first paramter
  690. * is a (comma) delimited list of agent IDs to unassign the permission from.
  691. * @param mixed $agentids Agents to unassign the permission from (array or delimited string)
  692. * @param integer $perm The permission of combination of perms to unassign
  693. * @param string $delim The delimiter string separating agent IDs (default comma)
  694. */
  695. function unpermit($agentids, $perm, $delim=",") {
  696. if (is_array($agentids)) $agents = $agentids;
  697. else $agents = explode($delim, $agentids);
  698. foreach ($agents as $agentid) {
  699. if (isset($this->perms[$agentid])) {
  700. $unperm = $this->perms[$agentid] & $perm;
  701. $newperm = $this->perms[$agentid] ^ $unperm;
  702. $this->perms[$agentid] = $newperm;
  703. }
  704. }
  705. } // unpermit
  706. // .....................................................................
  707. /**
  708. * Low-level method for returning the permission for the given agent and
  709. * perm. We return one of three states: agent is allowed, agent is disallowed,
  710. * or agent permission status is undefined/unknown. The latter would occur
  711. * if the agent ID is unrecognised in this class (ie. not in the $perms array).
  712. * @param integer $agentid The unique agent ID to return the permission of
  713. * @param integer $perm The permission of combination of perms to assign
  714. * @return integer The permission status: allowed, disallowed or undefined
  715. */
  716. function permission($agentid, $perm) {
  717. if ( isset($this->perms[$agentid]) ) {
  718. return ($perm & $this->perms[$agentid] ? PERM_ALLOWED : PERM_DISALLOWED );
  719. }
  720. else {
  721. return PERM_UNDEFINED;
  722. }
  723. } // permission
  724. // .....................................................................
  725. /**
  726. * This is the main method for querying permission access rights for a given
  727. * agent. Returns a boolean value, true if the agent is permitted to access
  728. * in the given way, else false. If the agent ID is unrecognised, then the
  729. * method uses the 'default agent' permissions.
  730. * @param integer $agentid The agent to query the access permission of
  731. * @param integer $perm The access permission
  732. * @return boolean True if the agent is permitted access in given ways
  733. */
  734. function ispermitted($agentid, $perm) {
  735. $permission = $this->permission($agentid, $perm);
  736. if ($permission == PERM_UNDEFINED) {
  737. $permission = $this->permission(DEFAULT_AGENT, $perm);
  738. }
  739. return ($permission == PERM_ALLOWED);
  740. } // ispermitted
  741. // .....................................................................
  742. /**
  743. * This is a variant permitted query method, which takes a comma-delimited
  744. * list of agent IDs, and returns true if ANY one or more of these has the
  745. * required permissions. This facilitates passing of a group membership
  746. * list for a given user, for example.
  747. * @param mixed $agentids Agents to query the permission of (array or delimited string)
  748. * @param integer $perm The access permission
  749. * @param string $delim Delimiter character used (default is a comma)
  750. * @return boolean True if the agent is permitted access in given ways
  751. */
  752. function anypermitted($agentids, $perm, $delim=",") {
  753. $permitted = false;
  754. if (is_array($agentids)) $agents = $agentids;
  755. else $agents = explode($delim, $agentids);
  756. foreach ($agents as $agentid) {
  757. if ($this->ispermitted($agentid, $perm)) {
  758. $permitted = true;
  759. break;
  760. }
  761. }
  762. return $permitted;
  763. } // anypermitted
  764. // .....................................................................
  765. /**
  766. * Decode permission as a string of the form 'crud'
  767. * @param integer $perm The access permission to decode
  768. * @access private
  769. */
  770. function decode($perm) {
  771. $s = "";
  772. $s .= ($perm & PERM_CREATE ? "c" : "-");
  773. $s .= ($perm & PERM_READ ? "r" : "-");
  774. $s .= ($perm & PERM_UPDATE ? "u" : "-");
  775. $s .= ($perm & PERM_DELETE ? "d" : "-");
  776. return $s;
  777. } // decode
  778. // .....................................................................
  779. /** Dump these permissions as text. Mainly a debugging aid.
  780. * @access private
  781. */
  782. function dump() {
  783. $s = "";
  784. reset($this->perms);
  785. while (list($agentid, $perm) = each($this->perms)) {
  786. if ($agentid != DEFAULT_AGENT) {
  787. $s .= $agentid . "&nbsp;" . "(" . $this->decode($perm) . ") ";
  788. }
  789. }
  790. if ($s == "") $s = "no perms";
  791. return $s;
  792. } // dump
  793.  
  794.  
  795.  
  796. } // permissions class
  797. // ----------------------------------------------------------------------
  798.  
  799. ?>

Documentation generated by phpDocumentor 1.3.0RC3