modules/versioncontrol/versioncontrol.module

<?php
// $Id: versioncontrol.module,v 1.153 2009/10/16 14:15:26 sdboyer Exp $
/**
 * @file
 * Version Control API - An interface to version control systems
 * whose functionality is provided by pluggable back-end modules.
 *
 * Copyright 2006, 2007 Derek Wright ("dww" , http://drupal.org/user/46549)
 * Copyright 2007, 2008, 2009 by Jakob Petsovits ("jpetso", http://drupal.org/user/56020)
 */

/**
 * @name backend capabilities
 * Optional capabilities that backend modules can provide.
 */
//@{
define('VERSIONCONTROL_CAPABILITY_ATOMIC_COMMITS',          1);
define('VERSIONCONTROL_CAPABILITY_COMMIT_RESTRICTIONS',     2);
define('VERSIONCONTROL_CAPABILITY_BRANCH_TAG_RESTRICTIONS', 3);
define('VERSIONCONTROL_CAPABILITY_DIRECTORY_REVISIONS',     4);
//@}

/**
 * @name VCS actions
 * for a single item (file or directory) in a commit, or for branches and tags.
 */
//@{
define('VERSIONCONTROL_ACTION_ADDED',    1);
define('VERSIONCONTROL_ACTION_MODIFIED', 2);
define('VERSIONCONTROL_ACTION_MOVED',    3); //< == renamed
define('VERSIONCONTROL_ACTION_COPIED',   4);
define('VERSIONCONTROL_ACTION_MERGED',   5);
define('VERSIONCONTROL_ACTION_DELETED',  6);
define('VERSIONCONTROL_ACTION_REPLACED', 7);
define('VERSIONCONTROL_ACTION_OTHER',    8); //< for example, SVN revprop-only changes
//@}

/**
 * @name VCS flag for operation item database entries
 * The flag for operation item database entries, specifying whether an item
 * is actually a direct "member" item of that operation or just a cached
 * source item that speeds up operation queries. (Background: we want some
 * source items to be considered when the caller passes a 'paths' constraint,
 * but joining those is unnecessarily inefficient. Therefore, searched source
 * items get directly included in the {versioncontrol_operation_items} table.)
 * This is an implementation detail, the API user won't get to see this. Ever.
 */
//@{
define('VERSIONCONTROL_OPERATION_MEMBER_ITEM',          1);
define('VERSIONCONTROL_OPERATION_CACHED_AFFECTED_ITEM', 2);
//@}

/**
 * @name Constraint 'cardinality' key
 * Allowed values for the 'cardinality' key in constraint descriptions
 * provided by hook_versioncontrol_operation_constraint_info().
 */
//@{
define('VERSIONCONTROL_CONSTRAINT_MULTIPLE',           1); // default
define('VERSIONCONTROL_CONSTRAINT_SINGLE',             2);
define('VERSIONCONTROL_CONSTRAINT_SINGLE_OR_MULTIPLE', 3);
//@}

/**
 * @name User relation constraints
 * Allowed values for use with the 'user_relation' constraint in
 * versioncontrol_get_operations() queries.
 */
//@{
define('VERSIONCONTROL_USER_ASSOCIATED',        1);
define('VERSIONCONTROL_USER_ASSOCIATED_ACTIVE', 2);
//@}

/** Used internally by the repository and account admin pages. Private constant. */
define('VERSIONCONTROL_FORM_CREATE', FALSE);

//TODO: define if we want to do the load each time, per use, or all-in-one like views.inc
require_once drupal_get_path('module', 'versioncontrol') .'/includes/VersioncontrolAccount.php';
require_once drupal_get_path('module', 'versioncontrol') .'/includes/classes.inc';
/**
 * Implementation of hook_init():
 * Code that is run on every page request, except for cached ones.
 */
function versioncontrol_init() {
  // The backend-only part of the API.
  module_load_include('inc', 'versioncontrol', 'versioncontrol-backend');
}

/**
 * Implementation of hook_theme().
 */
function versioncontrol_theme() {
  $theme = array();
  $theme['versioncontrol_account_username'] = array(
    'arguments' => array('uid', 'username', 'repository', 'options' => NULL),
  );
  $theme['versioncontrol_user_statistics_table'] = array(
    'arguments' => array('statistics', 'options'),
  );
  $theme['versioncontrol_user_statistics_item_list'] = array(
    'arguments' => array('statistics', 'more_link'),
  );
  $theme['versioncontrol_user_statistics_account'] = array(
    'arguments' => array('user_stats'),
  );
  return $theme;
}

/**
 * Implementation of hook_user():
 * Register additional user account edit tabs,
 * and delete VCS accounts when the associated user account is deleted.
 */
function versioncontrol_user($type, &$edit, &$user, $category = NULL) {
  switch ($type) {
    case 'categories':
      $categories = array();
      $categories[] = array(
        'name' => 'versioncontrol',
        // user_menu() pipes 'title' though check_plain() already.
        'title' => 'Repository accounts',
        'weight' => 99,
      );
      return $categories;

    case 'delete':
      $accounts = VersioncontrolAccountCache::getInstance()->getAccounts(array('uids' => array($user->uid)), TRUE);
      if (empty($accounts)) {
        return;
      }
      foreach ($accounts as $uid => $usernames_by_repository) {
        foreach ($usernames_by_repository as $repo_id => $account) {
          $account->delete();
        }
      }
      break;

  }
}

/**
 * Implementation of hook_menu().
 */
