phorge / src / applications / search / engine / PhabricatorApplicationSearchEngine.php

<?php

/**
 * Represents an abstract search engine for an application. It supports
 * creating and storing saved queries.
 *
 * @task construct  Constructing Engines
 * @task app        Applications
 * @task builtin    Builtin Queries
 * @task uri        Query URIs
 * @task dates      Date Filters
 * @task order      Result Ordering
 * @task read       Reading Utilities
 * @task exec       Paging and Executing Queries
 * @task render     Rendering Results
 * @task custom     Custom Fields
 */
abstract class PhabricatorApplicationSearchEngine extends Phobject {

  private $application;
  private $viewer;
  private $errors = array();
  private $request;
  private $context;
  private $controller;
  private $namedQueries;
  private $navigationItems = array();

  const CONTEXT_LIST  = 'list';
  const CONTEXT_PANEL = 'panel';

  const BUCKET_NONE = 'none';

  public function setController(PhabricatorController $controller) {
    $this->controller = $controller;
    return $this;
  }

  /**
   * @return PhabricatorController
   */
  public function getController() {
    return $this->controller;
  }

  public function buildResponse() {
    $controller = $this->getController();
    $request = $controller->getRequest();

    $search = id(new PhabricatorApplicationSearchController())
      ->setQueryKey($request->getURIData('queryKey'))
      ->setSearchEngine($this);

    return $controller->delegateToController($search);
  }

  /**
   * @return object|null Matching object (e.g. PhabricatorUser, PhamePost, or
   *   PhabricatorDashboardPanel), or null if no object matches.
   */
  public function newResultObject() {
    // We may be able to get this automatically if newQuery() is implemented.
    $query = $this->newQuery();
    if ($query) {
      $object = $query->newResultObject();
      if ($object) {
        return $object;
      }
    }

    return null;
  }

  public function newQuery() {
    return null;
  }

  public function setViewer(PhabricatorUser $viewer) {
    $this->viewer = $viewer;
    return $this;
  }

  /**
   * @return PhabricatorUser
   * @throws PhutilInvalidStateException
   */
  protected function requireViewer() {
    if (!$this->viewer) {
      throw new PhutilInvalidStateException('setViewer');
    }
    return $this->viewer;
  }

  /**
   * Set rendering context (e.g. list or panel)
   *
   * @param $context string A CONTEXT_* constant
   */
  public function setContext($context) {
    $this->context = $context;
    return $this;
  }

  /**
   * Whether this is in the context of rendering a panel
   *
   * @return bool True if in panel context
   */
  public function isPanelContext() {
    return ($this->context == self::CONTEXT_PANEL);
  }

  /**
   * @param array<PHUIListItemView> $navigation_items
   */
  public function setNavigationItems(array $navigation_items) {
    assert_instances_of($navigation_items, PHUIListItemView::class);
    $this->navigationItems = $navigation_items;
    return $this;
  }

  /**
   * @return array<PHUIListItemView> $navigation_items
   */
  public function getNavigationItems() {
    return $this->navigationItems;
  }

  public function canUseInPanelContext() {
    return true;
  }

  public function saveQuery(PhabricatorSavedQuery $query) {
    if ($query->getID()) {
      throw new Exception(
        pht(
          'Query (with ID "%s") has already been saved. Queries are '.
          'immutable once saved.',
          $query->getID()));
    }

    $query->setEngineClassName(get_class($this));

    $unguarded = AphrontWriteGuard::beginScopedUnguardedWrites();
    try {
      $query->save();
    } catch (AphrontDuplicateKeyQueryException $ex) {
      // Ignore, this is just a repeated search.
    }
    unset($unguarded);
  }

  /**
   * Create a saved query object from the request.
   *
   * @param AphrontRequest $request The search request.
   * @return PhabricatorSavedQuery
   */
  public function buildSavedQueryFromRequest(AphrontRequest $request) {
    $fields = $this->buildSearchFields();
    $viewer = $this->requireViewer();

    $saved = new PhabricatorSavedQuery();
    foreach ($fields as $field) {
      $field->setViewer($viewer);

      $value = $field->readValueFromRequest($request);
      $saved->setParameter($field->getKey(), $value);
    }

    return $saved;
  }

  /**
   * Executes the saved query.
   *
   * @param PhabricatorSavedQuery $original The saved query to operate on.
   * @return PhabricatorQuery The result of the query.
   */
  public function buildQueryFromSavedQuery(PhabricatorSavedQuery $original) {
    $saved = clone $original;
    $this->willUseSavedQuery($saved);

    $fields = $this->buildSearchFields();
    $viewer = $this->requireViewer();

    $map = array();
    foreach ($fields as $field) {
      $field->setViewer($viewer);
      $field->readValueFromSavedQuery($saved);
      $value = $field->getValueForQuery($field->getValue());
      $map[$field->getKey()] = $value;
    }

    $original->attachParameterMap($map);
    $query = $this->buildQueryFromParameters($map);

    $object = $this->newResultObject();
    if (!$object) {
      return $query;
    }

    $extensions = $this->getEngineExtensions();
    foreach ($extensions as $extension) {
      $extension->applyConstraintsToQuery($object, $query, $saved, $map);
    }

    $order = $saved->getParameter('order');
    $builtin = $query->getBuiltinOrderAliasMap();
    if (phutil_nonempty_string($order) && isset($builtin[$order])) {
      $query->setOrder($order);
    } else {
      // If the order is invalid or not available, we choose the first
      // builtin order. This isn't always the default order for the query,
      // but is the first value in the "Order" dropdown, and makes the query
      // behavior more consistent with the UI. In queries where the two
      // orders differ, this order is the preferred order for humans.
      $query->setOrder(head_key($builtin));
    }

    return $query;
  }

