Page MenuHomePhorge
Diviner Tech Docs PhabricatorMarkupEngine

final class PhabricatorMarkupEngine
Phorge Technical Documentation (Remarkup)

Manages markup engine selection, configuration, application, caching and pipelining.

PhabricatorMarkupEngine can be used to render objects which implement PhabricatorMarkupInterface in a batched, cache-aware way. For example, if you have a list of comments written in remarkup (and the objects implement the correct interface) you can render them by first building an engine and adding the fields with addObject().

$field  = 'field:body'; // Field you want to render. Each object exposes
                        // one or more fields of markup.

$engine = new PhabricatorMarkupEngine();
foreach ($comments as $comment) {
  $engine->addObject($comment, $field);
}

Now, call process() to perform the actual cache/rendering step. This is a heavyweight call which does batched data access and transforms the markup into output.

$engine->process();

Finally, do something with the results:

$results = array();
foreach ($comments as $comment) {
  $results[] = $engine->getOutput($comment, $field);
}

If you have a single object to render, you can use the convenience method renderOneObject().

Tasks

Markup Pipeline

  • public static function renderOneObject($object, $field, $viewer, $context_object) — Convenience method for pushing a single object through the markup pipeline.
  • public function addObject($object, $field) — Queue an object for markup generation when @{method:process} is called. You can retrieve the output later with @{method:getOutput}.
  • public function process() — Process objects queued with @{method:addObject}. You can then retrieve the output with @{method:getOutput}.
  • public function getOutput($object, $field) — Get the output of markup processing for a field queued with @{method:addObject}. Before you can call this method, you must call @{method:process}.
  • public function getEngineMetadata($object, $field, $metadata_key, $default) — Retrieve engine metadata for a given field.
  • private function requireKeyProcessed($key)
  • private function getMarkupFieldKey($object, $field)
  • private function loadPreprocessorCaches($engines, $objects)
  • public function setViewer($viewer) — Set the viewing user. Used to implement object permissions.
  • public function setContextObject($object) — Set the context object. Used to implement object permissions.

Engine Construction

Other Methods

Methods

public function __get($name)
Inherited

This method is not documented.
Parameters
$name
Return
wild

public function __set($name, $value)
Inherited

This method is not documented.
Parameters
$name
$value
Return
wild

public function current()
Inherited

This method is not documented.
Return
wild

public function key()
Inherited

This method is not documented.
Return
wild

public function next()
Inherited

This method is not documented.
Return
wild

public function rewind()
Inherited

This method is not documented.
Return
wild

public function valid()
Inherited

This method is not documented.
Return
wild

private function throwOnAttemptedIteration()
Inherited

This method is not documented.
Return
wild

public function getPhobjectClassConstant($key, $byte_limit)
Inherited

Phobject

Read the value of a class constant.

This is the same as just typing self::CONSTANTNAME, but throws a more useful message if the constant is not defined and allows the constant to be limited to a maximum length.

Parameters
string$keyName of the constant.
int|null$byte_limitMaximum number of bytes permitted in the value.
Return
stringValue of the constant.

public static function renderOneObject($object, $field, $viewer, $context_object)

Convenience method for pushing a single object through the markup pipeline.

Parameters
PhabricatorMarkupInterface$objectThe object to render.
string$fieldThe field to render.
PhabricatorUser$viewerUser viewing the markup.
object$context_objectA context object for policy checks
Return
stringMarked up output.

public function addObject($object, $field)

Queue an object for markup generation when process() is called. You can retrieve the output later with getOutput().

Parameters
PhabricatorMarkupInterface$objectThe object to render.
string$fieldThe field to render.
Return
this

public function process()

Process objects queued with addObject(). You can then retrieve the output with getOutput().

Return
this

public static function isRenderingEmbeddedContent()

This method is not documented.
Return
wild

private function execute()

This method is not documented.
Return
wild

public function getOutput($object, $field)

Get the output of markup processing for a field queued with addObject(). Before you can call this method, you must call process().

Parameters
PhabricatorMarkupInterface$objectThe object to retrieve.
string$fieldThe field to retrieve.
Return
stringProcessed output.

public function getEngineMetadata($object, $field, $metadata_key, $default)

Retrieve engine metadata for a given field.

Parameters
PhabricatorMarkupInterface$objectThe object to retrieve.
string$fieldThe field to retrieve.
string$metadata_keyThe engine metadata field to retrieve.
wild$defaultOptional default value.
Return
wild

private function requireKeyProcessed($key)

This method is not documented.
Parameters
$key
Return
wild

private function getMarkupFieldKey($object, $field)

This method is not documented.
Parameters
PhabricatorMarkupInterface$object
$field
Return
wild

private function loadPreprocessorCaches($engines, $objects)

This method is not documented.
Parameters
array$engines
array$objects
Return
wild

public function setViewer($viewer)

Set the viewing user. Used to implement object permissions.

Parameters
PhabricatorUser$viewerThe viewing user.
Return
this

public function setContextObject($object)

Set the context object. Used to implement object permissions.

Parameters
The$objectobject in which context this remarkup is used.
Return
this

public function setAuxiliaryConfig($key, $value)

This method is not documented.
Parameters
$key
$value
Return
wild

public static function newManiphestMarkupEngine()

This method is not documented.
Return
wild

public static function newPhrictionMarkupEngine()

This method is not documented.
Return
wild

public static function newPhameMarkupEngine()

This method is not documented.
Return
wild

public static function newFeedMarkupEngine()

This method is not documented.
Return
wild

public static function newCalendarMarkupEngine()

This method is not documented.
Return
wild

public static function newDifferentialMarkupEngine($options)

This method is not documented.
Parameters
array$options
Return
wild

public static function newDiffusionMarkupEngine($options)

This method is not documented.
Parameters
array$options
Return
wild

public static function getEngine($ruleset)

This method is not documented.
Parameters
$ruleset
Return
wild

private static function getMarkupEngineDefaultConfiguration()

This method is not documented.
Return
wild

public static function newMarkupEngine($options)

This method is not documented.
Parameters
array$options
Return
wild

public static function extractPHIDsFromMentions($viewer, $content_blocks)

This method is not documented.
Parameters
PhabricatorUser$viewer
array$content_blocks
Return
wild

public static function extractFilePHIDsFromEmbeddedFiles($viewer, $content_blocks)

This method is not documented.
Parameters
PhabricatorUser$viewer
array$content_blocks
Return
wild

public static function summarizeSentence($corpus)

This method is not documented.
Parameters
$corpus
Return
wild

public static function summarize($corpus)

Produce a corpus summary, in a way that shortens the underlying text without truncating it somewhere awkward.

TODO: We could do a better job of this.

Parameters
string$corpusRemarkup corpus to summarize.
Return
stringSummarized corpus.

private static function loadCustomInlineRules()

This method is not documented.
Return
wild

private static function loadCustomBlockRules()

This method is not documented.
Return
wild

public static function digestRemarkupContent($object, $content)

This method is not documented.
Parameters
$object
$content
Return
wild