Correct a parameter order swap in "diffusion.historyquery" for Mercurial

[phabricator.git] / src / applications / search / field / PhabricatorSearchField.php

<?php

/**
 * @task config Configuring Fields
 * @task error Handling Errors
 * @task io Reading and Writing Field Values
 * @task conduit Integration with Conduit
 * @task util Utility Methods
 */
abstract class PhabricatorSearchField extends Phobject {

  private $key;
  private $conduitKey;
  private $viewer;
  private $value;
  private $label;
  private $aliases = array();
  private $errors = array();
  private $description;
  private $isHidden;

  private $enableForConduit = true;


/* -(  Configuring Fields  )------------------------------------------------- */


  /**
   * Set the primary key for the field, like `projectPHIDs`.
   *
   * You can set human-readable aliases with @{method:setAliases}.
   *
   * The key should be a short, unique (within a search engine) string which
   * does not contain any special characters.
   *
   * @param string Unique key which identifies the field.
   * @return this
   * @task config
   */
  public function setKey($key) {
    $this->key = $key;
    return $this;
  }


  /**
   * Get the field's key.
   *
   * @return string Unique key for this field.
   * @task config
   */
  public function getKey() {
    return $this->key;
  }


  /**
   * Set a human-readable label for the field.
   *
   * This should be a short text string, like "Reviewers" or "Colors".
   *
   * @param string Short, human-readable field label.
   * @return this
   * task config
   */
  public function setLabel($label) {
    $this->label = $label;
    return $this;
  }


  /**
   * Get the field's human-readable label.
   *
   * @return string Short, human-readable field label.
   * @task config
   */
  public function getLabel() {
    return $this->label;
  }


  /**
   * Set the acting viewer.
   *
   * Engines do not need to do this explicitly; it will be done on their
   * behalf by the caller.
   *
   * @param PhabricatorUser Viewer.
   * @return this
   * @task config
   */
  public function setViewer(PhabricatorUser $viewer) {
    $this->viewer = $viewer;
    return $this;
  }


  /**
   * Get the acting viewer.
   *
   * @return PhabricatorUser Viewer.
   * @task config
   */
  public function getViewer() {
    return $this->viewer;
  }


  /**
   * Provide alternate field aliases, usually more human-readable versions
   * of the key.
   *
   * These aliases can be used when building GET requests, so you can provide
   * an alias like `authors` to let users write `&authors=alincoln` instead of
   * `&authorPHIDs=alincoln`. This is a little easier to use.
   *
   * @param list<string> List of aliases for this field.
   * @return this
   * @task config
   */
  public function setAliases(array $aliases) {
    $this->aliases = $aliases;
    return $this;
  }


  /**
   * Get aliases for this field.
   *
   * @return list<string> List of aliases for this field.
   * @task config
   */
  public function getAliases() {
    return $this->aliases;
  }


  /**
   * Provide an alternate field key for Conduit.
   *
   * This can allow you to choose a more usable key for API endpoints.
   * If no key is provided, the main key is used.
   *
   * @param string Alternate key for Conduit.
   * @return this
   * @task config
   */
  public function setConduitKey($conduit_key) {
    $this->conduitKey = $conduit_key;
    return $this;
  }


  /**
   * Get the field key for use in Conduit.
   *
   * @return string Conduit key for this field.
   * @task config
   */
  public function getConduitKey() {
    if ($this->conduitKey !== null) {
      return $this->conduitKey;
    }

    return $this->getKey();
  }


  /**
   * Set a human-readable description for this field.
   *
   * @param string Human-readable description.
   * @return this
   * @task config
   */
  public function setDescription($description) {
    $this->description = $description;
    return $this;
  }


  /**
   * Get this field's human-readable description.
   *
   * @return string|null Human-readable description.
   * @task config
   */
  public function getDescription() {
    return $this->description;
  }


  /**
   * Hide this field from the web UI.
   *
   * @param bool True to hide the field from the web UI.
   * @return this
   * @task config
   */
  public function setIsHidden($is_hidden) {
    $this->isHidden = $is_hidden;
    return $this;
  }