  /**
   * Hook for subclasses to adjust saved queries prior to use.
   *
   * If an application changes how queries are saved, it can implement this
   * hook to keep old queries working the way users expect, by reading,
   * adjusting, and overwriting parameters.
   *
   * @param PhabricatorSavedQuery $saved Saved query which will be executed.
   * @return void
   */
  protected function willUseSavedQuery(PhabricatorSavedQuery $saved) {
    return;
  }

  protected function buildQueryFromParameters(array $parameters) {
    throw new PhutilMethodNotImplementedException();
  }

  /**
   * Builds the search form using the request.
   *
   * @param AphrontFormView       $form  Form to populate.
   * @param PhabricatorSavedQuery $saved Query from which to build the form.
   * @return void
   */
  public function buildSearchForm(
    AphrontFormView $form,
    PhabricatorSavedQuery $saved) {

    $saved = clone $saved;
    $this->willUseSavedQuery($saved);

    $fields = $this->buildSearchFields();
    $fields = $this->adjustFieldsForDisplay($fields);
    $viewer = $this->requireViewer();

    foreach ($fields as $field) {
      $field->setViewer($viewer);
      $field->readValueFromSavedQuery($saved);
    }

    foreach ($fields as $field) {
      foreach ($field->getErrors() as $error) {
        $this->addError(last($error));
      }
    }

    foreach ($fields as $field) {
      $field->appendToForm($form);
    }
  }

  protected function buildSearchFields() {
    $fields = array();

    foreach ($this->buildCustomSearchFields() as $field) {
      $fields[] = $field;
    }

    $object = $this->newResultObject();
    if ($object) {
      $extensions = $this->getEngineExtensions();
      foreach ($extensions as $extension) {
        $extension_fields = $extension->getSearchFields($object);
        foreach ($extension_fields as $extension_field) {
          $fields[] = $extension_field;
        }
      }
    }

    $query = $this->newQuery();
    if ($query && $this->shouldShowOrderField()) {
      $orders = $query->getBuiltinOrders();
      $orders = ipull($orders, 'name');

      $fields[] = id(new PhabricatorSearchOrderField())
        ->setLabel(pht('Order By'))
        ->setKey('order')
        ->setOrderAliases($query->getBuiltinOrderAliasMap())
        ->setOptions($orders);
    }

    if (id(new PhabricatorAuditApplication())->isInstalled()) {
      $buckets = $this->newResultBuckets();
      if ($query && $buckets) {
        $bucket_options = array(
          self::BUCKET_NONE => pht('No Bucketing'),
        ) + mpull($buckets, 'getResultBucketName');

        $fields[] = id(new PhabricatorSearchSelectField())
          ->setLabel(pht('Bucket'))
          ->setKey('bucket')
          ->setOptions($bucket_options);
      }
    }

    $field_map = array();
    foreach ($fields as $field) {
      $key = $field->getKey();
      if (isset($field_map[$key])) {
        throw new Exception(
          pht(
            'Two fields in this SearchEngine use the same key ("%s"), but '.
            'each field must use a unique key.',
            $key));
      }
      $field_map[$key] = $field;
    }

    return $field_map;
  }

  protected function shouldShowOrderField() {
    return true;
  }

  private function adjustFieldsForDisplay(array $field_map) {
    $order = $this->getDefaultFieldOrder();

    $head_keys = array();
    $tail_keys = array();
    $seen_tail = false;
    foreach ($order as $order_key) {
      if ($order_key === '...') {
        $seen_tail = true;
        continue;
      }

      if (!$seen_tail) {
        $head_keys[] = $order_key;
      } else {
        $tail_keys[] = $order_key;
      }
    }

    $head = array_select_keys($field_map, $head_keys);
    $body = array_diff_key($field_map, array_fuse($tail_keys));
    $tail = array_select_keys($field_map, $tail_keys);

    $result = $head + $body + $tail;

    // Force the fulltext "query" field to the top unconditionally.
    $result = array_select_keys($result, array('query')) + $result;

    foreach ($this->getHiddenFields() as $hidden_key) {
      unset($result[$hidden_key]);
    }

    return $result;
  }

  protected function buildCustomSearchFields() {
    throw new PhutilMethodNotImplementedException();
  }


  /**
   * Define the default display order for fields by returning a list of
   * field keys.
   *
   * You can use the special key `...` to mean "all unspecified fields go
   * here". This lets you easily put important fields at the top of the form,
   * standard fields in the middle of the form, and less important fields at
   * the bottom.
   *
   * For example, you might return a list like this:
   *
   *   return array(
   *     'authorPHIDs',
   *     'reviewerPHIDs',
   *     '...',
   *     'createdAfter',
   *     'createdBefore',
   *   );
   *
   * Any unspecified fields (including custom fields and fields added
   * automatically by infrastructure) will be put in the middle.
   *
   * @return list<string> Default ordering for field keys.
   */
  protected function getDefaultFieldOrder() {
    return array();
  }

  /**
   * Return a list of field keys which should be hidden from the viewer.
   *
   * @return list<string> Fields to hide.
   */
  protected function getHiddenFields() {
    return array();
  }

  /**
   * @return array<string>
   */
  public function getErrors() {
    return $this->errors;
  }

  /**
   * @param string $error
   */
  public function addError($error) {
    $this->errors[] = $error;
    return $this;
  }

  /**
   * Return an application URI corresponding to the results page of a query.
   * Normally, this is something like `/application/query/QUERYKEY/`.
   *
   * @param   string  $query_key The query key to build a URI for.
   * @return  string  URI where the query can be executed.
   * @task uri
   */
  public function getQueryResultsPageURI($query_key) {
    return $this->getURI('query/'.$query_key.'/');
  }


