class clients_connection_drupal_services_6_2 in Web Service Clients 6.2

Drupal client for services on a Drupal 6 site for Services 6.x-2.x.

Developed against Services 6.x-2.4.

Note that the Services 5.x-0.92 class is a subclass of this and uses several of its methods.

Hierarchy

• class \clients_connection_base
  • class \clients_connection_drupal_services
    • class \clients_connection_drupal_services_6_2

File

connections/clients_drupal/clients_drupal.inc, line 369

Contains classes for Client connections handlers.

class clients_connection_drupal_services_6_2 extends clients_connection_drupal_services {

  // ============================================ D6-2: Connection form methods.

  /**
   * Extra form elements specific to a class's edit form.
   *
   * This is the same pattern as node_form() -- just ignore the object behind
   * the curtain ;)
   *
   * This is common to versions 6-2 and 5 of Drupal Services.
   *
   * @param $form_state
   *  The form state from the main form, which you probably don't need anyway.
   *
   * @return
   *  A FormAPI form array. This will be merged in with basic data and the
   *  submit button added.
   *
   * @see clients_connection_form()
   * @see clients_connection_form()
   * @see clients_connection_form_submit()
   */
  function connectionSettingsForm(&$form_state) {
    $form = array();
    $form['endpoint'] = array(
      '#type' => 'textfield',
      '#title' => t('Connection endpoint'),
      '#default_value' => $this->new ? '' : $this->endpoint,
      '#size' => 50,
      '#maxlength' => 100,
      '#description' => t('Remote service URL e.g. http://mysite.com/services/xmlrpc'),
      '#required' => TRUE,
    );
    $form['configuration'] = array(
      '#type' => 'fieldset',
      '#title' => t('Configuration'),
      '#collapsible' => FALSE,
      '#tree' => TRUE,
    );
    $form['configuration']['domain'] = array(
      '#type' => 'textfield',
      '#title' => t('Domain'),
      '#default_value' => $this->new ? '' : $this->configuration['domain'],
      '#size' => 50,
      '#maxlength' => 100,
      '#description' => t('This should be same as the \'Domain\' field used by the Services authentication key on the server you are connecting to.'),
      '#required' => TRUE,
    );
    $form['configuration']['servicekey'] = array(
      '#type' => 'textfield',
      '#title' => t('Service key'),
      '#default_value' => $this->new ? '' : $this->configuration['servicekey'],
      '#size' => 50,
      '#maxlength' => 40,
      '#attributes' => array(
        'autocomplete' => 'off',
      ),
      '#description' => t('This should be same as the \'Key\' field used by the Services authentication key on the server you are connecting to.'),
      '#required' => TRUE,
    );
    $form['configuration']['username'] = array(
      '#type' => 'textfield',
      '#title' => t('Service username'),
      '#default_value' => $this->new ? '' : $this->configuration['username'],
      '#size' => 30,
      '#maxlength' => 60,
      '#attributes' => array(
        'autocomplete' => 'off',
      ),
      '#description' => t('This should be same as the username on the server you are connecting to.'),
      '#required' => TRUE,
    );
    $password_desc = $this->new ? t('This should be same as the password on the server you are connecting to.') : t('This should be same as the password on the server you are connecting to. Leave blank unless you need to change this.');
    $form['configuration']['password'] = array(
      '#type' => 'password',
      '#title' => t('Service password'),
      '#size' => 30,
      '#maxlength' => 60,
      '#attributes' => array(
        'autocomplete' => 'off',
      ),
      '#description' => $password_desc,
      '#required' => $this->new,
    );
    return $form;
  }

  /**
   * Submit handler for saving/updating connections of this class.
   *
   * @see clients_connection_form_submit()
   */
  static function connectionSettingsForm_submit($form, &$form_state) {
    $old_connection = $form_state['values']['old_connection'];

    // Check whether we're editing or adding a new connection.
    if ($old_connection->new) {
      $form_state['values']['configuration']['password'] = clients_drupal_encrypt($form_state['values']['configuration']['password']);
    }
    else {

      // Prepare password for serialized storage
      if (empty($form_state['values']['configuration']['password'])) {

        // Set password to original if blank.
        $form_state['values']['configuration']['password'] = $old_connection->configuration['password'];
      }
      $form_state['values']['configuration']['password'] = clients_drupal_encrypt($form_state['values']['configuration']['password']);
    }
  }

