Page MenuHomePhorge
Files F2895150

DiagramSearchConduitAPIMethod.php
No OneTemporary
Actions

DiagramSearchConduitAPIMethod.php
View Options

<?php
final class DiagramSearchConduitAPIMethod extends ConduitAPIMethod {
/**
* Name of the Conduit API method.
* This method should return a string that represents the name of the method.
* The method name is used to identify the method when calling it via the
* Conduit API.
*/
public function getAPIMethodName() {
return 'diagram.search';
}
/**
* Defines the input parameters for this API.
* This method should return an associative array where the keys are
* the names of the parameters and the values are strings that describe
* the types of the parameters.
* The parameter types are used for documentation purposes and are displayed
* on the documentation page for the method to help users understand what
* kind of data they can pass to the method when calling it.
*/
protected function defineParamTypes() {
return array(
'constraints' => 'optional map<string, wild>',
'attachments' => 'optional map<string, bool>',
'order' => 'optional string',
'before' => 'optional int',
'after' => 'optional int',
'limit' => 'optional int',
);
}
/**
* This method should return a string that describes the type of data that
* the method returns.
* The return type is used for documentation purposes and is displayed on the
* documentation page for the method to help users understand what kind of
* data they can expect to receive when calling the method.
*/
protected function defineReturnType() {
return 'list<dict>';
}
/**
* The execute method is the core of your Conduit API method and is where
* you implement the logic that performs the desired operation.
*
* The execute method should return the result of the operation in a
* format that can be serialized as JSON.
* The result will be sent back to the client as the response to the API
* request.
*/
protected function execute(ConduitAPIRequest $request) {
$viewer = $request->getUser();
$constraints = $request->getValue('constraints', array());
$attachments = $request->getValue('attachments', array());
$order = $request->getValue('order');
$before = $request->getValue('before');
$after = $request->getValue('after');
$limit = $request->getValue('limit');
if (!$order) {
$order = "newest";
}
if (!$limit || $limit > 100 || $limit < 1) {
$limit = 100; // maximum limit
}
$query = new PhabricatorDiagramVersionQuery();
$query->setViewer($viewer);
if (isset($constraints['ids'])) {
$query->withDiagramIDs($constraints['ids']);
}
if (isset($constraints['createdStart'])) {
$query->withModifiedAfter($constraints['createdStart']);
}
if (isset($constraints['createdEnd'])) {
$query->withModifiedBefore($constraints['createdEnd']);
}
if ($order) {
$query->setOrder($order);
}
// Create a new AphrontCursorPagerView object to paginate the results.
$pager = new AphrontCursorPagerView();
$pager->setPageSize($limit);
if ($after) {
$pager->setAfterID($after);
}
if ($before) {
$pager->setBeforeID($before);
}
// execute query
$diagrams = $query->executeWithCursorPager($pager);
$results = array();
foreach ($diagrams as $diagram) {
$result = array(
'id' => $diagram->getID(),
'phid' => $diagram->getPHID(),
'fields' => array(
'authorPHID' => $diagram->getAuthorPHID(),
'byteSize' => $diagram->getByteSize(),
'dataURI' => $diagram->getDataURI(),
'dateModified' => $diagram->getDateModified(),
'viewPolicy' => $diagram->getViewPolicy(),
'editPolicy' => $diagram->getEditPolicy()
)
);
if (isset($attachments['includeData']) && $attachments['includeData']) {
$result['fields']['data'] = $diagram->getBase64Data();
}
if (isset($attachments['includeVersion']) && $attachments['includeVersion']) {
$result['fields']['version'] = $diagram->getVersion();
}
$results[] = $result;
}
return array(
'data' => $results,
'cursor' => array(
'limit' => $pager->getPageSize(),
'after' => $pager->getNextPageID(),
'before' => $pager->getPrevPageID(),
'order' => $order
)
);
}
/**
* Descriptive text what this Conduit API method does
* This method should return a string that describes what the method does.
* The method description is used for documentation purposes and is
* displayed on the documentation page for the method to help users
* understand what the method does and how to use it.
*/
public function getMethodDescription() {
return pht('Search for diagrams.');
}
/**
* Generates custom documentation pages for this Conduit API method.
* This method should return an array of PhabricatorDocumentationBoxPage
* objects representing the custom documentation pages you want to add for
* the method.
* Each PhabricatorDocumentationBoxPage object represents a single
* documentation page and includes a title and content.
*/
public function newDocumentationPages(PhabricatorUser $viewer) {
$pages = array();
// create different chapters
$pages[] = $this->getDocumentationAttachments($viewer);
$pages[] = $this->getDocumentationObjectFields($viewer);
$pages[] = $this->getDocumentationConstraints($viewer);
$pages[] = $this->getDocumentationResultOrder($viewer);
$pages[] = $this->getDocumentationPagingAndLimits($viewer);
return $pages;
}
/**
* Creates the documentation chapter about Attachments
*/
public function getDocumentationAttachments(PhabricatorUser $viewer) {
// set title and content of 'Attachments' documentation box
$title = pht('Attachments');
$content = pht(<<<EOREMARKUP
By default, only basic information about objects is returned.
If you want more extensive information, you can use available
attachments to get more information in the results (like includeData).
Generally, requesting more information means the query executes more
slowly and returns more data (in some cases, much more data).
You should normally request only the data you need.
To request extra data, specify which attachments you want in the attachments parameter:
``` lang=json, name=Example Attachments Request
{
...
"attachments": {
"includeData": true
},
...
}
```
This example specifies that results should include the base64-formatted
content of the diagrams. In the return value, each object will now have
this information filled out in the corresponding attachments value:
``` lang=json, name=Example Attachments Result
{
"0": {
"id": "7",
"phid": "PHID-DGVN-hubmg6vge3srelgo3jj6",
"fields": {
"authorPHID": "PHID-USER-hmlbd2wfegzjhbpbnoc7",
"byteSize": "3152",
"dataURI": "http://phorge.local/diagram/data/PHID-DGVN-hubmg6vge3srelgo3jj6",
"dateModified": "1688493034",hubmg6vge3srelgo3jj6
"viewPolicy": "users",
"editPolicy": "PHID-USER-hmlbd2wfegzjhbpbnoc7",
"data": "iVBORw0KGg...K5CYII="
}
},
...
}
```
These are the available fields:
| Key | Type | Description
| -------------- | --------------- | ---
| includeData | Include Data | Include the image content of the diagrams in the search results.
| includeVersion | Include Version | Include the version number of the diagrams in the search results.
EOREMARKUP
);
// format content
$content = $this->newRemarkupDocumentationView($content);
// create documentation box
$page = $this->newDocumentationBoxPage(
$viewer,
$title,
$content
);
// set icon and anchor of documentation box for navigation menu on the left
$page->setAnchor('attachments');
$page->setIconIcon('fa-cubes');
return $page;
}
/**
* Creates the documentation chapter about Constraints
*/
public function getDocumentationConstraints(PhabricatorUser $viewer) {
// set title and content of 'Constraints' documentation box
$title = pht('Constraints');
$content = pht(<<<EOREMARKUP
You can apply custom constraints by passing a dictionary in constraints.
This will let you search for specific sets of diagrams (for example, you
may want show only diagrams within a certain period).
``` lang=json,name=Example Custom Constraints
{
...
"constraints": {
"ids": [1, 2, 5],
"createdStart": 1688493034,
...
},
...
}
```
This method supports the following constraints:
| Key | Label | Type | Description
| ------------ | -------------- | --------- | ---
| ids | IDs | list<int> | Search for diagrams with specific IDs.
| createdStart | Created After | epoch | Search for diagrams created on or after a specific date.
| createdEnd | Created Before | epoch | Search for diagrams created on or before a specific date.
EOREMARKUP
);
// format content
$content = $this->newRemarkupDocumentationView($content);
// create documentation box
$page = $this->newDocumentationBoxPage(
$viewer,
$title,
$content
);
// set icon and anchor of documentation box for navigation menu on the left
$page->setAnchor('constraints');
$page->setIconIcon('fa-filter');
return $page;
}
/**
* Creates the documentation chapter about Object Fields
*/
public function getDocumentationObjectFields(PhabricatorUser $viewer) {
// set title and content of 'Object Fields' documentation box
$title = pht('Object Fields');
$content = pht(<<<EOREMARKUP
Diagrams matching your query are returned as a list of dictionaries in the
data property of the results. Each dictionary has some metadata and a
fields key, which contains the information about the diagram that most
callers will be interested in.
For example, the results may look something like this:
``` lang=json, name=Example Attachments Result
{
"0": {
"id": "7",
"phid": "PHID-DGVN-hubmg6vge3srelgo3jj6",
"fields": {
"authorPHID": "PHID-USER-hmlbd2wfegzjhbpbnoc7",
"byteSize": "3152",
"dataURI": "http://phorge.local/diagram/data/PHID-DGVN-hubmg6vge3srelgo3jj6",
"dateModified": "1688493034",
"viewPolicy": "users",
"editPolicy": "PHID-USER-hmlbd2wfegzjhbpbnoc7",
}
},
...
}
```
These are the available fields:
| Key | Type | Description
| -------------- | --------------- | ---
| authorPHID | phid | PHID of the author of the diagram
| byteSize | int | Size of the diagram in bytes
| data | string | Base64 formatted content of diagram image
| dataURI | uri | URL to diagram image
| dateModified | int | Timestamp when diagram was last modified
| version | int | Version number of diagram
EOREMARKUP
);
// format content
$content = $this->newRemarkupDocumentationView($content);
// create documentation box
$page = $this->newDocumentationBoxPage(
$viewer,
$title,
$content
);
// set icon and anchor of documentation box for navigation menu on the left
$page->setAnchor('fields');
$page->setIconIcon('fa-cube');
return $page;
}
/**
* Creates the documentation chapter about Result Ordering
*/
public function getDocumentationPagingAndLimits(PhabricatorUser $viewer) {
// set title and content of 'Object Fields' documentation box
$title = pht('Paging and Limits');
$content = pht(<<<EOREMARKUP
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 of results.
After an initial query, it will usually look something like this:
``` lang=json, name=Example Cursor Result
{
...
"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, name=Second Result Page
{
...
"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.
EOREMARKUP
);
// format content
$content = $this->newRemarkupDocumentationView($content);
// create documentation box
$page = $this->newDocumentationBoxPage(
$viewer,
$title,
$content
);
// set icon and anchor of documentation box for navigation menu on the left
$page->setAnchor('paging');
$page->setIconIcon('fa-clone');
return $page;
}
/**
* Creates the documentation chapter about Result Ordering
*/
public function getDocumentationResultOrder(PhabricatorUser $viewer) {
// set title and content of 'Object Fields' documentation box
$title = pht('Result Ordering');
$content = pht(<<<EOREMARKUP
Use `order` to choose an ordering for the results.
Choose a builtin order from the table below and specify it like this:
``` lang=json, name=Choosing a Result Order
{
...
"order": "newest",
...
}
```
These builtin orders are available:
| Key | Description
| ------ | ---
| newest | Creation (Newest First)
| oldest | Creation (Oldest First)
EOREMARKUP
);
// format content
$content = $this->newRemarkupDocumentationView($content);
// create documentation box
$page = $this->newDocumentationBoxPage(
$viewer,
$title,
$content
);
// set icon and anchor of documentation box for navigation menu on the left
$page->setAnchor('ordering');
$page->setIconIcon('fa-sort-numeric-asc');
return $page;
}
}

File Metadata

Mime Type
text/x-php
Expires
Jan 19 2025, 21:00 (6 w, 1 d ago)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
1124125
Default Alt Text
DiagramSearchConduitAPIMethod.php (14 KB)

Event Timeline

Content licensed under Creative Commons Attribution-ShareAlike 4.0 (CC-BY-SA) unless otherwise noted; code licensed under Apache 2.0 or other open source licenses. · CC BY-SA 4.0 · Apache 2.0