  /**
   * Return an application URI for query management. This is used when, e.g.,
   * a query deletion operation is cancelled.
   *
   * @return  string  URI where queries can be managed.
   * @task uri
   */
  public function getQueryManagementURI() {
    return $this->getURI('query/edit/');
  }

  public function getQueryBaseURI() {
    return $this->getURI('');
  }

  public function getExportURI($query_key) {
    return $this->getURI('query/'.$query_key.'/export/');
  }

  public function getCustomizeURI($query_key, $object_phid, $context_phid) {
    $params = array(
      'search.objectPHID' => $object_phid,
      'search.contextPHID' => $context_phid,
    );

    $uri = $this->getURI('query/'.$query_key.'/customize/');
    $uri = new PhutilURI($uri, $params);

    return phutil_string_cast($uri);
  }



  /**
   * Return the URI to a path within the application. Used to construct default
   * URIs for management and results.
   *
   * @return string URI to path; empty string if not implemented or applicable.
   * @task uri
   */
  abstract protected function getURI($path);


  /**
   * Return a human readable description of the type of objects this query
   * searches for.
   *
   * For example, "Tasks" or "Commits".
   *
   * @return string Human-readable description of what this engine is used to
   *   find.
   */
  abstract public function getResultTypeDescription();


  /**
   * @return PhabricatorSavedQuery New instance of PhabricatorSavedQuery
   */
  public function newSavedQuery() {
    return id(new PhabricatorSavedQuery())
      ->setEngineClassName(get_class($this));
  }

  public function addNavigationItems(PHUIListView $menu) {
    $viewer = $this->requireViewer();

    $current_app = $this->getApplication()->getName();
    $search_app = id(new PhabricatorSearchApplication())->getName();

    if ($current_app === $search_app) {
      $menu->newLabel(pht('Global Queries'));
    } else {
      $menu->newLabel(pht('%s Queries', $current_app));
    }

    $named_queries = $this->loadEnabledNamedQueries();

    foreach ($named_queries as $query) {
      $key = $query->getQueryKey();
      $uri = $this->getQueryResultsPageURI($key);
      $menu->newLink($query->getQueryName(), $uri, 'query/'.$key);
    }

    if ($viewer->isLoggedIn()) {
      $manage_uri = $this->getQueryManagementURI();
      $menu->newLink(pht('Edit Queries...'), $manage_uri, 'query/edit');
    }

    $menu->newLabel(pht('Search'));
    $advanced_uri = $this->getQueryResultsPageURI('advanced');
    if ($current_app === $search_app) {
      $menu->newLink(pht('Global Search'), $advanced_uri, 'query/advanced');
    } else {
      $menu->newLink(
        pht('%s Search', $current_app),
        $advanced_uri,
        'query/advanced');
    }

    foreach ($this->navigationItems as $extra_item) {
      $menu->addMenuItem($extra_item);
    }

    return $this;
  }

  /**
   * @return array<string,PhabricatorNamedQuery> Array with pairs of the query
   * name (e.g. 'all' or 'open') and the corresponding PhabricatorNamedQuery
   */
  public function loadAllNamedQueries() {
    $viewer = $this->requireViewer();
    $builtin = $this->getBuiltinQueries();

    if ($this->namedQueries === null) {
      $named_queries = id(new PhabricatorNamedQueryQuery())
        ->setViewer($viewer)
        ->withEngineClassNames(array(get_class($this)))
        ->withUserPHIDs(
          array(
            $viewer->getPHID(),
            PhabricatorNamedQuery::SCOPE_GLOBAL,
          ))
        ->execute();
      $named_queries = mpull($named_queries, null, 'getQueryKey');

      $builtin = mpull($builtin, null, 'getQueryKey');

      foreach ($named_queries as $key => $named_query) {
        if ($named_query->getIsBuiltin()) {
          if (isset($builtin[$key])) {
            $named_queries[$key]->setQueryName($builtin[$key]->getQueryName());
            unset($builtin[$key]);
          } else {
            unset($named_queries[$key]);
          }
        }

        unset($builtin[$key]);
      }

      $named_queries = msortv($named_queries, 'getNamedQuerySortVector');
      $this->namedQueries = $named_queries;
    }

    return $this->namedQueries + $builtin;
  }

  /**
   * @return array<string,PhabricatorNamedQuery> Array with pairs of the query
   * name (e.g. 'all' or 'open') and the corresponding PhabricatorNamedQuery
   */
  public function loadEnabledNamedQueries() {
    $named_queries = $this->loadAllNamedQueries();
    foreach ($named_queries as $key => $named_query) {
      if ($named_query->getIsBuiltin() && $named_query->getIsDisabled()) {
        unset($named_queries[$key]);
      }
    }
    return $named_queries;
  }

  /**
   * @return string Name of the default query (e.g. 'all' or 'open') when not
   * passing a query key, e.g. by going to generic /search/ or /maniphest/
   */
  public function getDefaultQueryKey() {
    $viewer = $this->requireViewer();

    $configs = id(new PhabricatorNamedQueryConfigQuery())
      ->setViewer($viewer)
      ->withEngineClassNames(array(get_class($this)))
      ->withScopePHIDs(
        array(
          $viewer->getPHID(),
          PhabricatorNamedQueryConfig::SCOPE_GLOBAL,
        ))
      ->execute();
    $configs = msortv($configs, 'getStrengthSortVector');

    $key_pinned = PhabricatorNamedQueryConfig::PROPERTY_PINNED;
    $map = $this->loadEnabledNamedQueries();
    foreach ($configs as $config) {
      $pinned = $config->getConfigProperty($key_pinned);
      if (!isset($map[$pinned])) {
        continue;
      }

      return $pinned;
    }

    return head_key($map);
  }