function versioncontrol_menu() {
  $items = array();

  $admin = array(
    'page callback' => 'drupal_get_form',
    'access arguments' => array('administer version control systems'),
    'file' => 'versioncontrol.admin.inc',
  );

  // If Version Control API is used without the Project module,
  // we need to define our own version of /admin/project
  // so the rest of our admin pages all work.
  if (!module_exists('project')) {
    $items['admin/project'] = array(
      'title' => 'Project administration',
      'description' => 'Administrative interface for project management and related modules.',
      'position' => 'left',
      'weight' => 3,
      'page callback' => 'system_admin_menu_block_page',
      'access arguments' => array('administer site configuration'),
      'file' => 'system.admin.inc',
      'file path' => drupal_get_path('module', 'system'),
    );
  }

  $items['admin/project/versioncontrol-settings'] = array(
    'title' => 'Version control settings',
    'description' => 'Configure settings for Version Control API and related modules.',
    'page arguments' => array('versioncontrol_admin_settings'),
    'type' => MENU_NORMAL_ITEM,
  ) + $admin;
  $items['admin/project/versioncontrol-settings/general'] = array(
    'title' => 'General',
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'weight' => -1,
  );

  $items['admin/project/versioncontrol-repositories'] = array(
    'title' => 'VCS repositories',
    'description' => 'Define and configure what version control repositories are connected to your site, and how to integrate each repository with repository browser tools such as ViewVC or WebSVN.',
    'page arguments' => array('versioncontrol_admin_repository_list'),
  ) + $admin;

  $weight = 1;
  $items['admin/project/versioncontrol-repositories/list'] = array(
    'title' => 'List',
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'weight' => $weight,
  );

  // former !$may_cache
  /// TODO: Backend specific stuff was done in !$may_cache, as it once
  ///       screwed up after activating a new backend in admin/build/modules.
  ///       Make sure this works now.
  foreach (versioncontrol_get_backends() as $vcs => $backend) {
    $items['admin/project/versioncontrol-repositories/add-'. $vcs] = array(
      'title' => 'Add @vcs repository',
      'title arguments' => array('@vcs' => $backend->name),
      'page arguments' => array('versioncontrol_admin_repository_edit',
        VERSIONCONTROL_FORM_CREATE, $vcs
      ),
      'type' => MENU_LOCAL_TASK,
      'weight' => ++$weight,
    ) + $admin;
  }
  // end former !$may_cache

  $items['admin/project/versioncontrol-repositories/edit/%versioncontrol_repository'] = array(
    'title' => 'Edit repository',
    'page arguments' => array('versioncontrol_admin_repository_edit', 4),
    'type' => MENU_CALLBACK,
  ) + $admin;
  $items['admin/project/versioncontrol-repositories/delete/%versioncontrol_repository'] = array(
    'title' => 'Delete repository',
    'page arguments' => array('versioncontrol_admin_repository_delete_confirm', 4),
    'type' => MENU_CALLBACK,
  ) + $admin;

  $items['admin/project/versioncontrol-accounts'] = array(
    'title' => 'VCS accounts',
    'description' => 'Manage associations of Drupal users to VCS user accounts.',
    'page arguments' => array('versioncontrol_admin_account_list_form'),
    'type' => MENU_NORMAL_ITEM,
  ) + $admin;
  $items['admin/project/versioncontrol-accounts/list'] = array(
    'title' => 'List',
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'weight' => 0,
  );

  // former !$may_cache
  /// TODO: Backend specific stuff was done in !$may_cache, as it once
  ///       screwed up after activating a new backend in admin/build/modules.
  ///       Make sure this works now.
  // TODO (sdb): this should all be reworked using a version of the loader that
  // takes additional arguments for implementation checking.
  foreach (versioncontrol_get_backends() as $vcs => $backend) {
    // we need to check and interface, so create an empty repo here
    $repo = new $backend->classes['repo'](0, array(), FALSE);
    if ($repo instanceof VersioncontrolRepositoryImportExport) {
      $items['admin/project/versioncontrol-accounts/import'] = array(
        'title' => 'Import',
        'description' => 'Import an existing set of VCS user accounts.',
        'page arguments' => array('versioncontrol_admin_account_import_form'),
        'type' => MENU_LOCAL_TASK,
        'weight' => 2,
      ) + $admin;
      $items['admin/project/versioncontrol-accounts/export'] = array(
        'title' => 'Export',
        'description' => 'Export VCS user accounts of a specific repository.',
        'page arguments' => array('versioncontrol_admin_account_export_form'),
        'type' => MENU_LOCAL_TASK,
        'weight' => 3,
      ) + $admin;
      $items['admin/project/versioncontrol-accounts/export/%versioncontrol_repository'] = array(
        'title' => 'Export',
        'page callback' => 'versioncontrol_admin_account_export_page',
        'page arguments' => array(4),
        'type' => MENU_CALLBACK,
      ) + $admin;
    }
  }
  // end former !$may_cache

  // Account registration and editing pages for the regular user.
  $items['versioncontrol/register'] = array(
    'title' => 'Get commit access',
    'page callback' => 'versioncontrol_account_register_page',
    'access callback' => TRUE, // access checking is done in the page callback
    'file' => 'versioncontrol.pages.inc',
    'type' => MENU_SUGGESTED_ITEM,
  );
  $items['user/%versioncontrol_user_accounts/edit/versioncontrol'] = array(
    // Load with $include_unauthorized == TRUE, so that the user can inspect
    // his/her VCS accounts even if they are not approved by the admin yet.
    'load arguments' => array(TRUE),
    'title callback' => 'versioncontrol_user_accounts_title_callback',
    'title arguments' => array(1),
    'page callback' => 'versioncontrol_account_page',
    'page arguments' => array(1),
    'access callback' => 'versioncontrol_private_account_access',
    'access arguments' => array(1),
    'file' => 'versioncontrol.pages.inc',
    'weight' => 99,
    'type' => MENU_LOCAL_TASK,
  );

  // Autocomplete callback for Drupal usernames that have access to
  // the repo_id given in arg(3). (No need to fetch the full repository,
  // as the callback uses a raw & safe database query anyways.)
  $items['versioncontrol/user/autocomplete'] = array(
    'title' => 'Version control user autocomplete',
    'page callback' => 'versioncontrol_user_autocomplete',
    'access callback' => 'versioncontrol_user_access',
    'type' => MENU_CALLBACK,
  );

  return $items;
}

