Page MenuHomePhabricator

final class PhabricatorEdgeEditor
Phabricator Technical Documentation (Edges)

Add and remove edges between objects. You can use PhabricatorEdgeQuery to load object edges. For more information on edges, see Using Edges.

Edges are not directly policy aware, and this editor makes low-level changes below the policy layer.

Adding Edges
$src  = $earth_phid;
$type = PhabricatorEdgeConfig::TYPE_BODY_HAS_SATELLITE;
$dst  = $moon_phid;

id(new PhabricatorEdgeEditor())
  ->addEdge($src, $type, $dst)
  ->save();

Tasks

Editing Edges

  • public function addEdge($src, $type, $dst, $options) — Add a new edge (possibly also adding its inverse). Changes take effect when you call @{method:save}. If the edge already exists, it will not be overwritten, but if data is attached to the edge it will be updated. Removals queued with @{method:removeEdge} are executed before adds, so the effect of removing and adding the same edge is to overwrite any existing edge.
  • public function removeEdge($src, $type, $dst) — Remove an edge (possibly also removing its inverse). Changes take effect when you call @{method:save}. If an edge does not exist, the removal will be ignored. Edges are added after edges are removed, so the effect of a remove plus an add is to overwrite.
  • public function save() — Apply edge additions and removals queued by @{method:addEdge} and @{method:removeEdge}. Note that transactions are opened, all additions and removals are executed, and then transactions are saved. Thus, in some cases it may be slightly more efficient to perform multiple edit operations (e.g., adds followed by removals) if their outcomes are not dependent, since transactions will not be held open as long.

Cycle Prevention

No methods for this task.

Internals

  • private function buildEdgeSpecs($src, $type, $dst, $options) — Build the specification for an edge operation, and possibly build its inverse as well.
  • private function writeEdgeData() — Write edge data.
  • private function executeAdds() — Add queued edges.
  • private function executeRemoves() — Remove queued edges.
  • private function saveTransactions() — Save open transactions.

Other Methods

cycle

  • private function getPreventCyclesEdgeTypes() — Get a list of all edge types which are being added, and which we should prevent cycles on.
  • private function detectCycles($phids, $edge_type) — Detect graph cycles of a given edge type. If the edit introduces a cycle, a @{class:PhabricatorEdgeCycleException} is thrown with details.

Methods

public function addEdge($src, $type, $dst, $options)

Add a new edge (possibly also adding its inverse). Changes take effect when you call save(). If the edge already exists, it will not be overwritten, but if data is attached to the edge it will be updated. Removals queued with removeEdge() are executed before adds, so the effect of removing and adding the same edge is to overwrite any existing edge.

The $options parameter accepts these values:

  • data Optional, data to write onto the edge.
  • inverse_data Optional, data to write on the inverse edge. If not provided, data will be written.
Parameters
phid$srcSource object PHID.
const$typeEdge type constant.
phid$dstDestination object PHID.
map$optionsOptions map (see documentation).
Return
this

public function removeEdge($src, $type, $dst)

Remove an edge (possibly also removing its inverse). Changes take effect when you call save(). If an edge does not exist, the removal will be ignored. Edges are added after edges are removed, so the effect of a remove plus an add is to overwrite.

Parameters
phid$srcSource object PHID.
const$typeEdge type constant.
phid$dstDestination object PHID.
Return
this

public function save()

Apply edge additions and removals queued by addEdge() and removeEdge(). Note that transactions are opened, all additions and removals are executed, and then transactions are saved. Thus, in some cases it may be slightly more efficient to perform multiple edit operations (e.g., adds followed by removals) if their outcomes are not dependent, since transactions will not be held open as long.

Return
this

private function buildEdgeSpecs($src, $type, $dst, $options)

Build the specification for an edge operation, and possibly build its inverse as well.

Parameters
$src
$type
$dst
array$options
Return
wild

private function writeEdgeData()

Write edge data.

Return
wild

private function executeAdds()

Add queued edges.

Return
wild

private function executeRemoves()

Remove queued edges.

Return
wild

private function saveTransactions()

Save open transactions.

Return
wild

private function killTransactions()

This method is not documented.
Return
wild

private function getPreventCyclesEdgeTypes()

Get a list of all edge types which are being added, and which we should prevent cycles on.

Return
list<const>List of edge types which should have cycles prevented.

private function detectCycles($phids, $edge_type)

Detect graph cycles of a given edge type. If the edit introduces a cycle, a PhabricatorEdgeCycleException is thrown with details.

Parameters
array$phids
$edge_type
Return
void