  protected function setQueryProjects(
    PhabricatorCursorPagedPolicyAwareQuery $query,
    PhabricatorSavedQuery $saved) {

    $datasource = id(new PhabricatorProjectLogicalDatasource())
      ->setViewer($this->requireViewer());

    $projects = $saved->getParameter('projects', array());
    $constraints = $datasource->evaluateTokens($projects);

    if ($constraints) {
      $query->withEdgeLogicConstraints(
        PhabricatorProjectObjectHasProjectEdgeType::EDGECONST,
        $constraints);
    }

    return $this;
  }


/* -(  Applications  )------------------------------------------------------- */


  protected function getApplicationURI($path = '') {
    return $this->getApplication()->getApplicationURI($path);
  }

  /**
   * @return PhabricatorApplication A PhabricatorApplication subclass
   */
  protected function getApplication() {
    if (!$this->application) {
      $class = $this->getApplicationClassName();

      $this->application = id(new PhabricatorApplicationQuery())
        ->setViewer($this->requireViewer())
        ->withClasses(array($class))
        ->withInstalled(true)
        ->executeOne();

      if (!$this->application) {
        throw new Exception(
          pht(
            'Application "%s" is not enabled!',
            $class));
      }
    }

    return $this->application;
  }

  abstract public function getApplicationClassName();


/* -(  Constructing Engines  )----------------------------------------------- */


  /**
   * Load all available application search engines.
   *
   * @return list<PhabricatorApplicationSearchEngine> All available engines.
   * @task construct
   */
  public static function getAllEngines() {
    return id(new PhutilClassMapQuery())
      ->setAncestorClass(self::class)
      ->execute();
  }


  /**
   * Get an engine by class name, if it exists.
   *
   * @return PhabricatorApplicationSearchEngine|null Engine, or null if it does
   *   not exist.
   * @task construct
   */
  public static function getEngineByClassName($class_name) {
    return idx(self::getAllEngines(), $class_name);
  }


/* -(  Builtin Queries  )---------------------------------------------------- */


  /**
   * @return array<string,PhabricatorNamedQuery> Array with pairs of the query
   * name (e.g. 'all' or 'open') and the corresponding PhabricatorNamedQuery
   *
   * @task builtin
   */
  public function getBuiltinQueries() {
    $names = $this->getBuiltinQueryNames();

    $queries = array();
    $sequence = 0;
    foreach ($names as $key => $name) {
      $queries[$key] = id(new PhabricatorNamedQuery())
        ->setUserPHID(PhabricatorNamedQuery::SCOPE_GLOBAL)
        ->setEngineClassName(get_class($this))
        ->setQueryName($name)
        ->setQueryKey($key)
        ->setSequence((1 << 24) + $sequence++)
        ->setIsBuiltin(true);
    }

    return $queries;
  }


  /**
   * @task builtin
   */
  public function getBuiltinQuery($query_key) {
    if (!$this->isBuiltinQuery($query_key)) {
      throw new Exception(pht("'%s' is not a builtin!", $query_key));
    }
    return idx($this->getBuiltinQueries(), $query_key);
  }


  /**
   * @task builtin
   */
  protected function getBuiltinQueryNames() {
    return array();
  }


  /**
   * @task builtin
   */
  public function isBuiltinQuery($query_key) {
    $builtins = $this->getBuiltinQueries();
    return isset($builtins[$query_key]);
  }


  /**
   * @task builtin
   */
  public function buildSavedQueryFromBuiltin($query_key) {
    throw new Exception(pht("Builtin '%s' is not supported!", $query_key));
  }


/* -(  Reading Utilities )--------------------------------------------------- */


  /**
   * Read a list of user PHIDs from a request in a flexible way. This method
   * supports either of these forms:
   *
   *   users[]=alincoln&users[]=htaft
   *   users=alincoln,htaft
   *
   * Additionally, users can be specified either by PHID or by name.
   *
   * The main goal of this flexibility is to allow external programs to generate
   * links to pages (like "alincoln's open revisions") without needing to make
   * API calls.
   *
   * @param AphrontRequest  $request Request to read user PHIDs from.
   * @param string          $key Key to read in the request.
   * @param list<string>    $allow_types (optional) Other permitted PHID type
   *                        constants.
   * @return list<string>   List of user PHIDs and selector functions.
   * @task read
   */
  protected function readUsersFromRequest(
    AphrontRequest $request,
    $key,
    array $allow_types = array()) {

    $list = $this->readListFromRequest($request, $key);

    $phids = array();
    $names = array();
    $allow_types = array_fuse($allow_types);
    $user_type = PhabricatorPeopleUserPHIDType::TYPECONST;
    foreach ($list as $item) {
      $type = phid_get_type($item);
      if ($type == $user_type) {
        $phids[] = $item;
      } else if (isset($allow_types[$type])) {
        $phids[] = $item;
      } else {
        if (PhabricatorTypeaheadDatasource::isFunctionToken($item)) {
          // If this is a function, pass it through unchanged; we'll evaluate
          // it later.
          $phids[] = $item;
        } else {
          $names[] = $item;
        }
      }
    }

    if ($names) {
      $users = id(new PhabricatorPeopleQuery())
        ->setViewer($this->requireViewer())
        ->withUsernames($names)
        ->execute();
      foreach ($users as $user) {
        $phids[] = $user->getPHID();
      }
      $phids = array_unique($phids);
    }

    return $phids;
  }


  /**
   * Read a list of subscribers from a request in a flexible way.
   *
   * @param AphrontRequest  $request Request to read PHIDs from.
   * @param string          $key Key to read in the request.
   * @return list<string>   List of object PHIDs.
   * @task read
   */
  protected function readSubscribersFromRequest(
    AphrontRequest $request,
    $key) {
    return $this->readUsersFromRequest(
      $request,
      $key,
      array(
        PhabricatorProjectProjectPHIDType::TYPECONST,
      ));
  }