/**
 * Custom access callback, determining if the current user (or the one given
 * in @p $account, if set) is permitted to administer version control system
 * functionality.
 */
function versioncontrol_admin_access($account = NULL) {
  return user_access('administer version control systems', $account);
}

/**
 * Custom access callback, determining if the current user (or the one given
 * in @p $account, if set) is permitted to use version control system
 * functionality.
 */
function versioncontrol_user_access($account = NULL) {
  return user_access('use version control systems', $account)
    || user_access('administer version control systems', $account);
}

/**
 * Custom access callback, determining if the current user (or the one given
 * in @p $account, if set) is permitted to view version control account
 * settings of the user specified the first user id in @p $vcs_accounts.
 * (We take that parameter because it's what the '%versioncontrol_user_accounts'
 * wildcard returns.)
 */
function versioncontrol_private_account_access($vcs_accounts, $account = NULL) {
  $viewed_uid = key($vcs_accounts);
  if (!$viewed_uid) {
    return FALSE;
  }
  if (is_null($account)) {
    global $user;
    $account = clone $user;
  }
  return ($viewed_uid == $account->uid && user_access('use version control systems', $account))
    || user_access('administer version control systems', $account);
}

/**
 * Title callback for the "user/%versioncontrol_user_accounts/edit/versioncontrol" tab.
 */
function versioncontrol_user_accounts_title_callback($accounts) {
  $usernames = array();
  foreach ($accounts as $uid => $user_accounts) {
    foreach ($user_accounts as $repo_id => $account) {
      $usernames[] = $account->vcs_username;
    }
  }
  $repositories = VersioncontrolRepositoryCache::getInstance()->getRepositories(array(
    'repo_ids' => array_keys(reset($accounts)), // a.k.a. list of account repo_ids
  ));
  $vcses = array();
  foreach ($repositories as $repository) {
    $vcses[$repository['vcs']] = TRUE;
  }
  if (count($vcses) == 1) {
    $repo = array_shift($repositories);
    return check_plain($repo->backend->name);
  }
  return t('Repository accounts');
}

/**
 * Implementation of hook_perm().
 */
function versioncontrol_perm() {
  return array(
    'administer version control systems',
    'use version control systems',
  );
}

/**
 * Menu wildcard loader for repository ids ('%versioncontrol_repository').
 * Use this only for menu paths - if you want to retrieve a repository with
 * your own code, use versioncontrol_get_repository() instead.
 * (Yeah, I know duplicate functions are bad. Hopefully we can sort this out
 * when repositories are made into real objects, as
 * versioncontrol_get_repository() will be a static class method then.)
 */
function versioncontrol_repository_load($repo_id) {
  $repository = VersioncontrolRepositoryCache::getInstance()->getRepository($repo_id);
  return empty($repository) ? FALSE : $repository;
}

/**
 * Menu wildcard loader for '%versioncontrol_user_accounts':
 * Load all VCS accounts of a given user (in the format that
 * VersioncontrolAccountCache::getInstance()->getAccounts() returns) and return either that
 * or FALSE if no VCS accounts exist for this user.
 *
 * @param $uid
 *   Drupal user id of the user whose VCS accounts should be loaded.
 * @param $include_unauthorized
 *   Will be passed on to VersioncontrolAccountCache::getInstance()->getAccounts(), see the
 *   API documentation of that function.
 */
function versioncontrol_user_accounts_load($uid, $include_unauthorized = FALSE) {
  $accounts = VersioncontrolAccountCache::getInstance()->getAccounts(array('uids' => array($uid)), $include_unauthorized);
  return empty($accounts) ? FALSE : $accounts;
}


// API functions start here.

/**
 * Get a list of all backends with its detailed information.
 *
 * @return
 *   A structured array containing information about all known backends.
 *   Array keys are the unique string identifier of the version control
 *   system.
 *   The corresponding array values are VersioncontrolBackend children
 *   objects.
 *
 *   If no single backends can be found, an empty array is returned.
 *
 *   A real-life example of such a result array can be found
 *   in the FakeVCS example module.
 */
function versioncontrol_get_backends() {
  static $backends;

  if (!isset($backends)) {
    $backends = module_invoke_all('versioncontrol_backends');
  }
  return $backends;
}

/**
 * Determine all user account authorization methods
 * (free for all, only admin may create accounts, per-repository approval, ...)
 * by invoking hook_versioncontrol_authorization_methods().
 *
 * @return
 *   A structured array with the unique string identifier of the method as keys
 *   and the user-visible description (wrapped in t()) as values.
 */
function versioncontrol_get_authorization_methods() {
  static $methods;

  if (!isset($methods)) {
    $methods = module_invoke_all('versioncontrol_authorization_methods');
  }
  return $methods;
}

/**
 * Implementation of hook_versioncontrol_authorization_methods().
 *
 * @return
 *   A structured array containing information about authorization methods
 *   provided by this module, wrapped in a structured array. Array keys are
 *   the unique string identifiers of each authorization method, and
 *   array values are the user-visible method descriptions (wrapped in t()).
 */
function versioncontrol_versioncontrol_authorization_methods() {
  return array(
    'versioncontrol_admin' => t('Only administrators can create accounts'),
    'versioncontrol_none' => t('No approval required'),
  );
}

