No OneTemporary
Actions

Size

32 KB

Referenced Files

None

Subscribers

None

View Options

	diff --git a/src/applications/conduit/controller/PhabricatorConduitConsoleController.php b/src/applications/conduit/controller/PhabricatorConduitConsoleController.php
	index e570861f29..e878365acb 100644
	--- a/src/applications/conduit/controller/PhabricatorConduitConsoleController.php
	+++ b/src/applications/conduit/controller/PhabricatorConduitConsoleController.php
	@@ -1,207 +1,209 @@
	<?php

	final class PhabricatorConduitConsoleController
	extends PhabricatorConduitController {

	public function shouldAllowPublic() {
	return true;
	}

	public function handleRequest(AphrontRequest $request) {
	$viewer = $this->getViewer();
	$method_name = $request->getURIData('method');

	$method = id(new PhabricatorConduitMethodQuery())
	->setViewer($viewer)
	->withMethods(array($method_name))
	->executeOne();
	if (!$method) {
	return new Aphront404Response();
	}

	+ $method->setViewer($viewer);
	+
	$call_uri = '/api/'.$method->getAPIMethodName();

	$status = $method->getMethodStatus();
	$reason = $method->getMethodStatusDescription();
	$errors = array();

	switch ($status) {
	case ConduitAPIMethod::METHOD_STATUS_DEPRECATED:
	$reason = nonempty($reason, pht('This method is deprecated.'));
	$errors[] = pht('Deprecated Method: %s', $reason);
	break;
	case ConduitAPIMethod::METHOD_STATUS_UNSTABLE:
	$reason = nonempty(
	$reason,
	pht(
	'This method is new and unstable. Its interface is subject '.
	'to change.'));
	$errors[] = pht('Unstable Method: %s', $reason);
	break;
	}

	$form = id(new AphrontFormView())
	->setAction($call_uri)
	->setUser($request->getUser())
	->appendRemarkupInstructions(
	pht(
	'Enter parameters using JSON. For instance, to enter a '.
	'list, type: `%s`',
	'["apple", "banana", "cherry"]'));

	$params = $method->getParamTypes();
	foreach ($params as $param => $desc) {
	$form->appendChild(
	id(new AphrontFormTextControl())
	->setLabel($param)
	->setName("params[{$param}]")
	->setCaption($desc));
	}

	$must_login = !$viewer->isLoggedIn() &&
	$method->shouldRequireAuthentication();
	if ($must_login) {
	$errors[] = pht(
	'Login Required: This method requires authentication. You must '.
	'log in before you can make calls to it.');
	} else {
	$form
	->appendChild(
	id(new AphrontFormSelectControl())
	->setLabel(pht('Output Format'))
	->setName('output')
	->setOptions(
	array(
	'human' => pht('Human Readable'),
	'json' => pht('JSON'),
	)))
	->appendChild(
	id(new AphrontFormSubmitControl())
	->addCancelButton($this->getApplicationURI())
	->setValue(pht('Call Method')));
	}

	$header = id(new PHUIHeaderView())
	->setUser($viewer)
	->setHeader($method->getAPIMethodName());

	$form_box = id(new PHUIObjectBoxView())
	->setHeaderText(pht('Call Method'))
	->setForm($form);

	$content = array();

	$properties = $this->buildMethodProperties($method);

	$info_box = id(new PHUIObjectBoxView())
	->setHeaderText(pht('API Method: %s', $method->getAPIMethodName()))
	->setFormErrors($errors)
	->appendChild($properties);

	$content[] = $info_box;
	$content[] = $form_box;
	$content[] = $this->renderExampleBox($method, null);

	$query = $method->newQueryObject();
	if ($query) {
	$orders = $query->getBuiltinOrders();

	$rows = array();
	foreach ($orders as $key => $order) {
	$rows[] = array(
	$key,
	$order['name'],
	implode(', ', $order['vector']),
	);
	}

	$table = id(new AphrontTableView($rows))
	->setHeaders(
	array(
	pht('Key'),
	pht('Description'),
	pht('Columns'),
	))
	->setColumnClasses(
	array(
	'pri',
	'',
	'wide',
	));
	$content[] = id(new PHUIObjectBoxView())
	->setHeaderText(pht('Builtin Orders'))
	->setTable($table);

	$columns = $query->getOrderableColumns();

	$rows = array();
	foreach ($columns as $key => $column) {
	$rows[] = array(
	$key,
	idx($column, 'unique') ? pht('Yes') : pht('No'),
	);
	}

	$table = id(new AphrontTableView($rows))
	->setHeaders(
	array(
	pht('Key'),
	pht('Unique'),
	))
	->setColumnClasses(
	array(
	'pri',
	'wide',
	));
	$content[] = id(new PHUIObjectBoxView())
	->setHeaderText(pht('Column Orders'))
	->setTable($table);
	}

	$crumbs = $this->buildApplicationCrumbs();
	$crumbs->addTextCrumb($method->getAPIMethodName());

	return $this->buildApplicationPage(
	array(
	$crumbs,
	$content,
	),
	array(
	'title' => $method->getAPIMethodName(),
	));
	}

	private function buildMethodProperties(ConduitAPIMethod $method) {
	$viewer = $this->getViewer();

	$view = id(new PHUIPropertyListView());

	$view->addProperty(
	pht('Returns'),
	$method->getReturnType());

	$error_types = $method->getErrorTypes();
	$error_types['ERR-CONDUIT-CORE'] = pht('See error message for details.');
	$error_description = array();
	foreach ($error_types as $error => $meaning) {
	$error_description[] = hsprintf(
	'<li><strong>%s:</strong> %s</li>',
	$error,
	$meaning);
	}
	$error_description = phutil_tag('ul', array(), $error_description);

	$view->addProperty(
	pht('Errors'),
	$error_description);

	$view->addSectionHeader(
	pht('Description'), PHUIPropertyListView::ICON_SUMMARY);
	$view->addTextContent(
	new PHUIRemarkupView($viewer, $method->getMethodDescription()));

	return $view;
	}


	}
	diff --git a/src/applications/conduit/method/ConduitAPIMethod.php b/src/applications/conduit/method/ConduitAPIMethod.php
	index afa75c53b3..8471ac8919 100644
	--- a/src/applications/conduit/method/ConduitAPIMethod.php
	+++ b/src/applications/conduit/method/ConduitAPIMethod.php
	@@ -1,382 +1,392 @@
	<?php

	/**
	* @task info Method Information
	* @task status Method Status
	* @task pager Paging Results
	*/
	abstract class ConduitAPIMethod
	extends Phobject
	implements PhabricatorPolicyInterface {

	+ private $viewer;

	const METHOD_STATUS_STABLE = 'stable';
	const METHOD_STATUS_UNSTABLE = 'unstable';
	const METHOD_STATUS_DEPRECATED = 'deprecated';


	/**
	* Get a short, human-readable text summary of the method.
	*
	* @return string Short summary of method.
	* @task info
	*/
	public function getMethodSummary() {
	return $this->getMethodDescription();
	}


	/**
	* Get a detailed description of the method.
	*
	* This method should return remarkup.
	*
	* @return string Detailed description of the method.
	* @task info
	*/
	abstract public function getMethodDescription();

	abstract protected function defineParamTypes();
	abstract protected function defineReturnType();

	protected function defineErrorTypes() {
	return array();
	}

	abstract protected function execute(ConduitAPIRequest $request);


	- public function __construct() {}
	-
	public function getParamTypes() {
	$types = $this->defineParamTypes();

	$query = $this->newQueryObject();
	if ($query) {
	$types['order'] = 'optional order';
	$types += $this->getPagerParamTypes();
	}

	return $types;
	}

	public function getReturnType() {
	return $this->defineReturnType();
	}

	public function getErrorTypes() {
	return $this->defineErrorTypes();
	}

	/**
	* This is mostly for compatibility with
	* @{class:PhabricatorCursorPagedPolicyAwareQuery}.
	*/
	public function getID() {
	return $this->getAPIMethodName();
	}

	/**
	* Get the status for this method (e.g., stable, unstable or deprecated).
	* Should return a METHOD_STATUS_* constant. By default, methods are
	* "stable".
	*
	* @return const METHOD_STATUS_* constant.
	* @task status
	*/
	public function getMethodStatus() {
	return self::METHOD_STATUS_STABLE;
	}

	/**
	* Optional description to supplement the method status. In particular, if
	* a method is deprecated, you can return a string here describing the reason
	* for deprecation and stable alternatives.
	*
	* @return string\|null Description of the method status, if available.
	* @task status
	*/
	public function getMethodStatusDescription() {
	return null;
	}

	public function getErrorDescription($error_code) {
	return idx($this->getErrorTypes(), $error_code, pht('Unknown Error'));
	}

	public function getRequiredScope() {
	// by default, conduit methods are not accessible via OAuth
	return PhabricatorOAuthServerScope::SCOPE_NOT_ACCESSIBLE;
	}

	public function executeMethod(ConduitAPIRequest $request) {
	+ $this->setViewer($request->getUser());
	+
	return $this->execute($request);
	}

	abstract public function getAPIMethodName();

	/**
	* Return a key which sorts methods by application name, then method status,
	* then method name.
	*/
	public function getSortOrder() {
	$name = $this->getAPIMethodName();

	$map = array(
	self::METHOD_STATUS_STABLE => 0,
	self::METHOD_STATUS_UNSTABLE => 1,
	self::METHOD_STATUS_DEPRECATED => 2,
	);
	$ord = idx($map, $this->getMethodStatus(), 0);

	list($head, $tail) = explode('.', $name, 2);

	return "{$head}.{$ord}.{$tail}";
	}

	public function getApplicationName() {
	return head(explode('.', $this->getAPIMethodName(), 2));
	}

	public static function loadAllConduitMethods() {
	return id(new PhutilClassMapQuery())
	->setAncestorClass(__CLASS__)
	->setUniqueMethod('getAPIMethodName')
	->execute();
	}

	public static function getConduitMethod($method_name) {
	$method_map = self::loadAllConduitMethods();
	return idx($method_map, $method_name);
	}

	public function shouldRequireAuthentication() {
	return true;
	}

	public function shouldAllowPublic() {
	return false;
	}

	public function shouldAllowUnguardedWrites() {
	return false;
	}


	/**
	* Optionally, return a @{class:PhabricatorApplication} which this call is
	* part of. The call will be disabled when the application is uninstalled.
	*
	* @return PhabricatorApplication\|null Related application.
	*/
	public function getApplication() {
	return null;
	}

	protected function formatStringConstants($constants) {
	foreach ($constants as $key => $value) {
	$constants[$key] = '"'.$value.'"';
	}
	$constants = implode(', ', $constants);
	return 'string-constant<'.$constants.'>';
	}

	public static function getParameterMetadataKey($key) {
	if (strncmp($key, 'api.', 4) === 0) {
	// All keys passed beginning with "api." are always metadata keys.
	return substr($key, 4);
	} else {
	switch ($key) {
	// These are real keys which always belong to request metadata.
	case 'access_token':
	case 'scope':
	case 'output':

	// This is not a real metadata key; it is included here only to
	// prevent Conduit methods from defining it.
	case '__conduit__':

	// This is prevented globally as a blanket defense against OAuth
	// redirection attacks. It is included here to stop Conduit methods
	// from defining it.
	case 'code':

	// This is not a real metadata key, but the presence of this
	// parameter triggers an alternate request decoding pathway.
	case 'params':
	return $key;
	}
	}

	return null;
	}

	+ final public function setViewer(PhabricatorUser $viewer) {
	+ $this->viewer = $viewer;
	+ return $this;
	+ }
	+
	+ final public function getViewer() {
	+ return $this->viewer;
	+ }
	+
	/* -( Paging Results )----------------------------------------------------- */


	/**
	* @task pager
	*/
	protected function getPagerParamTypes() {
	return array(
	'before' => 'optional string',
	'after' => 'optional string',
	'limit' => 'optional int (default = 100)',
	);
	}


	/**
	* @task pager
	*/
	protected function newPager(ConduitAPIRequest $request) {
	$limit = $request->getValue('limit', 100);
	$limit = min(1000, $limit);
	$limit = max(1, $limit);

	$pager = id(new AphrontCursorPagerView())
	->setPageSize($limit);

	$before_id = $request->getValue('before');
	if ($before_id !== null) {
	$pager->setBeforeID($before_id);
	}

	$after_id = $request->getValue('after');
	if ($after_id !== null) {
	$pager->setAfterID($after_id);
	}

	return $pager;
	}


	/**
	* @task pager
	*/
	protected function addPagerResults(
	array $results,
	AphrontCursorPagerView $pager) {

	$results['cursor'] = array(
	'limit' => $pager->getPageSize(),
	'after' => $pager->getNextPageID(),
	'before' => $pager->getPrevPageID(),
	);

	return $results;
	}


	/* -( Implementing Query Methods )----------------------------------------- */


	public function newQueryObject() {
	return null;
	}


	protected function newQueryForRequest(ConduitAPIRequest $request) {
	$query = $this->newQueryObject();

	if (!$query) {
	throw new Exception(
	pht(
	'You can not call newQueryFromRequest() in this method ("%s") '.
	'because it does not implement newQueryObject().',
	get_class($this)));
	}

	if (!($query instanceof PhabricatorCursorPagedPolicyAwareQuery)) {
	throw new Exception(
	pht(
	'Call to method newQueryObject() did not return an object of class '.
	'"%s".',
	'PhabricatorCursorPagedPolicyAwareQuery'));
	}

	$query->setViewer($request->getUser());

	$order = $request->getValue('order');
	if ($order !== null) {
	if (is_scalar($order)) {
	$query->setOrder($order);
	} else {
	$query->setOrderVector($order);
	}
	}

	return $query;
	}


	/* -( PhabricatorPolicyInterface )----------------------------------------- */


	public function getPHID() {
	return null;
	}

	public function getCapabilities() {
	return array(
	PhabricatorPolicyCapability::CAN_VIEW,
	);
	}

	public function getPolicy($capability) {
	// Application methods get application visibility; other methods get open
	// visibility.

	$application = $this->getApplication();
	if ($application) {
	return $application->getPolicy($capability);
	}

	return PhabricatorPolicies::getMostOpenPolicy();
	}

	public function hasAutomaticCapability($capability, PhabricatorUser $viewer) {
	if (!$this->shouldRequireAuthentication()) {
	// Make unauthenticated methods universally visible.
	return true;
	}

	return false;
	}

	public function describeAutomaticCapability($capability) {
	return null;
	}

	protected function hasApplicationCapability(
	$capability,
	PhabricatorUser $viewer) {

	$application = $this->getApplication();

	if (!$application) {
	return false;
	}

	return PhabricatorPolicyFilter::hasCapability(
	$viewer,
	$application,
	$capability);
	}

	protected function requireApplicationCapability(
	$capability,
	PhabricatorUser $viewer) {

	$application = $this->getApplication();
	if (!$application) {
	return;
	}

	PhabricatorPolicyFilter::requireCapability(
	$viewer,
	$this->getApplication(),
	$capability);
	}

	}
	diff --git a/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php b/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
	index ae27cb07c0..1ef3e02f33 100644
	--- a/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
	+++ b/src/applications/search/engine/PhabricatorSearchEngineAPIMethod.php
	@@ -1,389 +1,389 @@
	<?php

	abstract class PhabricatorSearchEngineAPIMethod
	extends ConduitAPIMethod {

	abstract public function newSearchEngine();

	public function getApplication() {
	$engine = $this->newSearchEngine();
	$class = $engine->getApplicationClassName();
	return PhabricatorApplication::getByClass($class);
	}

	public function getMethodStatus() {
	return self::METHOD_STATUS_UNSTABLE;
	}

	public function getMethodStatusDescription() {
	return pht('ApplicationSearch methods are highly unstable.');
	}

	final protected function defineParamTypes() {
	return array(
	'queryKey' => 'optional string',
	'constraints' => 'optional map<string, wild>',
	'order' => 'optional order',
	) + $this->getPagerParamTypes();
	}

	final protected function defineReturnType() {
	return 'map<string, wild>';
	}

	final protected function execute(ConduitAPIRequest $request) {
	$engine = $this->newSearchEngine()
	->setViewer($request->getUser());

	return $engine->buildConduitResponse($request);
	}

	final public function getMethodDescription() {
	- // TODO: We don't currently have a real viewer in this method.
	- $viewer = PhabricatorUser::getOmnipotentUser();
	+ $viewer = $this->getViewer();

	$engine = $this->newSearchEngine()
	->setViewer($viewer);

	$query = $engine->newQuery();

	$out = array();

	$out[] = pht(<<<EOTEXT
	This is a standard ApplicationSearch method which will let you list, query,
	or search for objects.

	EOTEXT
	);

	$out[] = pht(<<<EOTEXT
	Prebuilt Queries
	----------------

	You can use a builtin or saved query as a starting point by passing it with
	`queryKey`. If you don't specify a `queryKey`, the query will start with no
	constraints.

	For example, many applications have builtin queries like `"active"` or
	`"open"` to find only active or enabled results. To use a `queryKey`, specify
	it like this:

	```lang=json
	{
	...
	"queryKey": "active",
	...
	}
	```

	-These builtin and saved queries are available:
	+You can use these keys to select builtin queries and your configured saved
	+queries:
	EOTEXT
	);

	$head_querykey = pht('Query Key');
	$head_name = pht('Name');
	$head_builtin = pht('Builtin');

	$named_queries = $engine->loadAllNamedQueries();

	$table = array();
	$table[] = "\| {$head_querykey} \| {$head_name} \| {$head_builtin} \|";
	$table[] = '\|------------------\|--------------\|-----------------\|';
	foreach ($named_queries as $named_query) {
	$key = $named_query->getQueryKey();
	$name = $named_query->getQueryName();
	$builtin = $named_query->getIsBuiltin()
	? pht('Builtin')
	: pht('Custom');

	$table[] = "\| `{$key}` \| {$name} \| {$builtin} \|";
	}
	$table = implode("\n", $table);
	$out[] = $table;

	$out[] = pht(<<<EOTEXT
	You can also use any query you run via the web UI as a starting point. You
	can find the key for a query by examining the URI after running a normal
	search.
	EOTEXT
	);

	$out[] = pht(<<<EOTEXT
	Custom Constraints
	------------------

	You can add custom constraints to the basic query by passing `constraints`.
	This will let you filter results (for example, show only results with a
	certain state, status, or owner).

	Specify constraints like this:

	```lang=json
	{
	...
	"constraints": {
	"authorPHIDs": ["PHID-USER-1111", "PHID-USER-2222"],
	"statuses": ["open", "closed"]
	},
	...
	}
	```

	If you specify both a `queryKey` and `constraints`, the basic query
	configuration will be applied first as a starting point, then any additional
	values in `constraints` will be applied, overwriting the defaults from the
	original query.

	This API endpoint supports these constraints:
	EOTEXT
	);

	$head_key = pht('Key');
	$head_label = pht('Label');
	$head_type = pht('Type');
	$head_desc = pht('Description');

	$desc_ids = pht('Search for specific objects by ID.');
	$desc_phids = pht('Search for specific objects by PHID.');

	$fields = $engine->getSearchFieldsForConduit();

	$table = array();
	$table[] = "\| {$head_key} \| {$head_label} \| {$head_type} \| {$head_desc} \|";
	$table[] = '\|-------------\|---------------\|--------------\|--------------\|';
	$table[] = "\| `ids` \| IDs \| `list<int>` \| {$desc_ids} \|";
	$table[] = "\| `phids` \| PHIDs \| `list<phid>` \| {$desc_phids} \|";
	foreach ($fields as $field) {
	$key = $field->getKeyForConduit();
	$label = $field->getLabel();

	// TODO: Support generating and surfacing this information.
	$type = pht('TODO');
	$description = pht('TODO');

	$table[] = "\| `{$key}` \| {$label} \| `{$type}` \| {$description}";
	}
	$table = implode("\n", $table);
	$out[] = $table;


	$out[] = pht(<<<EOTEXT
	Result Order
	------------

	Use `order` to choose an ordering for the results. Either specify a single
	key from the builtin orders (these are a set of meaningful, high-level,
	human-readable orders) or specify a list of low-level columns.

	To use a high-level order, choose a builtin order from the table below
	and specify it like this:

	```lang=json
	{
	...
	"order": "newest",
	...
	}
	```

	These builtin orders are available:
	EOTEXT
	);

	$head_builtin = pht('Builtin Order');
	$head_description = pht('Description');
	$head_columns = pht('Columns');

	$orders = $query->getBuiltinOrders();

	$table = array();
	$table[] = "\| {$head_builtin} \| {$head_description} \| {$head_columns} \|";
	$table[] = '\|-----------------\|---------------------\|-----------------\|';
	foreach ($orders as $key => $order) {
	$name = $order['name'];
	$columns = implode(', ', $order['vector']);
	$table[] = "\| `{$key}` \| {$name} \| {$columns} \|";
	}
	$table = implode("\n", $table);
	$out[] = $table;

	$out[] = pht(<<<EOTEXT
	You can choose a low-level column order instead. This is an advanced feature.

	In your custom order: each column may only be specified once; each column may
	be prefixed with "-" to invert the order; the last column must be unique; and
	no column other than the last may be unique.

	To use a low-level order, choose a sequence of columns and specify them like
	this:

	```lang=json
	{
	...
	"order": ["color", "-name", "id"],
	...
	}
	```

	These low-level columns are available:
	EOTEXT
	);

	$head_column = pht('Column Key');
	$head_unique = pht('Unique');

	$columns = $query->getOrderableColumns();

	$table = array();
	$table[] = "\| {$head_column} \| {$head_unique} \|";
	$table[] = '\|----------------\|----------------\|';
	foreach ($columns as $key => $column) {
	$unique = idx($column, 'unique')
	? pht('Yes')
	: pht('No');

	$table[] = "\| `{$key}` \| {$unique} \|";
	}
	$table = implode("\n", $table);
	$out[] = $table;


	$out[] = pht(<<<EOTEXT
	Result Format
	-------------

	The result format is a dictionary with several fields:

	- `data`: Contains the actual results, as a list of dictionaries.
	- `query`: Details about the query which was issued.
	- `cursor`: Information about how to issue another query to get the next
	(or previous) page of results. See "Paging and Limits" below.

	EOTEXT
	);

	$out[] = pht(<<<EOTEXT
	Fields
	------

	The `data` field of the result contains a list of results. Each result has
	some metadata and a `fields` key, which contains the primary object fields.

	For example, the results may look something like this:

	```lang=json
	{
	...
	"data": [
	{
	"id": 123,
	"phid": "PHID-WXYZ-1111",
	"fields": {
	"name": "First Example Object",
	"authorPHID": "PHID-USER-2222"
	}
	},
	{
	"id": 124,
	"phid": "PHID-WXYZ-3333",
	"fields": {
	"name": "Second Example Object",
	"authorPHID": "PHID-USER-4444"
	}
	},
	...
	]
	...
	}
	```

	This result structure is standardized across all search methods, but the
	available fields differ from application to application.

	These are the fields available on this object type:

	EOTEXT
	);

	$specs = $engine->getAllConduitFieldSpecifications();

	$table = array();
	$table[] = "\| {$head_key} \| {$head_type} \| {$head_description} \|";
	$table[] = '\|-------------\|--------------\|---------------------\|';
	foreach ($specs as $key => $spec) {
	$type = idx($spec, 'type');
	$description = idx($spec, 'description');
	$table[] = "\| `{$key}` \| `{$type}` \| {$description} \|";
	}
	$table = implode("\n", $table);
	$out[] = $table;

	$out[] = pht(<<<EOTEXT
	Paging and Limits
	-----------------

	Queries are limited to returning 100 results at a time. If you want fewer
	results than this, you can use `limit` to specify a smaller limit.

	If you want more results, you'll need to make additional queries to retrieve
	more pages of results.

	The result structure contains a `cursor` key with information you'll need in
	order to fetch the next page. After an initial query, it will usually look
	something like this:

	```lang=json
	{
	...
	"cursor": {
	"limit": 100,
	"after": "1234",
	"before": null,
	"order": null
	}
	...
	}
	```

	The `limit` and `order` fields are describing the effective limit and order the
	query was executed with, and are usually not of much interest. The `after` and
	`before` fields give you cursors which you can pass when making another API
	call in order to get the next (or previous) page of results.

	To get the next page of results, repeat your API call with all the same
	parameters as the original call, but pass the `after` cursor you received from
	the first call in the `after` parameter when making the second call.

	If you do things correctly, you should get the second page of results, and
	a cursor structure like this:

	```lang=json
	{
	...
	"cursor": {
	"limit": 5,
	"after": "4567",
	"before": "7890",
	"order": null
	}
	...
	}
	```

	You can now continue to the third page of results by passing the new `after`
	cursor to the `after` parameter in your third call, or return to the previous
	page of results by passing the `before` cursor to the `before` parameter. This
	might be useful if you are rendering a web UI for a user and want to provide
	"Next Page" and "Previous Page" links.

	If `after` is `null`, there is no next page of results available. Likewise,
	if `before` is `null`, there are no previous results available.

	EOTEXT
	);

	$out = implode("\n\n", $out);
	return $out;
	}

	}
	diff --git a/src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php b/src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php
	index 8c7fafdc2a..344f22b3c4 100644
	--- a/src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php
	+++ b/src/applications/transactions/editengine/PhabricatorEditEngineAPIMethod.php
	@@ -1,202 +1,201 @@
	<?php

	abstract class PhabricatorEditEngineAPIMethod
	extends ConduitAPIMethod {

	abstract public function newEditEngine();

	public function getApplication() {
	$engine = $this->newEditEngine();
	$class = $engine->getEngineApplicationClass();
	return PhabricatorApplication::getByClass($class);
	}

	public function getMethodStatus() {
	return self::METHOD_STATUS_UNSTABLE;
	}

	public function getMethodStatusDescription() {
	return pht('ApplicationEditor methods are highly unstable.');
	}

	final protected function defineParamTypes() {
	return array(
	'transactions' => 'list<map<string, wild>>',
	'objectIdentifier' => 'optional id\|phid\|string',
	);
	}

	final protected function defineReturnType() {
	return 'map<string, wild>';
	}

	final protected function execute(ConduitAPIRequest $request) {
	$engine = $this->newEditEngine()
	->setViewer($request->getUser());

	return $engine->buildConduitResponse($request);
	}

	final public function getMethodDescription() {
	- // TODO: We don't currently have a real viewer in this method.
	- $viewer = PhabricatorUser::getOmnipotentUser();
	+ $viewer = $this->getViewer();

	$engine = $this->newEditEngine()
	->setViewer($viewer);

	$types = $engine->getConduitEditTypes();

	$out = array();

	$out[] = pht(<<<EOTEXT
	This is a standard ApplicationEditor method which allows you to create and
	modify objects by applying transactions.

	Each transaction applies one change to the object. For example, to create an
	object with a specific title or change the title of an existing object you might
	start by building a transaction like this:

	```lang=json, name=Example Single Transaction
	{
	"type": "title",
	"value": "New Object Title"
	}
	```

	By passing a list of transactions in the `transactions` parameter, you can
	apply a sequence of edits. For example, you'll often pass a value like this to
	create an object with several field values or apply changes to multiple fields:

	```lang=json, name=Example Transaction List
	[
	{
	"type": "title",
	"value": "New Object Title"
	},
	{
	"type": "body",
	"value": "New body text for the object."
	},
	{
	"type": "projects.add",
	"value": ["PHID-PROJ-1111", "PHID-PROJ-2222"]
	}
	]
	```

	Exactly which types of edits are available depends on the object you're editing.


	Creating Objects
	----------------

	To create an object, pass a list of `transactions` but leave `objectIdentifier`
	empty. This will create a new object with the initial field values you
	specify.


	Editing Objects
	---------------

	To edit an object, pass a list of `transactions` and specify an object to
	apply them to with `objectIdentifier`. This will apply the changes to the
	object.

	You may pass an ID (like `123`), PHID (like `PHID-WXYZ-abcdef...`), or
	monogram (like `T123`, for objects which have monograms).


	Return Type
	-----------

	WARNING: The structure of the return value from these methods is likely to
	change as ApplicationEditor evolves.

	Return values look something like this for now:

	```lang=json, name=Example Return Value
	{
	"object": {
	"phid": "PHID-XXXX-1111"
	},
	"transactions": [
	{
	"phid": "PHID-YYYY-1111",
	},
	{
	"phid": "PHID-YYYY-2222",
	}
	]
	}
	```

	The `object` key contains information about the object which was created or
	edited.

	The `transactions` key contains information about the transactions which were
	actually applied. For many reasons, the transactions which actually apply may
	be greater or fewer in number than the transactions you provided, or may differ
	in their nature in other ways.


	Edit Types
	==========

	This API method supports these edit types:
	EOTEXT
	);

	$key = pht('Key');
	$summary = pht('Summary');
	$description = pht('Description');
	$head_type = pht('Type');

	$table = array();
	$table[] = "\| {$key} \| {$summary} \|";
	$table[] = '\|--------\|----------------\|';
	foreach ($types as $type) {
	$edit_type = $type->getEditType();
	$edit_summary = $type->getSummary();
	$table[] = "\| `{$edit_type}` \| {$edit_summary} \|";
	}

	$out[] = implode("\n", $table);

	foreach ($types as $type) {
	$section = array();
	$section[] = pht('Edit Type: %s', $type->getEditType());
	$section[] = '---------';
	$section[] = null;
	$section[] = $type->getDescription();
	$section[] = null;
	$section[] = pht(
	'This edit generates transactions of type `%s` internally.',
	$type->getTransactionType());
	$section[] = null;

	$type_description = pht(
	'Use `%s` to select this edit type.',
	$type->getEditType());

	$value_type = $type->getValueType();
	if (!strlen($value_type)) {
	$value_type = '?';
	}

	$value_description = $type->getValueDescription();

	$table = array();
	$table[] = "\| {$key} \| {$head_type} \| {$description} \|";
	$table[] = '\|--------\|--------------\|----------------\|';
	$table[] = "\| `type` \| `const` \| {$type_description} \|";
	$table[] = "\| `value` \| `{$value_type}` \| {$value_description} \|";
	$section[] = implode("\n", $table);

	$out[] = implode("\n", $section);
	}

	$out = implode("\n\n", $out);
	return $out;
	}

	}

File Metadata

Mime Type: text/x-diff
Expires: Mon, Jul 28, 12:56 AM (1 w, 9 h ago)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 186292
Default Alt Text: (32 KB)

No OneTemporaryActions

View Options

File Metadata

Event Timeline

No OneTemporary
Actions