  /**
   * Read a list of generic PHIDs from a request in a flexible way. Like
   * @{method:readUsersFromRequest}, this method supports either array or
   * comma-delimited forms. Objects can be specified either by PHID or by
   * object name.
   *
   * @param AphrontRequest  $request Request to read PHIDs from.
   * @param string          $key Key to read in the request.
   * @param list<string>    $allow_types (optional) List of permitted PHID
   *                        type constants.
   * @return list<string>   List of object PHIDs.
   *
   * @task read
   */
  protected function readPHIDsFromRequest(
    AphrontRequest $request,
    $key,
    array $allow_types = array()) {

    $list = $this->readListFromRequest($request, $key);

    $objects = id(new PhabricatorObjectQuery())
      ->setViewer($this->requireViewer())
      ->withNames($list)
      ->execute();
    $list = mpull($objects, 'getPHID');

    if (!$list) {
      return array();
    }

    // If only certain PHID types are allowed, filter out all the others.
    if ($allow_types) {
      $allow_types = array_fuse($allow_types);
      foreach ($list as $key => $phid) {
        if (empty($allow_types[phid_get_type($phid)])) {
          unset($list[$key]);
        }
      }
    }

    return $list;
  }


  /**
   * Read a list of items from the request, in either array format or string
   * format:
   *
   *   list[]=item1&list[]=item2
   *   list=item1,item2
   *
   * This provides flexibility when constructing URIs, especially from external
   * sources.
   *
   * @param AphrontRequest  $request Request to read strings from.
   * @param string          $key Key to read in the request.
   * @return list<string>   List of values.
   */
  protected function readListFromRequest(
    AphrontRequest $request,
    $key) {
    $list = $request->getArr($key, null);
    if ($list === null) {
      $list = $request->getStrList($key);
    }

    if (!$list) {
      return array();
    }

    return $list;
  }

  protected function readBoolFromRequest(
    AphrontRequest $request,
    $key) {
    if (!phutil_nonempty_string($request->getStr($key))) {
      return null;
    }
    return $request->getBool($key);
  }


  protected function getBoolFromQuery(PhabricatorSavedQuery $query, $key) {
    $value = $query->getParameter($key);
    if ($value === null) {
      return $value;
    }
    return $value ? 'true' : 'false';
  }


/* -(  Dates  )-------------------------------------------------------------- */


  /**
   * @task dates
   */
  protected function parseDateTime($date_time) {
    if (!strlen($date_time)) {
      return null;
    }

    return PhabricatorTime::parseLocalTime($date_time, $this->requireViewer());
  }


  /**
   * @task dates
   * @return void
   */
  protected function buildDateRange(
    AphrontFormView $form,
    PhabricatorSavedQuery $saved_query,
    $start_key,
    $start_name,
    $end_key,
    $end_name) {

    $start_str = $saved_query->getParameter($start_key);
    $start = null;
    if (strlen($start_str)) {
      $start = $this->parseDateTime($start_str);
      if (!$start) {
        $this->addError(
          pht(
            '"%s" date can not be parsed.',
            $start_name));
      }
    }


    $end_str = $saved_query->getParameter($end_key);
    $end = null;
    if (strlen($end_str)) {
      $end = $this->parseDateTime($end_str);
      if (!$end) {
        $this->addError(
          pht(
            '"%s" date can not be parsed.',
            $end_name));
      }
    }

    if ($start && $end && ($start >= $end)) {
      $this->addError(
        pht(
          '"%s" must be a date before "%s".',
          $start_name,
          $end_name));
    }

    $form
      ->appendChild(
        id(new PHUIFormFreeformDateControl())
          ->setName($start_key)
          ->setLabel($start_name)
          ->setValue($start_str))
      ->appendChild(
        id(new AphrontFormTextControl())
          ->setName($end_key)
          ->setLabel($end_name)
          ->setValue($end_str));
  }


/* -(  Paging and Executing Queries  )--------------------------------------- */


  protected function newResultBuckets() {
    return array();
  }

  public function getResultBucket(PhabricatorSavedQuery $saved) {
    $key = $saved->getParameter('bucket');
    if ($key == self::BUCKET_NONE) {
      return null;
    }

    $buckets = $this->newResultBuckets();
    return idx($buckets, $key);
  }

  /**
   * @return int|float Number of results to display (float if set to infinity)
   */
  public function getPageSize(PhabricatorSavedQuery $saved) {
    $bucket = $this->getResultBucket($saved);

    $limit = (int)$saved->getParameter('limit');

    if ($limit > 0) {
      if ($bucket) {
        $bucket->setPageSize($limit);
      }
      return $limit;
    }

    if ($bucket) {
      return $bucket->getPageSize();
    }

    return 100;
  }


  public function shouldUseOffsetPaging() {
    return false;
  }

  /**
   * @return AphrontCursorPagerView|PHUIPagerView
   */
  public function newPagerForSavedQuery(PhabricatorSavedQuery $saved) {
    if ($this->shouldUseOffsetPaging()) {
      $pager = new PHUIPagerView();
    } else {
      $pager = new AphrontCursorPagerView();
    }

    $page_size = $this->getPageSize($saved);
    if (is_finite($page_size)) {
      $pager->setPageSize($page_size);
    } else {
      // Consider an INF pagesize to mean a large finite pagesize.

      // TODO: It would be nice to handle this more gracefully, but math
      // with INF seems to vary across PHP versions, systems, and runtimes.
      $pager->setPageSize(0xFFFF);
    }

    return $pager;
  }

  /**
   * @return array<string,PhabricatorObjectHandle> $results Array of pairs of
   *   the object's PHID as key and the corresponding PhabricatorObjectHandle
   */
  public function executeQuery(
    PhabricatorPolicyAwareQuery $query,
    AphrontView $pager) {

    $query->setViewer($this->requireViewer());

    if ($this->shouldUseOffsetPaging()) {
      $objects = $query->executeWithOffsetPager($pager);
    } else {
      $objects = $query->executeWithCursorPager($pager);
    }

    $this->didExecuteQuery($query);

    return $objects;
  }