function _versioncontrol_get_fallback_authorization_method() {
  return 'versioncontrol_admin';
}

/**
 * Assemble a list of query constraints given as string array that's
 * supposed to be imploded with an SQL "AND", and a $params array containing
 * the corresponding parameter values for all the '%d' and '%s' placeholders.
 */
function _versioncontrol_construct_repository_constraints($constraints, $backends) {
  $and_constraints = array();
  $params = array();

  // Filter out repositories of which the corresponding backend is not enabled,
  // and handle the 'vcs' constraint at the same time.
  $placeholders = array();
  $vcses = array_keys($backends);
  if (isset($constraints['vcs'])) {
    $vcses = array_intersect($vcses, $constraints['vcs']);
  }
  if (empty($vcses)) {
    $and_constraints[] = 'FALSE'; // no backends are enabled of those that have been requested
  }
  else {
    foreach ($vcses as $vcs) {
      $placeholders[] = "'%s'";
      $params[] = $vcs;
    }
    $and_constraints[] = 'r.vcs IN ('. implode(',', $placeholders) .')';
  }

  if (isset($constraints['repo_ids'])) {
    if (empty($constraints['repo_ids'])) {
      $and_constraints[] = 'FALSE';
    }
    else {
      $placeholders = array();
      foreach ($constraints['repo_ids'] as $repo_id) {
        $placeholders[] = '%d';
        $params[] = $repo_id;
      }
      $and_constraints[] = 'r.repo_id IN ('. implode(',', $placeholders) .')';
    }
  }

  if (isset($constraints['names'])) {
    if (empty($constraints['names'])) {
      $and_constraints[] = 'FALSE';
    }
    else {
      $placeholders = array();
      foreach ($constraints['names'] as $name) {
        $placeholders[] = "'%s'";
        $params[] = $name;
      }
      $and_constraints[] = 'r.name IN ('. implode(',', $placeholders) .')';
    }
  }

  return array($and_constraints, $params);
}

/**
 * Execute a query with either db_query(), db_query_range() or pager_query().
 * Which one of those is called, and with which parameters, is specified by the
 * @p $options array, see versioncontrol_get_operations() for a description of
 * possible array keys and option values.
 */
function _versioncontrol_query($query, $params, $options) {
  if (isset($options['query_type']) && $options['query_type'] == 'pager') {
    $element = isset($options['pager_element']) ? $options['pager_element'] : 0;
    return pager_query($query, $options['count'], $element, NULL, $params);
  }
  elseif (isset($options['query_type']) && $options['query_type'] == 'range') {
    return db_query_range($query, $params, $options['from'], $options['count']);
  }
  else {
    return db_query($query, $params);
  }
}

/**
 * Implementation of hook_versioncontrol_operation_constraint_info().
 */
function versioncontrol_versioncontrol_operation_constraint_info() {
  return array(
    'vcs' => array('join callback' => 'versioncontrol_table_repositories_join'),
    'vc_op_ids' => array(),
    'revisions' => array(),
    'repo_ids' => array('join callback' => 'versioncontrol_table_repositories_join'),
    'date_lower' => array('cardinality' => VERSIONCONTROL_CONSTRAINT_SINGLE),
    'date_upper' => array('cardinality' => VERSIONCONTROL_CONSTRAINT_SINGLE),
    'uids' => array(),
    'usernames' => array(),
    'user_relation' => array('cardinality' => VERSIONCONTROL_CONSTRAINT_SINGLE),
    'message' => array('cardinality' => VERSIONCONTROL_CONSTRAINT_SINGLE_OR_MULTIPLE),
    'item_revision_ids' => array('join callback' => 'versioncontrol_table_operation_items_join'),
    'item_revisions' => array('join callback' => 'versioncontrol_table_item_revisions_join'),
    'paths' => array('join callback' => 'versioncontrol_table_item_revisions_join'),
    'labels' => array('join callback' => 'versioncontrol_table_labels_join'),
    'tags' => array('join callback' => 'versioncontrol_table_labels_join'),
    'branches' => array('join callback' => 'versioncontrol_table_labels_join'),
    'types' => array(),
  );
}

/**
 * Implementation of hook_versioncontrol_operation_constraints_alter():
 * Include only operations for enabled backends in the query.
 */
function versioncontrol_versioncontrol_operation_constraints_alter($constraints) {
  // Filter out entries of which the corresponding backend is not enabled,
  // and handle the 'vcs' constraint at the same time.
  $backends = versioncontrol_get_backends();
  $vcses = array_keys($backends);

  if (isset($constraints['vcs'])) {
    $vcses = array_intersect($vcses, $constraints['vcs']);
  }
  $constraints['vcs'] = $vcses;
}

/**
 * Filter operations by their associated backend.
 */
function versioncontrol_operation_constraint_vcs($constraint, &$tables, &$and_constraints, &$params) {
  $placeholders = array();
  foreach ($constraint as $vcs) {
    $placeholders[] = "'%s'";
    $params[] = $vcs;
  }
  $and_constraints[] = $tables['versioncontrol_repositories']['alias'] .'.vcs
                        IN ('. implode(',', $placeholders) .')';
}

/**
 * Filter operations by their version control operation id.
 */
function versioncontrol_operation_constraint_vc_op_ids($constraint, &$tables, &$and_constraints, &$params) {
  $placeholders = array();
  foreach ($constraint as $vc_op_id) {
    $placeholders[] = '%d';
    $params[] = $vc_op_id;
  }
  $and_constraints[] = $tables['versioncontrol_operations']['alias'] .'.vc_op_id
                        IN ('. implode(',', $placeholders) .')';
}

/**
 * Filter operations by their revision identifier.
 */
