X-Git-Url: http://git.polytechnique.org/?a=blobdiff_plain;f=classes%2Fuserfilter.php;h=9804acb23df43698142b7a6a3b72b66d585eeeb3;hb=036d163736bfd72e7d2b4dae5cfbc30e9d2959a8;hp=738c702a8c05ba850b359b2515fe0526f1f67e16;hpb=ceb512d24fe826623ac5ccd38f55a01e2bc3a3d7;p=platal.git

diff --git a/classes/userfilter.php b/classes/userfilter.php
index 738c702..9804acb 100644
--- a/classes/userfilter.php
+++ b/classes/userfilter.php
@@ -25,6 +25,15 @@
  ******************/
 
 // {{{ interface UserFilterCondition
+/** This interface describe objects which filter users based
+ *      on various parameters.
+ * The parameters of the filter must be given to the constructor.
+ * The buildCondition function is called by UserFilter when
+ *     actually building the query. That function must call
+ *     $uf->addWheteverFilter so that the UserFilter makes
+ *     adequate joins. It must return the 'WHERE' condition to use
+ *     with the filter.
+ */
 interface UserFilterCondition
 {
     const COND_TRUE  = 'TRUE';
@@ -190,10 +199,10 @@ class UFC_Profile implements UserFilterCondition
 // }}}
 
 // {{{ class UFC_Promo
-/** Filters users based on promo
+/** Filters users based on promotion
  * @param $comparison Comparison operator (>, =, ...)
  * @param $grade Formation on which to restrict, UserFilter::DISPLAY for "any formation"
- * @param $promo Promo on which the filter is based
+ * @param $promo Promotion on which the filter is based
  */
 class UFC_Promo implements UserFilterCondition
 {
@@ -228,9 +237,9 @@ class UFC_Promo implements UserFilterCondition
 
 // {{{ class UFC_Name
 /** Filters users based on name
- * @param $type Type of name field on which filtering is done (firstname, lastname, ...)
+ * @param $type Type of name field on which filtering is done (firstname, lastname...)
  * @param $text Text on which to filter
- * @param $mode flag indicating search type (prefix, suffix, with particule, ...)
+ * @param $mode Flag indicating search type (prefix, suffix, with particule...)
  */
 class UFC_Name implements UserFilterCondition
 {
@@ -418,24 +427,24 @@ class UFC_Sex implements UserFilterCondition
 
 // {{{ class UFC_Group
 /** Filters users based on group membership
- * @param $group Group whose member we are selecting
- * @param $admin Whether to restrict selection to admins of that group
+ * @param $group Group whose members we are selecting
+ * @param $anim Whether to restrict selection to animators of that group
  */
 class UFC_Group implements UserFilterCondition
 {
     private $group;
-    private $admin;
-    public function __construct($group, $admin = false)
+    private $anim;
+    public function __construct($group, $anim = false)
     {
         $this->group = $group;
-        $this->admin = $admin;
+        $this->anim = $anim;
     }
 
     public function buildCondition(UserFilter &$uf)
     {
         $sub = $uf->addGroupFilter($this->group);
         $where = 'gpm' . $sub . '.perms IS NOT NULL';
-        if ($this->admin) {
+        if ($this->anim) {
             $where .= ' AND gpm' . $sub . '.perms = \'admin\'';
         }
         return $where;
@@ -473,7 +482,7 @@ class UFC_Email implements UserFilterCondition
 // }}}
 
 // {{{ class UFC_EmailList
-/** Filters users base on an email list
+/** Filters users based on an email list
  * @param $emails List of emails whose owner must be selected
  */
 class UFC_EmailList implements UserFilterCondition
@@ -521,44 +530,127 @@ class UFC_EmailList implements UserFilterCondition
 
 // {{{ class UFC_Address
 /** Filters users based on their address
- * @param $field Field of the address used for filtering (city, street, ...)
- * @param $text Text for filter
- * @param $mode Mode for search (PREFIX, SUFFIX, ...)
+ * @param $text Text for filter in fulltext search
+ * @param $textSearchMode Mode for search (PREFIX, SUFFIX, ...)
+ * @param $type Filter on address type
+ * @param $flags Filter on address flags
+ * @param $countryId Filter on address countryId
+ * @param $administrativeAreaId Filter on address administrativeAreaId
+ * @param $subAdministrativeAreaId Filter on address subAdministrativeAreaId
+ * @param $localityId Filter on address localityId
+ * @param $postalCode Filter on address postalCode
  */
 class UFC_Address implements UserFilterCondition
 {
-    const PREFIX    = 1;
-    const SUFFIX    = 2;
-    const CONTAINS  = 3;
+    /** Flags for text search
+     */
+    const PREFIX    = 0x0001;
+    const SUFFIX    = 0x0002;
+    const CONTAINS  = 0x0003;
 
-    private $field;
-    private $text;
-    private $mode;
+    /** Valid address type ('hq' is reserved for company addresses)
+     */
+    const TYPE_HOME = 'home';
+    const TYPE_PRO  = 'job';
 
-    public function __construct($field, $text, $mode)
-    {
-        $this->field = $field;
-        $this->text  = $text;
-        $this->mode  = $mode;
+    /** Flags for addresses
+     */
+    const FLAG_CURRENT = 0x0001;
+    const FLAG_TEMP    = 0x0002;
+    const FLAG_SECOND  = 0x0004;
+    const FLAG_MAIL    = 0x0008;
+    const FLAG_CEDEX   = 0x0010;
+
+    // Binary OR of those flags
+    const FLAG_ANY     = 0x001F;
+
+    /** Text of these flags
+     */
+    private static $flagtexts = array(
+        self::FLAG_CURRENT => 'current',
+        self::FLAG_TEMP    => 'temporary',
+        self::FLAG_SECOND  => 'secondary',
+        self::FLAG_MAIL    => 'mail',
+        self::FLAG_CEDEX   => 'cedex',
+    );
+
+    /** Data of the filter
+     */
+    private $text;
+    private $type;
+    private $flags;
+    private $countryId;
+    private $administrativeAreaId;
+    private $subAdministrativeAreaId;
+    private $localityId;
+    private $postalCode;
+
+    private $textSearchMode;
+
+    public function __construct($text = null, $textSearchMode = self::CONTAINS,
+        $type = null, $flags = self::FLAG_ANY, $countryId = null, $administrativeAreaId = null,
+        $subAdministrativeAreaId = null, $localityId = null, $postalCode = null)
+    {
+        $this->text                      = $text;
+        $this->textSearchMode            = $textSearchMode;
+        $this->type                      = $type;
+        $this->flags                     = $flags;
+        $this->countryId                 = $countryId;
+        $this->administrativeAreaId      = $administrativeAreaId;
+        $this->subAdministrativeAreaId   = $subAdministrativeAreaId;
+        $this->localityId                = $localityId;
+        $this->postalCode                = $postalCode;
     }
 
     public function buildCondition(UserFilter &$uf)
     {
-        $left = 'pa.' . $field;
-        $op   = ' LIKE ';
-        if (($this->mode & self::CONTAINS) == 0) {
-            $right = XDB::format('{?}', $this->text);
-            $op = ' = ';
-        } else if (($this->mode & self::CONTAINS) == self::PREFIX) {
-            $right = XDB::format('CONCAT({?}, \'%\')', $this->text);
-        } else if (($this->mode & self::CONTAINS) == self::SUFFIX) {
-            $right = XDB::format('CONCAT(\'%\', {?})', $this->text);
-        } else {
-            $right = XDB::format('CONCAT(\'%\', {?}, \'%\')', $this->text);
+        $sub = $uf->addAddressFilter();
+        $conds = array();
+        if ($this->text != null) {
+            $left = $sub . '.text ';
+            $op = ' LIKE ';
+            if (($this->textSearchMode & self::CONTAINS) == 0) {
+                $right = XDB::format('{?}', $this->text);
+                $op = ' = ';
+            } else if (($this->mode & self::CONTAINS) == self::PREFIX) {
+                $right = XDB::format('CONCAT({?}, \'%\')', $this->text);
+            } else if (($this->mode & self::CONTAINS) == self::SUFFIX) {
+                $right = XDB::format('CONCAT(\'%\', {?})', $this->text);
+            } else {
+                $right = XDB::format('CONCAT(\'%\', {?}, \'%\')', $this->text);
+            }
+            $conds[] = $left . $op . $right;
         }
-        $cond = $left . $op . $right;
-        $uf->addAddressFilter();
-        return $cond;
+
+        if ($this->type != null) {
+            $conds[] = $sub . '.type = ' . XDB::format('{?}', $this->type);
+        }
+
+        if ($this->flags != self::FLAG_ANY) {
+            foreach(self::$flagtexts as $flag => $text) {
+                if ($flag & $this->flags) {
+                    $conds[] = 'FIND_IN_SET(' . XDB::format('{?}', $text) . ', ' . $sub . '.flags)';
+                }
+            }
+        }
+
+        if ($this->countryId != null) {
+            $conds[] = $sub . '.countryId = ' . XDB::format('{?}', $this->countryId);
+        }
+        if ($this->administrativeAreaId != null) {
+            $conds[] = $sub . '.administrativeAreaId = ' . XDB::format('{?}', $this->administrativeAreaId);
+        }
+        if ($this->subAdministrativeAreaId != null) {
+            $conds[] = $sub . '.subAdministrativeAreaId = ' . XDB::format('{?}', $this->subAdministrativeAreaId);
+        }
+        if ($this->localityId != null) {
+            $conds[] = $sub . '.localityId = ' . XDB::format('{?}', $this->localityId);
+        }
+        if ($this->postalCode != null) {
+            $conds[] = $sub . '.postalCode = ' . XDB::format('{?}', $this->postalCode);
+        }
+
+        return implode(' AND ', $conds);
     }
 }
 // }}}
@@ -570,8 +662,8 @@ class UFC_Address implements UserFilterCondition
  */
 class UFC_Corps implements UserFilterCondition
 {
-    const CURRENT=1;
-    const ORIGIN=2;
+    const CURRENT   = 1;
+    const ORIGIN    = 2;
 
     private $corps;
     private $type;
@@ -584,8 +676,8 @@ class UFC_Corps implements UserFilterCondition
 
     public function buildCondition(UserFilter &$uf)
     {
-        /** Tables shortcuts :
-         * pc for profile corps,
+        /** Tables shortcuts:
+         * pc for profile_corps,
          * pceo for profile_corps_enum - orginal
          * pcec for profile_corps_enum - current
          */
@@ -610,7 +702,7 @@ class UFC_Corps_Rank implements UserFilterCondition
 
     public function buildCondition(UserFilter &$uf)
     {
-        /** Tables shortcuts :
+        /** Tables shortcuts:
          * pcr for profile_corps_rank
          */
         $sub = $uf->addCorpsRankFilter();
@@ -625,7 +717,7 @@ class UFC_Corps_Rank implements UserFilterCondition
  * @param $type The field being searched (self::JOBID, self::JOBNAME or self::JOBACRONYM)
  * @param $value The searched value
  */
-class UFC_Job_Company extends UserFilterCondition
+class UFC_Job_Company implements UserFilterCondition
 {
     const JOBID = 'id';
     const JOBNAME = 'name';
@@ -644,7 +736,7 @@ class UFC_Job_Company extends UserFilterCondition
     private function assertType($type)
     {
         if ($type != self::JOBID && $type != self::JOBNAME && $type != self::JOBACRONYM) {
-            Platal::page()->killError("Type de recherche non valide");
+            Platal::page()->killError("Type de recherche non valide.");
         }
     }
 
@@ -663,7 +755,7 @@ class UFC_Job_Company extends UserFilterCondition
  * @param $subsector The subsector
  * @param $subsubsector The subsubsector
  */
-class UFC_Job_Sectorization extends UserFilterCondition
+class UFC_Job_Sectorization implements UserFilterCondition
 {
 
     private $sector;
@@ -703,7 +795,7 @@ class UFC_Job_Sectorization extends UserFilterCondition
  * @param $description The text being searched for
  * @param $fields The fields to search for (user-defined, ((sub|)sub|)sector)
  */
-class UFC_Job_Description extends UserFilterCondition
+class UFC_Job_Description implements UserFilterCondition
 {
 
     /** Meta-filters
@@ -752,7 +844,7 @@ class UFC_Job_Description extends UserFilterCondition
  * @param $type Type of network (-1 for any)
  * @param $value Value to search
  */
-class UFC_Networking extends UserFilterCondition
+class UFC_Networking implements UserFilterCondition
 {
     private $type;
     private $value;
@@ -782,7 +874,7 @@ class UFC_Networking extends UserFilterCondition
  * @param $phone_type Type of phone (fixed/mobile/fax)
  * @param $number Phone number
  */
-class UFC_Phone extends UserFilterCondition
+class UFC_Phone implements UserFilterCondition
 {
     const NUM_PRO   = 'pro';
     const NUM_USER  = 'user';
@@ -827,7 +919,7 @@ class UFC_Phone extends UserFilterCondition
  * @param $medal ID of the medal
  * @param $grade Grade of the medal (null for 'any')
  */
-class UFC_Medal extends UserFilterCondition
+class UFC_Medal implements UserFilterCondition
 {
     private $medal;
     private $grade;
@@ -851,8 +943,79 @@ class UFC_Medal extends UserFilterCondition
 }
 // }}}
 
+// {{{ class UFC_Mentor_Expertise
+/** Filters users by mentoring expertise
+ * @param $expertise Domain of expertise
+ */
+class UFC_Mentor_Expertise implements UserFilterCondition
+{
+    private $expertise;
+
+    public function __construct($expertise)
+    {
+        $this->expertise = $expertise;
+    }
+
+    public function buildCondition(UserFilter &$uf)
+    {
+        $sub = $uf->addMentorFilter(UserFilter::MENTOR_EXPERTISE);
+        return $sub . '.expertise LIKE ' . XDB::format('CONCAT(\'%\', {?}, \'%\'', $this->expertise);
+    }
+}
+// }}}
+
+// {{{ class UFC_Mentor_Country
+/** Filters users by mentoring country
+ * @param $country Two-letters code of country being searched
+ */
+class UFC_Mentor_Country implements UserFilterCondition
+{
+    private $country;
+
+    public function __construct($country)
+    {
+        $this->country = $country;
+    }
+
+    public function buildCondition(UserFilter &$uf)
+    {
+        $sub = $uf->addMentorFilter(UserFilter::MENTOR_COUNTRY);
+        return $sub . '.country = ' . XDB::format('{?}', $this->country);
+    }
+}
+// }}}
+
+// {{{ class UFC_Mentor_Sectorization
+/** Filters users based on mentoring (sub|)sector
+ * @param $sector ID of sector
+ * @param $subsector Subsector (null for any)
+ */
+class UFC_Mentor_Sectorization implements UserFilterCondition
+{
+    private $sector;
+    private $subsector;
+
+    public function __construct($sector, $subsector = null)
+    {
+        $this->sector = $sector;
+        $this->subsubsector = $subsector;
+    }
+
+    public function buildCondition(UserFilter &$uf)
+    {
+        $sub = $uf->addMentorFilter(UserFilter::MENTOR_SECTOR);
+        $conds = array();
+        $conds[] = $sub . '.sectorid = ' . XDB::format('{?}', $this->sector);
+        if ($this->subsector != null) {
+            $conds[] = $sub . '.subsectorid = ' . XDB::format('{?}', $this->subsector);
+        }
+        return implode(' AND ', $conds);
+    }
+}
+// }}}
+
 // {{{ class UFC_UserRelated
-/** Filters users based on a relation toward on user
+/** Filters users based on a relation toward a user
  * @param $user User to which searched users are related
  */
 abstract class UFC_UserRelated implements UserFilterCondition
@@ -866,7 +1029,7 @@ abstract class UFC_UserRelated implements UserFilterCondition
 // }}}
 
 // {{{ class UFC_Contact
-/** Filters users who belongs to selected user's contacts
+/** Filters users who belong to selected user's contacts
  */
 class UFC_Contact extends UFC_UserRelated
 {
@@ -947,6 +1110,11 @@ class UFC_WatchContact extends UFC_Contact
  ******************/
 
 // {{{ class UserFilterOrder
+/** Base class for ordering results of a query.
+ * Parameters for the ordering must be given to the constructor ($desc for a
+ *     descending order).
+ * The getSortTokens function is used to get actual ordering part of the query.
+ */
 abstract class UserFilterOrder
 {
     protected $desc = false;
@@ -969,13 +1137,17 @@ abstract class UserFilterOrder
         return $sel;
     }
 
+    /** This function must return the tokens to use for ordering
+     * @param &$uf The UserFilter whose results must be ordered
+     * @return The name of the field to use for ordering results
+     */
     abstract protected function getSortTokens(UserFilter &$uf);
 }
 // }}}
 
 // {{{ class UFO_Promo
-/** Orders users by promo
- * @param $grade Formation whose promo users should be sorted by (restricts results to users of that formation)
+/** Orders users by promotion
+ * @param $grade Formation whose promotion users should be sorted by (restricts results to users of that formation)
  * @param $desc Whether sort is descending
  */
 class UFO_Promo extends UserFilterOrder
@@ -1003,8 +1175,8 @@ class UFO_Promo extends UserFilterOrder
 
 // {{{ class UFO_Name
 /** Sorts users by name
- * @param $type Type of name on which to sort (firstname, ...)
- * @param $variant Variant of that name to user (marital, ordinary, ...)
+ * @param $type Type of name on which to sort (firstname...)
+ * @param $variant Variant of that name to use (marital, ordinary...)
  * @param $particle Set to true if particles should be included in the sorting order
  * @param $desc If sort order should be descending
  */
@@ -1095,6 +1267,46 @@ class UFO_Death extends UserFilterOrder
  ***********************************/
 
 // {{{ class UserFilter
+/** This class provides a convenient and centralized way of filtering users.
+ *
+ * Usage:
+ * $uf = new UserFilter(new UFC_Blah($x, $y), new UFO_Coin($z, $t));
+ *
+ * Resulting UserFilter can be used to:
+ * - get a list of User objects matching the filter
+ * - get a list of UIDs matching the filter
+ * - get the number of users matching the filter
+ * - check whether a given User matches the filter
+ * - filter a list of User objects depending on whether they match the filter
+ *
+ * Usage for UFC and UFO objects:
+ * A UserFilter will call all private functions named XXXJoins.
+ * These functions must return an array containing the list of join
+ * required by the various UFC and UFO associated to the UserFilter.
+ * Entries in those returned array are of the following form:
+ *   'join_tablealias' => array('join_type', 'joined_table', 'join_criter')
+ * which will be translated into :
+ *   join_type JOIN joined_table AS join_tablealias ON (join_criter)
+ * in the final query.
+ *
+ * In the join_criter text, $ME is replaced with 'join_tablealias', $PID with
+ * profile.pid, and $UID with auth_user_md5.user_id.
+ *
+ * For each kind of "JOIN" needed, a function named addXXXFilter() should be defined;
+ * its parameter will be used to set various private vars of the UserFilter describing
+ * the required joins ; such a function shall return the "join_tablealias" to use
+ * when referring to the joined table.
+ *
+ * For example, if data from profile_job must be available to filter results,
+ * the UFC object will call $uf-addJobFilter(), which will set the 'with_pj' var and 
+ * return 'pj', the short name to use when referring to profile_job; when building
+ * the query, calling the jobJoins function will return an array containing a single
+ * row:
+ *   'pj' => array('left', 'profile_job', '$ME.pid = $UID');
+ *
+ * The 'register_optional' function can be used to generate unique table aliases when
+ * the same table has to be joined several times with different aliases.
+ */
 class UserFilter
 {
     static private $joinMethods = array();
@@ -1310,6 +1522,11 @@ class UserFilter
     }
 
 
+    /** Stores a new (and unique) table alias in the &$table table
+     * @param   &$table Array in which the table alias must be stored
+     * @param   $val    Value which will then be used to build the join
+     * @return          Name of the newly created alias
+     */
     private $option = 0;
     private function register_optional(array &$table, $val)
     {
@@ -1578,17 +1795,18 @@ class UserFilter
 
     /** ADDRESSES
      */
-    private $pa = false;
+    private $with_pa = false;
     public function addAddressFilter()
     {
-        $this->pa = true;
+        $this->with_pa = true;
+        return 'pa';
     }
 
     private function addressJoins()
     {
         $joins = array();
-        if ($this->pa) {
-            $joins['pa'] = array('left', 'profile_address', '$ME.PID = $PID');
+        if ($this->with_pa) {
+            $joins['pa'] = array('left', 'profile_address', '$ME.pid = $PID');
         }
         return $joins;
     }
@@ -1735,18 +1953,18 @@ class UserFilter
     /** PHONE
      */
 
-    private $with_phone = false;
+    private $with_ptel = false;
 
     public function addPhoneFilter()
     {
-        $this->with_phone = true;
+        $this->with_ptel = true;
         return 'ptel';
     }
 
     private function phoneJoins()
     {
         $joins = array();
-        if ($this->with_phone) {
+        if ($this->with_ptel) {
             $joins['ptel'] = array('left', 'profile_phone', '$ME.uid = $UID');
         }
         return $joins;
@@ -1755,22 +1973,56 @@ class UserFilter
     /** MEDALS
      */
 
-    private $with_medals = false;
+    private $with_pmed = false;
     public function addMedalFilter()
     {
-        $this->with_medals = true;
+        $this->with_pmed = true;
         return 'pmed';
     }
 
     private function medalJoins()
     {
         $joins = array();
-        if ($this->with_medals) {
+        if ($this->with_pmed) {
             $joins['pmed'] = array('left', 'profile_medals_sub', '$ME.uid = $UID');
         }
         return $joins;
     }
 
+    /** MENTORING
+     */
+
+    private $pms = array();
+    const MENTOR_EXPERTISE  = 1;
+    const MENTOR_COUNTRY    = 2;
+    const MENTOR_SECTOR     = 3;
+
+    public function addMentorFilter($type)
+    {
+        switch($type) {
+        case MENTOR_EXPERTISE:
+            $pms['pme'] = 'profile_mentor';
+            return 'pme';
+        case MENTOR_COUNTRY:
+            $pms['pmc'] = 'profile_mentor_country';
+            return 'pmc';
+        case MENTOR_SECTOR:
+            $pms['pms'] =  'profile_mentor_sector';
+            return 'pms';
+        default:
+            Platal::page()->killError("Undefined mentor filter.");
+        }
+    }
+
+    private function mentorJoins()
+    {
+        $joins = array();
+        foreach ($this->pms as $sub => $tab) {
+            $joins[$sub] = array('left', $tab, '$ME.uid = $UID');
+        }
+        return $joins;
+    }
+
     /** CONTACTS
      */
     private $cts = array();