  protected function didExecuteQuery(PhabricatorPolicyAwareQuery $query) {
    return;
  }


/* -(  Rendering  )---------------------------------------------------------- */


  public function setRequest(AphrontRequest $request) {
    $this->request = $request;
    return $this;
  }

  public function getRequest() {
    return $this->request;
  }

  public function renderResults(
    array $objects,
    PhabricatorSavedQuery $query) {

    $phids = $this->getRequiredHandlePHIDsForResultList($objects, $query);

    if ($phids) {
      $handles = id(new PhabricatorHandleQuery())
        ->setViewer($this->requireViewer())
        ->withPHIDs($phids)
        ->execute();
    } else {
      $handles = array();
    }

    return $this->renderResultList($objects, $query, $handles);
  }

  protected function getRequiredHandlePHIDsForResultList(
    array $objects,
    PhabricatorSavedQuery $query) {
    return array();
  }

  abstract protected function renderResultList(
    array $objects,
    PhabricatorSavedQuery $query,
    array $handles);


/* -(  Application Search  )------------------------------------------------- */


  public function getSearchFieldsForConduit() {
    $standard_fields = $this->buildSearchFields();

    $fields = array();
    foreach ($standard_fields as $field_key => $field) {
      $conduit_key = $field->getConduitKey();

      if (isset($fields[$conduit_key])) {
        $other = $fields[$conduit_key];
        $other_key = $other->getKey();

        throw new Exception(
          pht(
            'SearchFields "%s" (of class "%s") and "%s" (of class "%s") both '.
            'define the same Conduit key ("%s"). Keys must be unique.',
            $field_key,
            get_class($field),
            $other_key,
            get_class($other),
            $conduit_key));
      }

      $fields[$conduit_key] = $field;
    }

    // These are handled separately for Conduit, so don't show them as
    // supported.
    unset($fields['order']);
    unset($fields['limit']);

    $viewer = $this->requireViewer();
    foreach ($fields as $key => $field) {
      $field->setViewer($viewer);
    }

    return $fields;
  }

  public function buildConduitResponse(
    ConduitAPIRequest $request,
    ConduitAPIMethod $method) {
    $viewer = $this->requireViewer();

    $query_key = $request->getValue('queryKey');
    $is_empty_query_key = phutil_string_cast($query_key) === '';
    if ($is_empty_query_key) {
      $saved_query = new PhabricatorSavedQuery();
    } else if ($this->isBuiltinQuery($query_key)) {
      $saved_query = $this->buildSavedQueryFromBuiltin($query_key);
    } else if (strlen($query_key) !== PhabricatorHash::INDEX_DIGEST_LENGTH) {
        throw new Exception(
          pht(
            'Query key "%s" does not correspond to a valid query.',
            $query_key));
    } else {
      $saved_query = id(new PhabricatorSavedQueryQuery())
        ->setViewer($viewer)
        ->withQueryKeys(array($query_key))
        ->executeOne();
      if (!$saved_query) {
        throw new Exception(
          pht(
            'Query key "%s" does not correspond to a valid query.',
            $query_key));
      }
    }

    $constraints = $request->getValue('constraints', array());
    if (!is_array($constraints)) {
      throw new Exception(
        pht(
          'Parameter "constraints" must be a map of constraints, got "%s".',
          phutil_describe_type($constraints)));
    }

    $fields = $this->getSearchFieldsForConduit();

    foreach ($fields as $key => $field) {
      if (!$field->getConduitParameterType()) {
        unset($fields[$key]);
      }
    }

    $valid_constraints = array();
    foreach ($fields as $field) {
      foreach ($field->getValidConstraintKeys() as $key) {
        $valid_constraints[$key] = true;
      }
    }

    foreach ($constraints as $key => $constraint) {
      if (empty($valid_constraints[$key])) {
        throw new Exception(
          pht(
            'Constraint "%s" is not a valid constraint for this query.',
            $key));
      }
    }

    foreach ($fields as $field) {
      if (!$field->getValueExistsInConduitRequest($constraints)) {
        continue;
      }

      $value = $field->readValueFromConduitRequest(
        $constraints,
        $request->getIsStrictlyTyped());
      $saved_query->setParameter($field->getKey(), $value);
    }

    // NOTE: Currently, when running an ad-hoc query we never persist it into
    // a saved query. We might want to add an option to do this in the future
    // (for example, to enable a CLI-to-Web workflow where user can view more
    // details about results by following a link), but have no use cases for
    // it today. If we do identify a use case, we could save the query here.

    $query = $this->buildQueryFromSavedQuery($saved_query);
    $pager = $this->newPagerForSavedQuery($saved_query);

    $attachments = $this->getConduitSearchAttachments();

    $attachment_specs = $request->getValue('attachments', array());
    if (!is_array($attachment_specs)) {
      throw new Exception(
        pht(
          'Parameter "attachments" must be a map of attachments, got "%s".',
          phutil_describe_type($attachment_specs)));
    }
    foreach ($attachment_specs as $key => $attachment) {
      if (empty($attachments[$key])) {
        throw new Exception(
          pht(
            'Attachment key "%s" is not a valid attachment for this query.',
            $key));
      }
    }

    $attachments = array_select_keys(
      $attachments,
      array_keys($attachment_specs));

    foreach ($attachments as $key => $attachment) {
      $attachment->setViewer($viewer);
    }

    foreach ($attachments as $key => $attachment) {
      $attachment->willLoadAttachmentData($query, $attachment_specs[$key]);
    }

    $this->setQueryOrderForConduit($query, $request);
    $this->setPagerLimitForConduit($pager, $request);
    $this->setPagerOffsetsForConduit($pager, $request);

    $objects = $this->executeQuery($query, $pager);

    $data = array();
    if ($objects) {
      $field_extensions = $this->getConduitFieldExtensions();

      $extension_data = array();
      foreach ($field_extensions as $key => $extension) {
        $extension_data[$key] = $extension->loadExtensionConduitData($objects);
      }

      $attachment_data = array();
      foreach ($attachments as $key => $attachment) {
        $attachment_data[$key] = $attachment->loadAttachmentData(
          $objects,
          $attachment_specs[$key]);
      }

      foreach ($objects as $object) {
        $field_map = $this->getObjectWireFieldsForConduit(
          $object,
          $field_extensions,
          $extension_data);

        $attachment_map = array();
        foreach ($attachments as $key => $attachment) {
          $attachment_map[$key] = $attachment->getAttachmentForObject(
            $object,
            $attachment_data[$key],
            $attachment_specs[$key]);
        }

        // If this is empty, we still want to emit a JSON object, not a
        // JSON list.
        if (!$attachment_map) {
          $attachment_map = (object)$attachment_map;
        }

        $id = (int)$object->getID();
        $phid = $object->getPHID();

        $data[] = array(
          'id' => $id,
          'type' => phid_get_type($phid),
          'phid' => $phid,
          'fields' => $field_map,
          'attachments' => $attachment_map,
        );
      }
    }

    return array(
      'data' => $data,
      'maps' => $method->getQueryMaps($query),
      'query' => array(
        // This may be `null` if we have not saved the query.
        'queryKey' => $saved_query->getQueryKey(),
      ),
      'cursor' => array(
        'limit' => $pager->getPageSize(),
        'after' => $pager->getNextPageID(),
        'before' => $pager->getPrevPageID(),
        'order' => $request->getValue('order'),
      ),
    );
  }