function versioncontrol_operation_constraint_revisions($constraint, &$tables, &$and_constraints, &$params) {
  $placeholders = array();
  foreach ($constraint as $revision) {
    $placeholders[] = "'%s'";
    $params[] = $revision;
  }
  $and_constraints[] = $tables['versioncontrol_operations']['alias'] .'.revision
                        IN ('. implode(',', $placeholders) .')';
}

/**
 * Filter operations by their repository id.
 */
function versioncontrol_operation_constraint_repo_ids($constraint, &$tables, &$and_constraints, &$params) {
  $placeholders = array();
  foreach ($constraint as $repo_id) {
    $placeholders[] = '%d';
    $params[] = $repo_id;
  }
  $and_constraints[] = $tables['versioncontrol_repositories']['alias'] .'.repo_id
                        IN ('. implode(',', $placeholders) .')';
}

/**
 * Filter operations by a lower date bound.
 */
function versioncontrol_operation_constraint_date_lower($constraint, &$tables, &$and_constraints, &$params) {
  $and_constraints[] = '('. $tables['versioncontrol_operations']['alias'] .'.date >= %d)';
  $params[] = $constraint;
}

/**
 * Filter operations by an upper date bound.
 */
function versioncontrol_operation_constraint_date_upper($constraint, &$tables, &$and_constraints, &$params) {
  $and_constraints[] = '('. $tables['versioncontrol_operations']['alias'] .'.date <= %d)';
  $params[] = $constraint;
}

/**
 * Filter operations by their associated Drupal user id.
 */
function versioncontrol_operation_constraint_uids($constraint, &$tables, &$and_constraints, &$params) {
  $placeholders = array();
  foreach ($constraint as $uid) {
    $placeholders[] = '%d';
    $params[] = $uid;
  }
  $and_constraints[] = $tables['versioncontrol_operations']['alias'] .'.uid
                        IN ('. implode(',', $placeholders) .')';
}

/**
 * Filter operations by the VCS username of the operation author.
 */
function versioncontrol_operation_constraint_usernames($constraint, &$tables, &$and_constraints, &$params) {
  $placeholders = array();
  foreach ($constraint as $username) {
    $placeholders[] = "'%s'";
    $params[] = $username;
  }
  $and_constraints[] = $tables['versioncontrol_operations']['alias'] .'.username
                        IN ('. implode(',', $placeholders) .')';
}

/**
 * Filter operations by associated Drupal user status of the operation author.
 */
function versioncontrol_operation_constraint_user_relation($constraint, &$tables, &$and_constraints, &$params) {
  $and_constraints[] = $tables['versioncontrol_operations']['alias'] .'.uid <> 0';

  if ($constraint == VERSIONCONTROL_USER_ASSOCIATED_ACTIVE) {
    versioncontrol_table_users_join($tables);
    $and_constraints[] = $tables['users']['alias'] .'.status = 1';
  }
}

/**
 * Filter operations by their log message.
 */
function versioncontrol_operation_constraint_message($constraint, &$tables, &$and_constraints, &$params) {
  $or_constraints = array();
  foreach ($constraint as $message_part) {
    $or_constraints[] = $tables['versioncontrol_operations']['alias'] .".message LIKE '%s'";
    $params[] = '%'. $message_part .'%';
  }
  $and_constraints[] = '('. implode(' OR ', $or_constraints) .')';
}

/**
 * Filter operations by item_revision_ids of associated items.
 */
function versioncontrol_operation_constraint_item_revision_ids($constraint, &$tables, &$and_constraints, &$params) {
  $or_constraints = array();

  $placeholders = array();
  foreach ($constraint as $item_revision_id) {
    $placeholders[] = '%d';
    $params[] = $item_revision_id;
  }
  $and_constraints[] = $tables['versioncontrol_operation_items']['alias'] .'.item_revision_id
                        IN ('. implode(',', $placeholders) .')';

  // Exact search for target items, no fuzzy source item path results.
  $params[] = VERSIONCONTROL_OPERATION_MEMBER_ITEM;
  $and_constraints[] = $tables['versioncontrol_operation_items']['alias'] .'.type = %d';
}

/**
 * Filter operations by revision identifiers of associated items.
 */
function versioncontrol_operation_constraint_item_revisions($constraint, &$tables, &$and_constraints, &$params) {
  $or_constraints = array();

  $placeholders = array();
  foreach ($constraint as $revision) {
    $placeholders[] = "'%s'";
    $params[] = $revision;
  }
  $and_constraints[] = $tables['versioncontrol_item_revisions']['alias'] .'.revision IN ('. implode(',', $placeholders) .')';

  // Exact search for target items, no fuzzy source item path results.
  $params[] = VERSIONCONTROL_OPERATION_MEMBER_ITEM;
  $and_constraints[] = $tables['versioncontrol_operation_items']['alias'] .'.type = %d';
}

/**
 * Filter operations by item paths of associated items.
 */
function versioncontrol_operation_constraint_paths($constraint, &$tables, &$and_constraints, &$params) {
  $or_constraints = array();

  foreach ($constraint as $path) {
    $current_path = $path;
    $placeholders = array();

    // Both the given path and all its parent directories are included in the query.
    while (TRUE) {
      $placeholders[] = "'%s'";
      $params[] = $current_path;

      if ($current_path == dirname($current_path)) {
        break; // we reached the root directory, '/'
      }
      $current_path = dirname($current_path);
    }
    $or_constraints[] = $tables['versioncontrol_item_revisions']['alias'] .'.path IN ('. implode(',', $placeholders) .')';

    // Also include any children paths of the given one
    // (will only yield results for directory paths).
    $or_constraints[] = $tables['versioncontrol_item_revisions']['alias'] .".path LIKE '%s'";
    $params[] = $path . (($path[strlen($path)-1] == '/') ? '%' : '/%');
  }
  $and_constraints[] = '('. implode(' OR ', $or_constraints) .')';
}