  /**
   * Should this field be hidden from the web UI?
   *
   * @return bool True to hide the field in the web UI.
   * @task config
   */
  public function getIsHidden() {
    return $this->isHidden;
  }


/* -(  Handling Errors  )---------------------------------------------------- */


  protected function addError($short, $long) {
    $this->errors[] = array($short, $long);
    return $this;
  }

  public function getErrors() {
    return $this->errors;
  }

  protected function validateControlValue($value) {
    return;
  }

  protected function getShortError() {
    $error = head($this->getErrors());
    if ($error) {
      return head($error);
    }
    return null;
  }


/* -(  Reading and Writing Field Values  )----------------------------------- */


  public function readValueFromRequest(AphrontRequest $request) {
    $check = array_merge(array($this->getKey()), $this->getAliases());
    foreach ($check as $key) {
      if ($this->getValueExistsInRequest($request, $key)) {
        return $this->getValueFromRequest($request, $key);
      }
    }
    return $this->getDefaultValue();
  }

  protected function getValueExistsInRequest(AphrontRequest $request, $key) {
    return $request->getExists($key);
  }

  abstract protected function getValueFromRequest(
    AphrontRequest $request,
    $key);

  public function readValueFromSavedQuery(PhabricatorSavedQuery $saved) {
    $value = $saved->getParameter(
      $this->getKey(),
      $this->getDefaultValue());
    $this->value = $this->didReadValueFromSavedQuery($value);
    $this->validateControlValue($value);
    return $this;
  }

  protected function didReadValueFromSavedQuery($value) {
    return $value;
  }

  public function getValue() {
    return $this->value;
  }

  protected function getValueForControl() {
    return $this->value;
  }

  protected function getDefaultValue() {
    return null;
  }

  public function getValueForQuery($value) {
    return $value;
  }


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


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


  protected function renderControl() {
    if ($this->getIsHidden()) {
      return null;
    }

    $control = $this->newControl();

    if (!$control) {
      return null;
    }

    // TODO: We should `setError($this->getShortError())` here, but it looks
    // terrible in the form layout.

    return $control
      ->setValue($this->getValueForControl())
      ->setName($this->getKey())
      ->setLabel($this->getLabel());
  }

  public function appendToForm(AphrontFormView $form) {
    $control = $this->renderControl();
    if ($control !== null) {
      $form->appendControl($this->renderControl());
    }
    return $this;
  }


/* -(  Integration with Conduit  )------------------------------------------- */


  /**
   * @task conduit
   */
  final public function getConduitParameterType() {
    if (!$this->getEnableForConduit()) {
      return false;
    }

    $type = $this->newConduitParameterType();

    if ($type) {
      $type->setViewer($this->getViewer());
    }

    return $type;
  }

  protected function newConduitParameterType() {
    return null;
  }

  public function getValueExistsInConduitRequest(array $constraints) {
    return $this->getConduitParameterType()->getExists(
      $constraints,
      $this->getConduitKey());
  }

  public function readValueFromConduitRequest(
    array $constraints,
    $strict = true) {

    return $this->getConduitParameterType()->getValue(
      $constraints,
      $this->getConduitKey(),
      $strict);
  }

  public function getValidConstraintKeys() {
    return $this->getConduitParameterType()->getKeys(
      $this->getConduitKey());
  }

  final public function setEnableForConduit($enable) {
    $this->enableForConduit = $enable;
    return $this;
  }

  final public function getEnableForConduit() {
    return $this->enableForConduit;
  }

  public function newConduitConstants() {
    return array();
  }


/* -(  Utility Methods )----------------------------------------------------- */


  /**
   * 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 to read strings from.
   * @param string          Key to read in the request.
   * @return list<string>   List of values.
   * @task utility
   */
  protected function getListFromRequest(
    AphrontRequest $request,
    $key) {

    $list = $request->getArr($key, null);
    if ($list === null) {
      $list = $request->getStrList($key);
    }

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

    return $list;
  }



}