  public function getAllConduitFieldSpecifications() {
    $extensions = $this->getConduitFieldExtensions();
    $object = $this->newQuery()->newResultObject();

    $map = array();
    foreach ($extensions as $extension) {
      $specifications = $extension->getFieldSpecificationsForConduit($object);
      foreach ($specifications as $specification) {
        $key = $specification->getKey();
        if (isset($map[$key])) {
          throw new Exception(
            pht(
              'Two field specifications share the same key ("%s"). Each '.
              'specification must have a unique key.',
              $key));
        }
        $map[$key] = $specification;
      }
    }

    return $map;
  }

  private function getEngineExtensions() {
    $extensions = PhabricatorSearchEngineExtension::getAllEnabledExtensions();

    foreach ($extensions as $key => $extension) {
      $extension
        ->setViewer($this->requireViewer())
        ->setSearchEngine($this);
    }

    $object = $this->newResultObject();
    foreach ($extensions as $key => $extension) {
      if (!$extension->supportsObject($object)) {
        unset($extensions[$key]);
      }
    }

    return $extensions;
  }


  private function getConduitFieldExtensions() {
    $extensions = $this->getEngineExtensions();
    $object = $this->newResultObject();

    foreach ($extensions as $key => $extension) {
      if (!$extension->getFieldSpecificationsForConduit($object)) {
        unset($extensions[$key]);
      }
    }

    return $extensions;
  }

  private function setQueryOrderForConduit($query, ConduitAPIRequest $request) {
    $order = $request->getValue('order');
    if ($order === null) {
      return;
    }

    if (is_scalar($order)) {
      $query->setOrder($order);
    } else {
      $query->setOrderVector($order);
    }
  }

  private function setPagerLimitForConduit($pager, ConduitAPIRequest $request) {
    $limit = $request->getValue('limit');

    // If there's no limit specified and the query uses a weird huge page
    // size, just leave it at the default gigantic page size. Otherwise,
    // make sure it's between 1 and 100, inclusive.

    if ($limit === null) {
      if ($pager->getPageSize() >= 0xFFFF) {
        return;
      } else {
        $limit = 100;
      }
    }

    if ($limit > 100) {
      throw new Exception(
        pht(
          'Maximum page size for Conduit API method calls is 100, but '.
          'this call specified %s.',
          $limit));
    }

    if ($limit < 1) {
      throw new Exception(
        pht(
          'Minimum page size for API searches is 1, but this call '.
          'specified %s.',
          $limit));
    }

    $pager->setPageSize($limit);
  }

  private function setPagerOffsetsForConduit(
    $pager,
    ConduitAPIRequest $request) {
    $before_id = $request->getValue('before');
    if ($before_id !== null) {
      $pager->setBeforeID($before_id);
    }

    $after_id = $request->getValue('after');
    if ($after_id !== null) {
      $pager->setAfterID($after_id);
    }
  }

  protected function getObjectWireFieldsForConduit(
    $object,
    array $field_extensions,
    array $extension_data) {

    $fields = array();
    foreach ($field_extensions as $key => $extension) {
      $data = idx($extension_data, $key, array());
      $fields += $extension->getFieldValuesForConduit($object, $data);
    }

    return $fields;
  }

  public function getConduitSearchAttachments() {
    $extensions = $this->getEngineExtensions();
    $object = $this->newResultObject();

    $attachments = array();
    foreach ($extensions as $extension) {
      $extension_attachments = $extension->getSearchAttachments($object);
      foreach ($extension_attachments as $attachment) {
        $attachment_key = $attachment->getAttachmentKey();
        if (isset($attachments[$attachment_key])) {
          $other = $attachments[$attachment_key];
          throw new Exception(
            pht(
              'Two search engine attachments (of classes "%s" and "%s") '.
              'specify the same attachment key ("%s"); keys must be unique.',
              get_class($attachment),
              get_class($other),
              $attachment_key));
        }
        $attachments[$attachment_key] = $attachment;
      }
    }

    return $attachments;
  }

