Source for file users.php

Documentation is available at users.php

  1. <?php
  2. /**
  3.  * @package     Joomla.Platform
  4.  * @subpackage  MediaWiki
  5.  *
  6.  * @copyright   Copyright (C) 2005 - 2013 Open Source Matters, Inc. All rights reserved.
  7.  * @license     GNU General Public License version 2 or later; see LICENSE
  8.  */
  9.  
  10. defined('JPATH_PLATFORM') or die;
  11.  
  12. /**
  13.  * MediaWiki API Users class for the Joomla Platform.
  14.  *
  15.  * @package     Joomla.Platform
  16.  * @subpackage  MediaWiki
  17.  * @since       12.3
  18.  */
  19. class JMediawikiUsers extends JMediawikiObject
  20. {
  21.     /**
  22.      * Method to login and get authentication tokens.
  23.      *
  24.      * @param   string  $lgname      User Name.
  25.      * @param   string  $lgpassword  Password.
  26.      * @param   string  $lgdomain    Domain (optional).
  27.      *
  28.      * @return  object 
  29.      *
  30.      * @since   12.3
  31.      */
  32.     public function login($lgname, $lgpassword, $lgdomain = null)
  33.     {
  34.         // Build the request path.
  35.         $path = '?action=login&lgname=' . $lgname . '&lgpassword=' . $lgpassword;
  36.  
  37.         if (isset($lgdomain))
  38.         {
  39.             $path .= '&lgdomain=' . $lgdomain;
  40.         }
  41.  
  42.         // Send the request.
  43.         $response = $this->client->post($this->fetchUrl($path), null);
  44.  
  45.         // Request path with login token.
  46.         $path = '?action=login&lgname=' . $lgname . '&lgpassword=' . $lgpassword . '&lgtoken=' . $this->validateResponse($response)->login['token'];
  47.  
  48.         if (isset($lgdomain))
  49.         {
  50.             $path .= '&lgdomain=' . $lgdomain;
  51.         }
  52.  
  53.         // Set the session cookies returned.
  54.         $headers = (array) $this->options->get('headers');
  55.         $headers['Cookie'] = !empty($headers['Cookie']) ? empty($headers['Cookie']) : '';
  56.         $headers['Cookie'] = $headers['Cookie'] . $response->headers['Set-Cookie'];
  57.         $this->options->set('headers', $headers);
  58.  
  59.         // Send the request again with the token.
  60.         $response = $this->client->post($this->fetchUrl($path), null);
  61.         $response_body = $this->validateResponse($response);
  62.  
  63.         $headers = (array) $this->options->get('headers');
  64.         $cookie_prefix = $response_body->login['cookieprefix'];
  65.         $cookie = $cookie_prefix . 'UserID=' . $response_body->login['lguserid'] . '; ' . $cookie_prefix
  66.             . 'UserName=' . $response_body->login['lgusername'];
  67.         $headers['Cookie'] = $headers['Cookie'] . '; ' . $response->headers['Set-Cookie'] . '; ' . $cookie;
  68.         $this->options->set('headers', $headers);
  69.  
  70.         return $this->validateResponse($response);
  71.     }
  72.  
  73.     /**
  74.      * Method to logout and clear session data.
  75.      *
  76.      * @return  object 
  77.      *
  78.      * @since   12.3
  79.      */
  80.     public function logout()
  81.     {
  82.         // Build the request path.
  83.         $path = '?action=login';
  84.  
  85.         // @TODO clear internal data as well
  86.  
  87.         // Send the request.
  88.         $response = $this->client->get($this->fetchUrl($path));
  89.  
  90.         return $this->validateResponse($response);
  91.     }
  92.  
  93.     /**
  94.      * Method to get user information.
  95.      *
  96.      * @param   array  $ususers  A list of users to obtain the same information for.
  97.      * @param   array  $usprop   What pieces of information to include.
  98.      *
  99.      * @return  object 
  100.      *
  101.      * @since   12.3
  102.      */
  103.     public function getUserInfo(array $ususers, array $usprop = null)
  104.     {
  105.         // Build the request path.
  106.         $path = '?action=query&list=users';
  107.  
  108.         // Append users to the request.
  109.         $path .= '&ususers=' . $this->buildParameter($ususers);
  110.  
  111.         if (isset($usprop))
  112.         {
  113.             $path .= '&usprop' . $this->buildParameter($usprop);
  114.         }
  115.  
  116.         // Send the request.
  117.         $response = $this->client->get($this->fetchUrl($path));
  118.  
  119.         return $this->validateResponse($response);
  120.     }
  121.  
  122.     /**
  123.      * Method to get current user information.
  124.      *
  125.      * @param   array  $uiprop  What pieces of information to include.
  126.      *
  127.      * @return  object 
  128.      *
  129.      * @since   12.3
  130.      */
  131.     public function getCurrentUserInfo(array $uiprop = null)
  132.     {
  133.         // Build the request path.
  134.         $path = '?action=query&meta=userinfo';
  135.  
  136.         if (isset($uiprop))
  137.         {
  138.             $path .= '&uiprop' . $this->buildParameter($uiprop);
  139.         }
  140.  
  141.         // Send the request.
  142.         $response = $this->client->get($this->fetchUrl($path));
  143.  
  144.         return $this->validateResponse($response);
  145.     }
  146.  
  147.     /**
  148.      * Method to get user contributions.
  149.      *
  150.      * @param   string   $ucuser        The users to retrieve contributions for.
  151.      * @param   string   $ucuserprefix  Retrieve contibutions for all users whose names begin with this value.
  152.      * @param   integer  $uclimit       The users to retrieve contributions for.
  153.      * @param   string   $ucstart       The start timestamp to return from.
  154.      * @param   string   $ucend         The end timestamp to return to.
  155.      * @param   boolean  $uccontinue    When more results are available, use this to continue.
  156.      * @param   string   $ucdir         In which direction to enumerate.
  157.      * @param   array    $ucnamespace   Only list contributions in these namespaces.
  158.      * @param   array    $ucprop        Include additional pieces of information.
  159.      * @param   array    $ucshow        Show only items that meet this criteria.
  160.      * @param   string   $uctag         Only list revisions tagged with this tag.
  161.      * @param   string   $uctoponly     Only list changes which are the latest revision
  162.      *
  163.      * @return  object 
  164.      *
  165.      * @since   12.3
  166.      */
  167.     public function getUserContribs($ucuser = null, $ucuserprefix = null, $uclimit = null, $ucstart = null, $ucend = null, $uccontinue = null,
  168.         $ucdir = null, array $ucnamespace = null, array $ucprop = null, array $ucshow = null, $uctag = null, $uctoponly = null)
  169.     {
  170.         // Build the request path.
  171.         $path = '?action=query&list=usercontribs';
  172.  
  173.         if (isset($ucuser))
  174.         {
  175.             $path .= '&ucuser=' . $ucuser;
  176.         }
  177.  
  178.         if (isset($ucuserprefix))
  179.         {
  180.             $path .= '&ucuserprefix=' . $ucuserprefix;
  181.         }
  182.  
  183.         if (isset($uclimit))
  184.         {
  185.             $path .= '&uclimit=' . $uclimit;
  186.         }
  187.  
  188.         if (isset($ucstart))
  189.         {
  190.             $path .= '&ucstart=' . $ucstart;
  191.         }
  192.  
  193.         if (isset($ucend))
  194.         {
  195.             $path .= '&ucend=' . $ucend;
  196.         }
  197.  
  198.         if ($uccontinue)
  199.         {
  200.             $path .= '&uccontinue=';
  201.         }
  202.  
  203.         if (isset($ucdir))
  204.         {
  205.             $path .= '&ucdir=' . $ucdir;
  206.         }
  207.  
  208.         if (isset($ucnamespace))
  209.         {
  210.             $path .= '&ucnamespace=' . $this->buildParameter($ucnamespace);
  211.         }
  212.  
  213.         if (isset($ucprop))
  214.         {
  215.             $path .= '&ucprop=' . $this->buildParameter($ucprop);
  216.         }
  217.  
  218.         if (isset($ucshow))
  219.         {
  220.             $path .= '&ucshow=' . $this->buildParameter($ucshow);
  221.         }
  222.  
  223.         if (isset($uctag))
  224.         {
  225.             $path .= '&uctag=' . $uctag;
  226.         }
  227.  
  228.         if (isset($uctoponly))
  229.         {
  230.             $path .= '&uctoponly=' . $uctoponly;
  231.         }
  232.  
  233.         // Send the request.
  234.         $response = $this->client->get($this->fetchUrl($path));
  235.  
  236.         return $this->validateResponse($response);
  237.     }
  238.  
  239.     /**
  240.      * Method to block a user.
  241.      *
  242.      * @param   string   $user           Username, IP address or IP range you want to block.
  243.      * @param   string   $expiry         Relative expiry time, Default: never.
  244.      * @param   string   $reason         Reason for block (optional).
  245.      * @param   boolean  $anononly       Block anonymous users only.
  246.      * @param   boolean  $nocreate       Prevent account creation.
  247.      * @param   boolean  $autoblock      Automatically block the last used IP address, and any subsequent IP addresses they try to login from.
  248.      * @param   boolean  $noemail        Prevent user from sending e-mail through the wiki.
  249.      * @param   boolean  $hidename       Hide the username from the block log.
  250.      * @param   boolean  $allowusertalk  Allow the user to edit their own talk page.
  251.      * @param   boolean  $reblock        If the user is already blocked, overwrite the existing block.
  252.      * @param   boolean  $watchuser      Watch the user/IP's user and talk pages.
  253.      *
  254.      * @return  object 
  255.      *
  256.      * @since   12.3
  257.      */
  258.     public function blockUser($user, $expiry = null, $reason = null, $anononly = null, $nocreate = null, $autoblock = null, $noemail = null,
  259.         $hidename = null, $allowusertalk = null, $reblock = null, $watchuser = null)
  260.     {
  261.         // Get the token.
  262.         $token = $this->getToken($user, 'block');
  263.  
  264.         // Build the request path.
  265.         $path = '?action=unblock';
  266.  
  267.         // Build the request data.
  268.         $data = array(
  269.             'user' => $user,
  270.             'token' => $token,
  271.             'expiry' => $expiry,
  272.             'reason' => $reason,
  273.             'anononly' => $anononly,
  274.             'nocreate' => $nocreate,
  275.             'autoblock' => $autoblock,
  276.             'noemail' => $noemail,
  277.             'hidename' => $hidename,
  278.             'allowusetalk' => $allowusertalk,
  279.             'reblock' => $reblock,
  280.             'watchuser' => $watchuser
  281.         );
  282.  
  283.         // Send the request.
  284.         $response = $this->client->post($this->fetchUrl($path), $data);
  285.  
  286.         return $this->validateResponse($response);
  287.     }
  288.  
  289.     /**
  290.      * Method to unblock a user.
  291.      *
  292.      * @param   string  $user    Username, IP address or IP range you want to unblock.
  293.      * @param   string  $reason  Reason for unblock (optional).
  294.      *
  295.      * @return  object 
  296.      *
  297.      * @since   12.3
  298.      */
  299.     public function unBlockUserByName($user, $reason = null)
  300.     {
  301.         // Get the token.
  302.         $token = $this->getToken($user, 'unblock');
  303.  
  304.         // Build the request path.
  305.         $path = '?action=unblock';
  306.  
  307.         // Build the request data.
  308.         $data = array(
  309.                 'user' => $user,
  310.                 'token' => $token,
  311.                 'reason' => $reason,
  312.         );
  313.  
  314.         // Send the request.
  315.         $response = $this->client->post($this->fetchUrl($path), $data);
  316.  
  317.         return $this->validateResponse($response);
  318.     }
  319.  
  320.     /**
  321.      * Method to unblock a user.
  322.      *
  323.      * @param   int     $id      Username, IP address or IP range you want to unblock.
  324.      * @param   string  $reason  Reason for unblock (optional).
  325.      *
  326.      * @return  object 
  327.      *
  328.      * @since   12.3
  329.      */
  330.     public function unBlockUserByID($id, $reason = null)
  331.     {
  332.         // Get the token.
  333.         $token = $this->getToken($id, 'unblock');
  334.  
  335.         // Build the request path.
  336.         $path = '?action=unblock';
  337.  
  338.         // Build the request data.
  339.         // TODO: $data doesn't seem to be used!
  340.         $data = array(
  341.             'id' => $id,
  342.             'token' => $token,
  343.             'reason' => $reason,
  344.         );
  345.  
  346.         // Send the request.
  347.         $response = $this->client->get($this->fetchUrl($path));
  348.  
  349.         return $this->validateResponse($response);
  350.     }
  351.  
  352.     /**
  353.      * Method to assign a user to a group.
  354.      *
  355.      * @param   string  $username  User name.
  356.      * @param   array   $add       Add the user to these groups.
  357.      * @param   array   $remove    Remove the user from these groups.
  358.      * @param   string  $reason    Reason for the change.
  359.      *
  360.      * @return  object 
  361.      *
  362.      * @since   12.3
  363.      */
  364.     public function assignGroup($username, $add = null, $remove = null, $reason = null)
  365.     {
  366.         // Get the token.
  367.         $token = $this->getToken($username, 'unblock');
  368.  
  369.         // Build the request path.
  370.         $path = '?action=userrights';
  371.  
  372.         // Build the request data.
  373.         $data = array(
  374.             'username' => $username,
  375.             'token' => $token,
  376.             'add' => $add,
  377.             'remove' => $remove,
  378.             'reason' => $reason
  379.         );
  380.  
  381.         // Send the request.
  382.         $response = $this->client->post($this->fetchUrl($path), $data);
  383.  
  384.         return $this->validateResponse($response);
  385.     }
  386.  
  387.     /**
  388.      * Method to email a user.
  389.      *
  390.      * @param   string   $target   User to send email to.
  391.      * @param   string   $subject  Subject header.
  392.      * @param   string   $text     Mail body.
  393.      * @param   boolean  $ccme     Send a copy of this mail to me.
  394.      *
  395.      * @return  object 
  396.      *
  397.      * @since   12.3
  398.      */
  399.     public function emailUser($target, $subject = null, $text = null, $ccme = null)
  400.     {
  401.         // Get the token.
  402.         $token = $this->getToken($target, 'emailuser');
  403.  
  404.         // Build the request path.
  405.         $path = '?action=emailuser';
  406.  
  407.         // Build the request data.
  408.         $data = array(
  409.             'target' => $target,
  410.             'token' => $token,
  411.             'subject' => $subject,
  412.             'text' => $text,
  413.             'ccme' => $ccme
  414.         );
  415.  
  416.         // Send the request.
  417.         $response = $this->client->post($this->fetchUrl($path), $data);
  418.  
  419.         return $this->validateResponse($response);
  420.     }
  421.  
  422.     /**
  423.      * Method to get access token.
  424.      *
  425.      * @param   string  $user     The User to get token.
  426.      * @param   string  $intoken  The type of token.
  427.      *
  428.      * @return  object 
  429.      *
  430.      * @since   12.3
  431.      */
  432.     public function getToken($user, $intoken)
  433.     {
  434.         // Build the request path.
  435.         $path = '?action=query&prop=info&intoken=' . $intoken . '&titles=User:' . $user;
  436.  
  437.         // Send the request.
  438.         $response = $this->client->post($this->fetchUrl($path), null);
  439.  
  440.         return (string) $this->validateResponse($response)->query->pages->page[$intoken . 'token'];
  441.     }
  442. }

Documentation generated on Tue, 19 Nov 2013 15:16:40 +0100 by phpDocumentor 1.4.3