/**
 * Filter operations by associated label names (both branches and tags).
 */
function versioncontrol_operation_constraint_labels($constraint, &$tables, &$and_constraints, &$params) {
  $or_constraints = array();
  foreach ($constraint as $label_name) {
    $or_constraints[] = $tables['versioncontrol_labels']['alias'] .".name = '%s'";
    $params[] = $label_name;
  }
  $and_constraints[] = '('. implode(' OR ', $or_constraints) .')';
}

/**
 * Filter operations by associated tag names.
 */
function versioncontrol_operation_constraint_tags($constraint, &$tables, &$and_constraints, &$params) {
  $or_constraints = array();
  foreach ($constraint as $label_name) {
    $or_constraints[] = $tables['versioncontrol_labels']['alias'] .".name = '%s'";
    $params[] = $label_name;
  }
  $and_constraints[] = '(('. implode(' OR ', $or_constraints) .') AND '.
    $tables['versioncontrol_labels']['alias'] .'.type = %d)';
  $params[] = VERSIONCONTROL_OPERATION_TAG;
}

/**
 * Filter operations by associated branch names.
 * (Applies to both branch operations and commits).
 */
function versioncontrol_operation_constraint_branches($constraint, &$tables, &$and_constraints, &$params) {
  $or_constraints = array();
  foreach ($constraint as $label_name) {
    $or_constraints[] = $tables['versioncontrol_labels']['alias'] .".name = '%s'";
    $params[] = $label_name;
  }
  $and_constraints[] = '(('. implode(' OR ', $or_constraints) .') AND '.
    $tables['versioncontrol_labels']['alias'] .'.type = %d)';
  $params[] = VERSIONCONTROL_OPERATION_BRANCH;
}

/**
 * Filter operations by their operation type. As noted in the API documentation
 * for versioncontrol_get_operations(), this filter is kinda smart and also
 * includes commits for version control systems like Subversion when a branch
 * or tag is affected by that commit.
 */
function versioncontrol_operation_constraint_types($constraint, &$tables, &$and_constraints, &$params) {
  $or_constraints = array();

  if (in_array(VERSIONCONTROL_OPERATION_COMMIT, $constraint)) {
    $or_constraints[] = $tables['versioncontrol_operations']['alias'] .'.type = %d';
    $params[] = VERSIONCONTROL_OPERATION_COMMIT;
  }
  if (in_array(VERSIONCONTROL_OPERATION_BRANCH, $constraint)) {
    versioncontrol_table_labels_join($tables);
    $or_constraints[] = '('.
      $tables['versioncontrol_labels']['alias'] .'.type = %d AND '.
      $tables['versioncontrol_operation_labels']['alias'] .'.action <> %d
    )';
    $params[] = VERSIONCONTROL_LABEL_BRANCH; // label.type
    // oplabel.action is != normal commits, we don't want those:
    $params[] = VERSIONCONTROL_ACTION_MODIFIED;
  }
  if (in_array(VERSIONCONTROL_OPERATION_TAG, $constraint)) {
    versioncontrol_table_labels_join($tables);
    $or_constraints[] = '('.
      $tables['versioncontrol_labels']['alias'] .'.type = %d AND '.
      $tables['versioncontrol_operation_labels']['alias'] .'.action <> %d
    )';
    $params[] = VERSIONCONTROL_OPERATION_TAG; // label.type
    // oplabel.action is != normal commits, we don't want those:
    $params[] = VERSIONCONTROL_ACTION_MODIFIED;
  }
  $and_constraints[] = '('. implode(' OR ', $or_constraints) .')';
}

/**
 * Take an existing @p $tables array and add the table join for
 * {versioncontrol_repositories}. Only meant to be used within a
 * constraint construction callback.
 */
function versioncontrol_table_repositories_join(&$tables) {
  if (!isset($tables['versioncontrol_repositories'])) {
    $tables['versioncontrol_repositories'] = array(
      'alias' => 'r',
      'join_on' => 'op.repo_id = r.repo_id',
    );
  }
}

/**
 * Take an existing @p $tables array and add the table join for {users} on
 * {versioncontrol_operations}.uid. Only meant to be used within a
 * constraint construction callback.
 */
function versioncontrol_table_users_join(&$tables) {
  if (!isset($tables['users'])) {
    $tables['users'] = array(
      'alias' => 'user',
      'join_on' => 'op.uid = user.uid',
    );
  }
}

/**
 * Take an existing @p $tables array and add the table joins for
 * {versioncontrol_operation_labels} and {versioncontrol_labels}.
 * Only meant to be used within a constraint construction callback.
 */
function versioncontrol_table_labels_join(&$tables) {
  if (!isset($tables['versioncontrol_operation_labels'])) {
    $tables['versioncontrol_operation_labels'] = array(
      'alias' => 'oplabel',
      'join_on' => $tables['versioncontrol_operations']['alias'] .'.vc_op_id = oplabel.vc_op_id',
    );
    $tables['versioncontrol_labels'] = array(
      'alias' => 'label',
      'join_on' => 'oplabel.label_id = label.label_id',
    );
  }
}

/**
 * Take an existing @p $tables array and add the table join for
 * {versioncontrol_operation_items}.
 * Only meant to be used within a constraint construction callback.
 */
function versioncontrol_table_operation_items_join(&$tables) {
  if (!isset($tables['versioncontrol_operation_items'])) {
    $tables['versioncontrol_operation_items'] = array(
      'alias' => 'opitem',
      'join_on' => $tables['versioncontrol_operations']['alias'] .'.vc_op_id = opitem.vc_op_id',
    );
  }
}