  /**
   * Format the connection's endpoint as a link.
   *
   * @param $url
   *  The connection's endpoint.
   *
   * @return
   *  The string to display in the admin UI. Subclasses may format this as a
   *  link to the remote site.
   */
  function formatEndpoint($url) {
    $base_url = str_replace('services/xmlrpc', '', $url);
    $link = l($base_url, $base_url);
    return $link . 'services/xmlrpc';
  }

  // ============================================ D6-2: Connection methods.

  /**
   * Log in as the configured user.
   *
   * Helper for callMethodArray(), because logging in doesn't change between
   * versions of Services.
   *
   * @param $session_id
   *  A session ID obtained from calling system.connect.
   *
   * @return
   *  The full data returned from the remote call.
   */
  function call_user_login($session_id) {

    // Get the API key-related arguments.
    $key_args = $this
      ->xmlrpc_key_args('user.login');

    //dsm($key_args);

    // Build the array of connection arguments we need to log in.
    $username = $this->configuration['username'];
    $password = $this->configuration['password'];
    $login_args = array_merge(array(
      $this->endpoint,
      'user.login',
    ), $key_args, array(
      $session_id,
    ), array(
      $username,
      $password,
    ));

    // Call the xmlrpc method with our array of arguments. This accounts for
    // whether we use a key or not, and the extra parameters to pass to the method.
    $login = call_user_func_array('xmlrpc', $login_args);
    return $login;
  }

  /**
   * Call a remote method with an array of parameters.
   *
   * This is technically internal; use the more DX-friendly callMethod() or
   * the all-in-one clients_connection_call().
   *
   * @param $method
   *  The name of the remote method to call.
   * @param
   *  All other parameters are passed to the remote method.
   *
   * @return
   *  Whatever is returned from the remote site.
   */
  function callMethodArray($method, $method_params = array()) {

    // If HTTP requests are enabled, report the error and do nothing.
    // (Cribbed from Content distribution module.)
    if (variable_get('drupal_http_request_fails', FALSE) == TRUE) {
      drupal_set_message(t('Drupal is unable to make HTTP requests. Please reset the HTTP request status.'), 'error', FALSE);
      watchdog('clients', 'Drupal is unable to make HTTP requests. Please reset the HTTP request status.', array(), WATCHDOG_CRITICAL);
      return;
    }
    $config = $this->configuration;
    $endpoint = $this->endpoint;
    $api_key = $this->configuration['servicekey'];
    $this->method = $method;

    // Connect to the remote system service to get an initial session id to log in with.
    $connect = xmlrpc($this->endpoint, 'system.connect');
    $session_id = $connect['sessid'];
    $this
      ->handleXmlrpcError();

    // We may want to call only system.connect for testing purposes.
    if ($method == 'system.connect') {
      return $connect;
    }

    // Log in and get the user's session ID.
    $login = $this
      ->call_user_login($session_id);
    $login_session_id = $login['sessid'];
    $this
      ->handleXmlrpcError();

    // If the requested method is user.login, we're done.
    if ($method == 'user.login') {
      return $login;
    }

    // Get the API key-related arguments.
    $key_args = $this
      ->xmlrpc_key_args($method);

    // Build the array of connection arguments for the method we want to call.
    $xmlrpc_args = array_merge(array(
      $this->endpoint,
      $method,
    ), $key_args, array(
      $login_session_id,
    ), $method_params);

    // Call the xmlrpc method with our array of arguments.
    $result = call_user_func_array('xmlrpc', $xmlrpc_args);

    // Throw an exception for errors from the remote call.
    $this
      ->handleXmlrpcError();
    return $result;
  }

