Issue #3200162 by brandonlira, ksenzee, ultimike, larowlan, cecelias, xjm:...

/**

 * Directed acyclic graph manipulation.

 *

 * This class represents a directed acyclic graph (DAG) and provides methods

 * for processing and sorting it.

 *

 * Example of a graph structure:

 * @code

 *   1────►2────►3

 *         │     │

 *         │     ▼

 *         └───► 4

 * @endcode

 *

 * Example of defining a graph in PHP:

 * @code

 *   $graph[1]['edges'][2] = 1;

 *   $graph[2]['edges'][3] = 1;

 *   $graph[2]['edges'][4] = 1;

 *   $graph[3]['edges'][4] = 1;

 * @endcode

 */

class Graph {

  protected $graph;

  /**

   * Instantiates the depth first search object.

   * Instantiates the directed acyclic graph object.

   *

   * @param array $graph

   *   A three dimensional associated array, with the first keys being the names

   *   of the vertices, these can be strings or numbers. The second key is

   *   'edges' and the third one are again vertices, each such key representing

   *   an edge. Values of array elements are copied over.

   *

   *   Example:

   *   @code

   *     $graph[1]['edges'][2] = 1;

   *     $graph[2]['edges'][3] = 1;

   *     $graph[2]['edges'][4] = 1;

   *     $graph[3]['edges'][4] = 1;

   *   @endcode

   *

   *   On return you will also have:

   *   @code

   *     $graph[1]['paths'][2] = 1;

   *     $graph[1]['paths'][3] = 1;

   *     $graph[2]['reverse_paths'][1] = 1;

   *     $graph[3]['reverse_paths'][1] = 1;

   *   @endcode

   *   A three-dimensional associative array, with the first keys being the

   *   names of the vertices, which can be strings or numbers. The second key is

   *   'edges', whose value is an array keyed by the names of the vertices

   *   connected to it; the values in this array can be simply TRUE or may

   *   contain other data.

   */

  public function __construct($graph) {

    $this->graph = $graph;