/**
 * Take an existing @p $tables array and add the table joins for
 * {versioncontrol_operation_labels} and {versioncontrol_labels}.
 * Only meant to be used within a constraint construction callback.
 */
function versioncontrol_table_item_revisions_join(&$tables) {
  if (!isset($tables['versioncontrol_item_revisions'])) {
    versioncontrol_table_operation_items_join($tables);

    $tables['versioncontrol_item_revisions'] = array(
      'alias' => 'ir',
      'join_on' => 'opitem.item_revision_id = ir.item_revision_id',
    );
  }
}

/**
 * Return a subset of the given operations according to the
 * $page and $limit values.
 */
function _versioncontrol_page_operations($operations, $page, $limit) {
  $i = 0;
  $paged_operations = array();
  foreach ($operations as $operation) {
    if ($i >= ($page * $limit) && $i < (($page+1) * $limit)) {
      $paged_operations[] = $operation;
    }
    ++$i;
  }
  return $paged_operations;
}


/**
 * Retrieve additional information about the origin of a given set of items.
 *
 * @param $repository
 *   The repository that the items are located in.
 * @param $items
 *   An array of item arrays, for example as returned by
 *   VersioncontrolOperation::getItems().
 *
 * @return
 *   This function does not have a return value; instead, it alters the
 *   given item arrays and adds additional information about their origin.
 *   The following elements will be set for all items whose source items
 *   could be retrieved.
 *
 *   - 'action': Specifies how the item was changed.
 *        One of the predefined VERSIONCONTROL_ACTION_* values.
 *   - 'source_items': An array with the previous revision(s) of the affected
 *        item. Empty if 'action' is VERSIONCONTROL_ACTION_ADDED. The key for
 *        all items in this array is the respective item path.
 *   - 'replaced_item': The previous but technically unrelated item at the
 *        same location as the current item. Only exists if this previous item
 *        was deleted and replaced by a different one that was just moved
 *        or copied to this location.
 *   - 'line_changes': Only exists if line changes have been recorded for this
 *        action - if so, this is an array containing the number of added lines
 *        in an element with key 'added', and the number of removed lines in
 *        the 'removed' key.
 */