  /**
   * Render a content body (if available) to onboard new users.
   * This body is usually visible when you have no elements in a list,
   * or when you force the rendering on a list with the `?nux=1` URL.
   * @return mixed|PhutilSafeHTML|null
   */
  final public function renderNewUserView() {
    $body = $this->getNewUserBody();

    if (!$body) {
      return null;
    }

    return $body;
  }

  /**
   * Get a content body to onboard new users.
   * Traditionally this content is shown from an empty list, to explain
   * what a certain entity does, and how to create a new one.
   * @return mixed|PhutilSafeHTML|null
   */
  protected function getNewUserHeader() {
    return null;
  }

  protected function getNewUserBody() {
    return null;
  }

  public function newUseResultsActions(PhabricatorSavedQuery $saved) {
    return array();
  }


/* -(  Export  )------------------------------------------------------------- */


  public function canExport() {
    $fields = $this->newExportFields();
    return (bool)$fields;
  }

  final public function newExportFieldList() {
    $object = $this->newResultObject();

    $builtin_fields = array(
      id(new PhabricatorIDExportField())
        ->setKey('id')
        ->setLabel(pht('ID')),
    );

    if ($object->getConfigOption(LiskDAO::CONFIG_AUX_PHID)) {
      $builtin_fields[] = id(new PhabricatorPHIDExportField())
        ->setKey('phid')
        ->setLabel(pht('PHID'));
    }

    $fields = mpull($builtin_fields, null, 'getKey');

    $export_fields = $this->newExportFields();
    foreach ($export_fields as $export_field) {
      $key = $export_field->getKey();

      if (isset($fields[$key])) {
        throw new Exception(
          pht(
            'Search engine ("%s") defines an export field with a key ("%s") '.
            'that collides with another field. Each field must have a '.
            'unique key.',
            get_class($this),
            $key));
      }

      $fields[$key] = $export_field;
    }

    $extensions = $this->newExportExtensions();
    foreach ($extensions as $extension) {
      $extension_fields = $extension->newExportFields();
      foreach ($extension_fields as $extension_field) {
        $key = $extension_field->getKey();

        if (isset($fields[$key])) {
          throw new Exception(
            pht(
              'Export engine extension ("%s") defines an export field with '.
              'a key ("%s") that collides with another field. Each field '.
              'must have a unique key.',
              get_class($extension_field),
              $key));
        }

        $fields[$key] = $extension_field;
      }
    }

    return $fields;
  }

  final public function newExport(array $objects) {
    $object = $this->newResultObject();
    $has_phid = $object->getConfigOption(LiskDAO::CONFIG_AUX_PHID);

    $objects = array_values($objects);
    $n = count($objects);

    $maps = array();
    foreach ($objects as $object) {
      $map = array(
        'id' => $object->getID(),
      );

      if ($has_phid) {
        $map['phid'] = $object->getPHID();
      }

      $maps[] = $map;
    }

    $export_data = $this->newExportData($objects);
    $export_data = array_values($export_data);
    if (count($export_data) !== count($objects)) {
      throw new Exception(
        pht(
          'Search engine ("%s") exported the wrong number of objects, '.
          'expected %s but got %s.',
          get_class($this),
          phutil_count($objects),
          phutil_count($export_data)));
    }

    for ($ii = 0; $ii < $n; $ii++) {
      $maps[$ii] += $export_data[$ii];
    }

    $extensions = $this->newExportExtensions();
    foreach ($extensions as $extension) {
      $extension_data = $extension->newExportData($objects);
      $extension_data = array_values($extension_data);
      if (count($export_data) !== count($objects)) {
        throw new Exception(
          pht(
            'Export engine extension ("%s") exported the wrong number of '.
            'objects, expected %s but got %s.',
            get_class($extension),
            phutil_count($objects),
            phutil_count($export_data)));
      }

      for ($ii = 0; $ii < $n; $ii++) {
        $maps[$ii] += $extension_data[$ii];
      }
    }

    return $maps;
  }

  protected function newExportFields() {
    return array();
  }

  protected function newExportData(array $objects) {
    throw new PhutilMethodNotImplementedException();
  }

  private function newExportExtensions() {
    $object = $this->newResultObject();
    $viewer = $this->requireViewer();

    $extensions = PhabricatorExportEngineExtension::getAllExtensions();

    $supported = array();
    foreach ($extensions as $extension) {
      $extension = clone $extension;
      $extension->setViewer($viewer);

      if ($extension->supportsObject($object)) {
        $supported[] = $extension;
      }
    }

    return $supported;
  }

  /**
   * Load from object and from storage, and updates Custom Fields instances
   * that are attached to each object.
   *
   * @param array<PhabricatorCustomFieldInterface> $objects
   * @param string $role One of the PhabricatorCustomField::ROLE_ constants
   * @return array<string, PhabricatorCustomFieldList> Map of loaded fields
   *   (PHID to PhabricatorCustomFieldList).
   * @task custom
   */
  protected function loadCustomFields(array $objects, $role) {
    assert_instances_of($objects, PhabricatorCustomFieldInterface::class);

    $query = new PhabricatorCustomFieldStorageQuery();
    $lists = array();

    foreach ($objects as $object) {
      $field_list = PhabricatorCustomField::getObjectFields($object, $role);
      $field_list->readFieldsFromObject($object);
      foreach ($field_list->getFields() as $field) {
        // TODO move $viewer into PhabricatorCustomFieldStorageQuery
        $field->setViewer($this->viewer);
      }
      $lists[$object->getPHID()] = $field_list;
      $query->addFields($field_list->getFields());
    }
    // This updates the field_list objects.
    $query->execute();

    return $lists;
  }

}