<?php

namespace Drupal\Core\Database\Query;

/**
 * Interface for extendable query objects.
 *
 * "Extenders" follow the "Decorator" OOP design pattern.  That is, they wrap
 * and "decorate" another object. In our case, they implement the same
 * interface as select queries and wrap a select query, to which they delegate
 * almost all operations. Subclasses of this class may implement additional
 * methods or override existing methods as appropriate. Extenders may also wrap
 * other extender objects, allowing for arbitrarily complex "enhanced" queries.
 */
interface ExtendableInterface {

  /**
   * Enhance this object by wrapping it in an extender object.
   *
   * @param class-string $extender_name
   *   The fully-qualified name of the extender class, without the leading '\'
   *   (for example, Drupal\my_module\myExtenderClass). The extender name will
   *   be checked against the current database connection to allow
   *   driver-specific subclasses as well, using the same logic as the query
   *   objects themselves.
   *
   * @return \Drupal\Core\Database\Query\ExtendableInterface
   *   The extender object, which now contains a reference to this object.
   */
  public function extend($extender_name);

}