function versioncontrol_fetch_source_items($repository, &$items) {
  if (empty($items)) {
    return;
  }
  $placeholders = array();
  $ids = array();
  $item_keys = array();

  foreach ($items as $key => $item) {
    // If we don't yet know the item_revision_id (required for db queries), try
    // to retrieve it. If we don't find it, we can't fetch this item's sources.
    if ($item->fetchItemRevisionId()) {
      $placeholders[] = '%d';
      $ids[] = $item->item_revision_id;
      $item_keys[$item->item_revision_id] = $key;
    }
  }
  if (empty($ids)) {
    return;
  }

  $result = db_query(
    'SELECT sit.item_revision_id, sit.source_item_revision_id, sit.action,
            sit.line_changes_recorded, sit.line_changes_added,
            sit.line_changes_removed, ir.path, ir.revision, ir.type
     FROM {versioncontrol_source_items} sit
      LEFT JOIN {versioncontrol_item_revisions} ir
       ON sit.source_item_revision_id = ir.item_revision_id
     WHERE sit.item_revision_id IN ('. implode(',', $placeholders) .')', $ids);

  while ($item_revision = db_fetch_object($result)) {
    $successor_key = $item_keys[$item_revision->item_revision_id];
    if (!isset($items[$successor_key]->source_items)) {
      $items[$successor_key]->source_items = array();
    }

    $item = new $repository->backend->classes['item'](
      $item_revision->type,
      $item_revision->path,
      $item_revision->revision,
      NULL,
      $repository
    );
    $item->selected_label = new stdClass();
    $item->selected_label->get_from = 'other_item';
    $item->selected_label->other_item = &$items[$successor_key];
    $item->selected_label->other_item_tags = array('successor_item');

    // Insert the item and its associated action into the successor item.
    if ($item_revision->action == VERSIONCONTROL_ACTION_REPLACED) {
      $items[$successor_key]->replaced_item = $item;
    }
    elseif ($item_revision->action == VERSIONCONTROL_ACTION_ADDED) {
      $items[$successor_key]['action'] = $item_revision->action;
      // Added items only join to an empty (NULL) item, ignore that one
      // instead of adding it to the source items.
    }
    else {
      $items[$successor_key]->action = $item_revision->action;
      $items[$successor_key]->source_items[$item->path] = $item;
    }

    // Add the lines-changed information if it has been recorded.
    // Only a single source item entry should hold this information,
    // so no emphasis is placed on merging it across multiple source items.
    if ($item_revision->line_changes_recorded) {
      $items[$successor_key]->line_changes = array(
        'added' => $item_revision->line_changes_added,
        'removed' => $item_revision->line_changes_removed,
      );
    }
  }
}

/**
 * Retrieve additional information about the successors of a given set
 * of items.
 *
 * @param $repository
 *   The repository that the items are located in.
 * @param $items
 *   An array of item arrays, for example as returned by
 *   VersioncontrolOperation::getItems().
 *
 * @return
 *   This function does not have a return value; instead, it alters the
 *   given item arrays and adds additional information about their successors.
 *   The following elements will be set for all items whose successor items
 *   could be retrieved.
 *
 *   - 'successor_items': An array with the previous revision(s) of the
 *        affected item. The key for all items in this array is the respective
 *        item path, and all of these items will have the 'actions' and
 *        'source_items' properties (as documented by
 *        versioncontrol_fetch_source_items()) filled in.
 *   - 'replaced_by_item': The succeeding but technically unrelated item at the
 *        same location as the current item. Only exists if the original item
 *        was deleted and replaced by a the succeeding one that was just moved
 *        or copied to this location.
 */
function versioncontrol_fetch_successor_items($repository, &$items) {
  if (empty($items)) {
    return;
  }
  $placeholders = array();
  $ids = array();
  $item_keys = array();

  foreach ($items as $key => $item) {
    // If we don't yet know the item_revision_id (required for db queries), try
    // to retrieve it. If we don't find it, we can't fetch this item's sources.
    if ($item->fetchItemRevisionId()) {
      $placeholders[] = '%d';
      $ids[] = $item->item_revision_id;
      $item_keys[$item->item_revision_id] = $key;
    }
  }

  $result = db_query(
    'SELECT sit.item_revision_id, sit.source_item_revision_id, sit.action,
            ir.path, ir.revision, ir.type
     FROM {versioncontrol_source_items} sit
      INNER JOIN {versioncontrol_item_revisions} ir
       ON sit.item_revision_id = ir.item_revision_id
     WHERE sit.source_item_revision_id IN ('. implode(',', $placeholders) .')', $ids);

  while ($item_revision = db_fetch_object($result)) {
    $source_key = $item_keys[$item_revision->source_item_revision_id];
    if (!isset($items[$source_key]['successor_items'])) {
      $items[$source_key]['successor_items'] = array();
    }

    $item = array(
      'path' => $item_revision->path,
      'revision' => $item_revision->revision,
      'type' => $item_revision->type,
      'item_revision_id' => $item_revision->item_revision_id,
    );
    $item['selected_label'] = new stdClass();
    $item['selected_label']->get_from = 'other_item';
    $item['selected_label']->other_item = &$items[$source_key];
    $item['selected_label']->other_item_tags = array('source_item');

    // Insert the item and its associated action into the source item.
    if ($item_revision->action == VERSIONCONTROL_ACTION_REPLACED) {
      $items[$source_key]['replaced_by_item'] = $item;
    }
    else {
      if ($item_revision->action == VERSIONCONTROL_ACTION_MERGED) {
        // If we've got a merge action then there are multiple source items,
        // the one that we know is not sufficient. (And of course, we won't
        // return an item with an incomplete 'source_items' property.)
        // So let's retrieve all of those source items.
        $successor_items = array($item['path'] => $item);
        versioncontrol_fetch_source_items($repository, $successor_items);
        $item = $successor_items[$item['path']];
      }
      else { // No "merged" action: the original item is the only source item.
        $item['action'] = $item_revision->action;
        $item['source_items'] = array(
          $items[$source_key]['path'] => $items[$source_key],
        );
      }
      $items[$source_key]['successor_items'][$item['path']] = $item;
    }
  }
}

/**
 * Retrieve the commit operation corresponding to each item in a list of items.
 *
 * @param $repository
 *   The repository that the items are located in.
 * @param $items
 *   An array of item arrays, for example as returned by
 *   VersioncontrolOperation::getItems().
 *
 * @return
 *   This function does not have a return value; instead, it alters the
 *   given item arrays and adds additional information about their
 *   corresponding commit operation in an 'commit_operation' property.
 *   If no corresponding commit was found, this property will not be set.
 */
function versioncontrol_fetch_item_commit_operations($repository, &$items) {
  $placeholders = array();
  $ids = array();
  $item_keys = array();

  $fetch_by_revision_id = FALSE;

  // If there are atomic commits and versioned directories (= SVN), we'll miss
  // out on operations for directory items if those are not (always) captured
  // in the {versioncontrol_operation_items} table.
  // So fetch by revision id instead in that case.
  if (in_array(VERSIONCONTROL_CAPABILITY_ATOMIC_COMMITS, $repository->backend->capabilities)) {
    $fetch_by_revision_id = TRUE;
  }

  foreach ($items as $key => $item) {
    if (!empty($item['commit_operation'])) {
      continue; // No need to insert an operation if it's already there.
    }
    if ($fetch_by_revision_id && !empty($item['revision'])) {
      $ids[$item['revision']] = TRUE; // automatic duplicate elimination
    }
    // If we don't yet know the item_revision_id (required for db queries), try
    // to retrieve it. If we don't find it, we can't fetch this item's sources.
    if ($item->fetchItemRevisionId()) {
      $placeholders[] = '%d';
      $ids[] = $item->item_revision_id;
      $item_keys[$item->item_revision_id] = $key;
    }
  }
  if (empty($ids)) {
    return;
  }

  if ($fetch_by_revision_id) {
    $commit_operations = VersioncontrolOperationCache::getInstance()->getCommits(array(
      'repo_ids' => array($repository['repo_id']),
      'revisions' => array_keys($ids),
    ));
    // Associate the commit operations to the items.
    foreach ($items as $key => $item) {
      foreach ($commit_operations as $commit_operation) {
        if ($item['revision'] == $commit_operation['revision']) {
          $items[$key]['commit_operation'] = $commit_operation;
        }
      }
    }
  }
  else { // fetch by operation/item association
    $result = db_query(
      'SELECT item_revision_id, vc_op_id
      FROM {versioncontrol_operation_items}
    WHERE item_revision_id IN ('. implode(',', $placeholders) .')', $ids);

    $operation_item_mapping = array();
    while ($opitem = db_fetch_object($result)) {
      $operation_item_mapping[$opitem->vc_op_id][] = $opitem->item_revision_id;
    }
    $commit_operations = VersioncontrolOperationCache::getInstance()->getCommits(array(
      'vc_op_ids' => array_keys($operation_item_mapping),
    ));

    // Associate the commit operations to the items.
    foreach ($commit_operations as $commit_operation) {
      $item_revision_ids = $operation_item_mapping[$commit_operation['vc_op_id']];