  /**
   * Helper function to get key-related method arguments for the XMLRPC call.
   */
  function xmlrpc_key_args($method) {
    $api_key = $this->configuration['servicekey'];

    // Build the API key arguments - if no key supplied supplied, presume not required
    if ($api_key != '') {

      // Use API key to get a hash code for the service.
      $timestamp = (string) strtotime("now");

      // Note that the domain -- at least for Services 5 and 6.x-2.x -- is a
      // purely arbitrary string more akin to a username.
      // See http://drupal.org/node/821700 for background.
      $domain = $this->configuration['domain'];

      /*
      if (!strlen($domain)) {
        $domain = $_SERVER['SERVER_NAME'];
        if ($_SERVER['SERVER_PORT'] != 80) {
          $domain .= ':' . $_SERVER['SERVER_PORT'];
        }
      }
      */
      $nonce = uniqid();
      $hash_parameters = array(
        $timestamp,
        $domain,
        $nonce,
        $method,
      );
      $hash = hash_hmac("sha256", implode(';', $hash_parameters), $api_key);
      $key_args = array(
        $hash,
        $domain,
        $timestamp,
        $nonce,
      );
    }
    else {
      $key_args = array();
    }
    return $key_args;
  }

  // ============================================ D6-2: Testing system.

  /**
   * Connection test button handler: loading a node on D6.
   */
  function testConnectionNodeLoad(&$button_form_values) {

    // Must be cast to integer for faffiness of XMLRPC and Services.
    $nid = (int) $button_form_values['nid'];
    $fields = array();
    try {
      $node = $this
        ->callMethodArray('node.get', array(
        $nid,
        $fields,
      ));
    } catch (Exception $e) {
      drupal_set_message(t('Could not retrieve a node from the remote site, got error message "@message".', array(
        '@message' => $e
          ->getMessage(),
      )), 'warning');

      //dsm($e);
      return;
    }
    if (is_array($node) && isset($node['nid'])) {
      drupal_set_message(t('Sucessfully retrieved node %title (nid @nid).', array(
        '%title' => $node['title'],
        '@nid' => $node['nid'],
      )));
    }
    return $node;
  }

}

Members

Name	Modifiers	Type	Description	Overrides
clients_connection_base::$cid	public	property	The connection id. Only set if this is stored in the database.
clients_connection_base::$configuration	public	property	An array of further configuration options.
clients_connection_base::$endpoint	public	property	The URL this connection connects to.
clients_connection_base::$name	public	property	The machine name of the connection.
clients_connection_base::callMethod		function	Call a remote method.
clients_connection_drupal_services::getTestOperations		function	Provide buttons for the connection testing page. Overrides clients_connection_base::getTestOperations	1
clients_connection_drupal_services::handleXmlrpcError		function	Common helper for reacting to an error from an XMLRPC call.
clients_connection_drupal_services::testConnectionConnect		function	Connection test button handler: basic connection.
clients_connection_drupal_services::testConnectionLogin		function	Connection test button handler: user login.
clients_connection_drupal_services::testConnectionNodeLoadValidate		function	Connection test button validate handler: loading a node.
clients_connection_drupal_services::__construct		function	Constructor method. Overrides clients_connection_base::__construct
clients_connection_drupal_services_6_2::callMethodArray		function	Call a remote method with an array of parameters. Overrides clients_connection_base::callMethodArray	1
clients_connection_drupal_services_6_2::call_user_login		function	Log in as the configured user.
clients_connection_drupal_services_6_2::connectionSettingsForm		function	Extra form elements specific to a class's edit form. Overrides clients_connection_base::connectionSettingsForm
clients_connection_drupal_services_6_2::connectionSettingsForm_submit	static	function	Submit handler for saving/updating connections of this class. Overrides clients_connection_base::connectionSettingsForm_submit
clients_connection_drupal_services_6_2::formatEndpoint		function	Format the connection's endpoint as a link. Overrides clients_connection_base::formatEndpoint
clients_connection_drupal_services_6_2::testConnectionNodeLoad		function	Connection test button handler: loading a node on D6. Overrides clients_connection_drupal_services::testConnectionNodeLoad	1
clients_connection_drupal_services_6_2::xmlrpc_key_args		function	Helper function to get key-related method arguments for the XMLRPC call.