Page MenuHomePhabricator
Diviner Phabricator Tech Docs PhabricatorProjectStandardCustomField

abstract class PhabricatorProjectStandardCustomField
Phabricator Technical Documentation (Projects)

This class is not documented.

Tasks

Building Applications with Custom Fields

Core Properties and Field Identity

  • public function getFieldKey() — Return a key which uniquely identifies this field, like "mycompany:dinosaur:count". Normally you should provide some level of namespacing to prevent collisions.
  • public function getFieldName() — Return a human-readable field name.
  • public function getFieldDescription() — Return a short, human-readable description of the field's behavior. This provides more context to administrators when they are customizing fields.
  • public function createFields($object) — Most field implementations are unique, in that one class corresponds to one field. However, some field implementations are general and a single implementation may drive several fields.
  • public function isFieldEnabled() — You can return `false` here if the field should not be enabled for any role. For example, it might depend on something (like an application or library) which isn't installed, or might have some global configuration which allows it to be disabled.
  • public function shouldEnableForRole($role) — Low level selector for field availability. Fields can appear in different roles (like an edit view, a list view, etc.), but not every field needs to appear everywhere. Fields that are disabled in a role won't appear in that context within applications.
  • public function canDisableField() — Allow administrators to disable this field. Most fields should allow this, but some are fundamental to the behavior of the application and can be locked down to avoid chaos, disorder, and the decline of civilization.
  • final public function getFieldIndex() — Return an index string which uniquely identifies this field.

Field Proxies

  • public function canSetProxy() — Proxies allow a field to use some other field's implementation for most of their behavior while still subclassing an application field. When a proxy is set for a field with @{method:setProxy}, all of its methods will call through to the proxy by default.

Contextual Data

  • final public function setObject($object) — Sets the object this field belongs to.
  • public function readValueFromObject($object) — Read object data into local field storage, if applicable.
  • final public function getObject() — Get the object this field belongs to.
  • final public function setViewer($viewer)
  • final public function getViewer()
  • final protected function requireViewer()

Rendering Utilities

Field Storage

  • public function shouldUseStorage() — Return true to use field storage.
  • public function newStorageObject()
  • public function getValueForStorage() — Return a serialized representation of the field value, appropriate for storing in auxiliary field storage. You must implement this method if you implement @{method:shouldUseStorage}.
  • public function setValueFromStorage($value) — Set the field's value given a serialized storage value. This is called when the field is loaded; if no data is available, the value will be null. You must implement this method if you implement @{method:shouldUseStorage}.

Integration with Edit Views

Integration with Property Views

Integration with List views

Integration with ApplicationSearch

  • public function shouldAppearInApplicationSearch() — Appearing in ApplicationSearch allows a field to be indexed and searched for.
  • public function buildFieldIndexes() — Return one or more indexes which this field can meaningfully query against to implement ApplicationSearch.
  • public function buildOrderIndex() — Return an index against which this field can be meaningfully ordered against to implement ApplicationSearch.
  • protected function newStringIndexStorage()
  • protected function newNumericIndexStorage()
  • protected function newStringIndex($value) — Build and populate storage for a string index.
  • protected function newNumericIndex($value) — Build and populate storage for a numeric index.
  • public function readApplicationSearchValueFromRequest($engine, $request) — Read a query value from a request, for storage in a saved query. Normally, this method should, e.g., read a string out of the request.
  • public function applyApplicationSearchConstraintToQuery($engine, $query, $value) — Constrain a query, given a field value. Generally, this method should use `with...()` methods to apply filters or other constraints to the query.
  • public function appendToApplicationSearchForm($engine, $form, $value) — Append search controls to the interface.

Integration with ApplicationTransactions

Integration with Transaction Mail

Integration with Global Search

Integration with Herald

Other Methods

conduit

Methods

public static function getObjectFields($object, $role)
Inherited

This method is not documented.
Parameters
PhabricatorCustomFieldInterface$object
$role
Return
wild

public static function getObjectField($object, $role, $field_key)
Inherited

This method is not documented.
Parameters
PhabricatorCustomFieldInterface$object
$role
$field_key
Return
wild

public static function buildFieldList($base_class, $spec, $object, $options)
Inherited

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

public function getFieldKey()
Inherited

PhabricatorCustomField

Return a key which uniquely identifies this field, like "mycompany:dinosaur:count". Normally you should provide some level of namespacing to prevent collisions.

Return
stringString which uniquely identifies this field.

public function getModernFieldKey()
Inherited

This method is not documented.
Return
wild

public function getFieldName()
Inherited

PhabricatorCustomField

Return a human-readable field name.

Return
stringHuman readable field name.

public function getFieldDescription()
Inherited

PhabricatorCustomField

Return a short, human-readable description of the field's behavior. This provides more context to administrators when they are customizing fields.

Return
string|nullOptional human-readable description.

public function createFields($object)
Inherited

PhabricatorCustomField

Most field implementations are unique, in that one class corresponds to one field. However, some field implementations are general and a single implementation may drive several fields.

For general implementations, the general field implementation can return multiple field instances here.

Parameters
object$objectThe object to create fields for.
Return
list<PhabricatorCustomField>List of fields.

public function isFieldEnabled()
Inherited

PhabricatorCustomField

You can return false here if the field should not be enabled for any role. For example, it might depend on something (like an application or library) which isn't installed, or might have some global configuration which allows it to be disabled.

Return
boolFalse to completely disable this field for all roles.

public function shouldEnableForRole($role)
Inherited

PhabricatorCustomField

Low level selector for field availability. Fields can appear in different roles (like an edit view, a list view, etc.), but not every field needs to appear everywhere. Fields that are disabled in a role won't appear in that context within applications.

Normally, you do not need to override this method. Instead, override the methods specific to roles you want to enable. For example, implement shouldUseStorage()() to activate the 'storage' role.

Parameters
$role
Return
boolTrue to enable the field for the given role.

public function canDisableField()
Inherited

PhabricatorCustomField

Allow administrators to disable this field. Most fields should allow this, but some are fundamental to the behavior of the application and can be locked down to avoid chaos, disorder, and the decline of civilization.

Return
boolFalse to prevent this field from being disabled through configuration.

public function shouldDisableByDefault()
Inherited

This method is not documented.
Return
wild

final public function getFieldIndex()
Inherited

PhabricatorCustomField

Return an index string which uniquely identifies this field.

Return
stringIndex string which uniquely identifies this field.

public function canSetProxy()
Inherited

PhabricatorCustomField

Proxies allow a field to use some other field's implementation for most of their behavior while still subclassing an application field. When a proxy is set for a field with setProxy(), all of its methods will call through to the proxy by default.

This is most commonly used to implement configuration-driven custom fields using PhabricatorStandardCustomField.

This method must be overridden to return true before a field can accept proxies.

Return
boolTrue if you can @{method:setProxy} this field.

final public function setProxy($proxy)
Inherited

PhabricatorCustomField

Set the proxy implementation for this field. See canSetProxy() for discussion of field proxies.

Parameters
PhabricatorCustomField$proxyField implementation.
Return
this

final public function getProxy()
Inherited

PhabricatorCustomField

Get the field's proxy implementation, if any. For discussion, see canSetProxy().

Return
PhabricatorCustomField|nullProxy field, if one is set.

final public function setObject($object)
Inherited

PhabricatorCustomField

Sets the object this field belongs to.

Parameters
PhabricatorCustomFieldInterface$objectThe object this field belongs to.
Return
this

public function readValueFromObject($object)
Inherited

PhabricatorCustomField

Read object data into local field storage, if applicable.

Parameters
PhabricatorCustomFieldInterface$objectThe object this field belongs to.
Return
this

final public function getObject()
Inherited

PhabricatorCustomField

Get the object this field belongs to.

Return
PhabricatorCustomFieldInterfaceThe object this field belongs to.

protected function didSetObject($object)
Inherited

PhabricatorCustomField

This is a hook, primarily for subclasses to load object data.

Parameters
PhabricatorCustomFieldInterface$object
Return
PhabricatorCustomFieldInterfaceThe object this field belongs to.

final public function setViewer($viewer)
Inherited

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

final public function getViewer()
Inherited

This method is not documented.
Return
wild

final protected function requireViewer()
Inherited

This method is not documented.
Return
wild

protected function renderHandleList($handles)
Inherited

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

public function shouldUseStorage()
Inherited

PhabricatorCustomField

Return true to use field storage.

Fields which can be edited by the user will most commonly use storage, while some other types of fields (for instance, those which just display information in some stylized way) may not. Many builtin fields do not use storage because their data is available on the object itself.

If you implement this, you must also implement getValueForStorage() and setValueFromStorage().

Return
boolTrue to use storage.

public function newStorageObject()

PhabricatorCustomField

Return a new, empty storage object. This should be a subclass of PhabricatorCustomFieldStorage which is bound to the application's database.

PhabricatorProjectStandardCustomField
This method is not documented.
Return
PhabricatorCustomFieldStorageNew empty storage object.

public function getValueForStorage()
Inherited

PhabricatorCustomField

Return a serialized representation of the field value, appropriate for storing in auxiliary field storage. You must implement this method if you implement shouldUseStorage().

If the field value is a scalar, it can be returned unmodiifed. If not, it should be serialized (for example, using JSON).

Return
stringSerialized field value.

public function setValueFromStorage($value)
Inherited

PhabricatorCustomField

Set the field's value given a serialized storage value. This is called when the field is loaded; if no data is available, the value will be null. You must implement this method if you implement shouldUseStorage().

Usually, the value can be loaded directly. If it isn't a scalar, you'll need to undo whatever serialization you applied in getValueForStorage().

Parameters
string|null$valueSerialized field representation (from @{method:getValueForStorage}) or null if no value has ever been stored.
Return
this

public function didSetValueFromStorage()
Inherited

This method is not documented.
Return
wild

public function shouldAppearInApplicationSearch()
Inherited

PhabricatorCustomField

Appearing in ApplicationSearch allows a field to be indexed and searched for.

Return
boolTrue to appear in ApplicationSearch.

public function buildFieldIndexes()
Inherited

PhabricatorCustomField

Return one or more indexes which this field can meaningfully query against to implement ApplicationSearch.

Normally, you should build these using newStringIndex() and newNumericIndex(). For example, if a field holds a numeric value it might return a single numeric index:

return array($this->newNumericIndex($this->getValue()));

If a field holds a more complex value (like a list of users), it might return several string indexes:

$indexes = array();
foreach ($this->getValue() as $phid) {
  $indexes[] = $this->newStringIndex($phid);
}
return $indexes;
Return
list<PhabricatorCustomFieldIndexStorage>List of indexes.

public function buildOrderIndex()
Inherited

PhabricatorCustomField

Return an index against which this field can be meaningfully ordered against to implement ApplicationSearch.

This should be a single index, normally built using newStringIndex() and newNumericIndex().

The value of the index is not used.

Return null from this method if the field can not be ordered.

Return
PhabricatorCustomFieldIndexStorageA single index to order by.

protected function newStringIndexStorage()

PhabricatorCustomField

Build a new empty storage object for storing string indexes. Normally, this should be a concrete subclass of PhabricatorCustomFieldStringIndexStorage.

PhabricatorProjectStandardCustomField
This method is not documented.
Return
PhabricatorCustomFieldStringIndexStorageStorage object.

protected function newNumericIndexStorage()

PhabricatorCustomField

Build a new empty storage object for storing string indexes. Normally, this should be a concrete subclass of PhabricatorCustomFieldStringIndexStorage.

PhabricatorProjectStandardCustomField
This method is not documented.
Return
PhabricatorCustomFieldStringIndexStorageStorage object.

protected function newStringIndex($value)
Inherited

PhabricatorCustomField

Build and populate storage for a string index.

Parameters
string$valueString to index.
Return
PhabricatorCustomFieldStringIndexStoragePopulated storage.

protected function newNumericIndex($value)
Inherited

PhabricatorCustomField

Build and populate storage for a numeric index.

Parameters
string$valueNumeric value to index.
Return
PhabricatorCustomFieldNumericIndexStoragePopulated storage.

public function readApplicationSearchValueFromRequest($engine, $request)
Inherited

PhabricatorCustomField

Read a query value from a request, for storage in a saved query. Normally, this method should, e.g., read a string out of the request.

Parameters
PhabricatorApplicationSearchEngine$engineEngine building the query.
AphrontRequest$requestRequest to read from.
Return
wild

public function applyApplicationSearchConstraintToQuery($engine, $query, $value)
Inherited

PhabricatorCustomField

Constrain a query, given a field value. Generally, this method should use with...() methods to apply filters or other constraints to the query.

Parameters
PhabricatorApplicationSearchEngine$engineEngine executing the query.
PhabricatorCursorPagedPolicyAwareQuery$queryQuery to constrain.
wild$valueConstraint provided by the user.
Return
void

public function appendToApplicationSearchForm($engine, $form, $value)
Inherited

PhabricatorCustomField

Append search controls to the interface.

Parameters
PhabricatorApplicationSearchEngine$engineEngine constructing the form.
AphrontFormView$formThe form to update.
wild$valueValue from the saved query.
Return
void

public function shouldAppearInApplicationTransactions()
Inherited

PhabricatorCustomField

Appearing in ApplicationTrasactions allows a field to be edited using standard workflows.

Return
boolTrue to appear in ApplicationTransactions.

public function getApplicationTransactionType()
Inherited

This method is not documented.
Return
wild

public function getApplicationTransactionMetadata()
Inherited

This method is not documented.
Return
wild

public function getOldValueForApplicationTransactions()
Inherited

This method is not documented.
Return
wild

public function getNewValueForApplicationTransactions()
Inherited

This method is not documented.
Return
wild

public function setValueFromApplicationTransactions($value)
Inherited

This method is not documented.
Parameters
$value
Return
wild

public function getNewValueFromApplicationTransactions($xaction)
Inherited

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function getApplicationTransactionHasEffect($xaction)
Inherited

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function applyApplicationTransactionInternalEffects($xaction)
Inherited

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function getApplicationTransactionRemarkupBlocks($xaction)
Inherited

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function applyApplicationTransactionExternalEffects($xaction)
Inherited

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function validateApplicationTransactions($editor, $type, $xactions)
Inherited

PhabricatorCustomField

Validate transactions for an object. This allows you to raise an error when a transaction would set a field to an invalid value, or when a field is required but no transactions provide value.

Parameters
PhabricatorLiskDAO$editorEditor applying the transactions.
string$typeTransaction type. This type is always `PhabricatorTransactions::TYPE_CUSTOMFIELD`, it is provided for convenience when constructing exceptions.
list<PhabricatorApplicationTransaction>$xactionsTransactions being applied, which may be empty if this field is not being edited.
Return
list<PhabricatorApplicationTransactionValidationError>Validation errors.

public function getApplicationTransactionTitle($xaction)
Inherited

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function getApplicationTransactionTitleForFeed($xaction)
Inherited

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function getApplicationTransactionHasChangeDetails($xaction)
Inherited

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function getApplicationTransactionChangeDetails($xaction, $viewer)
Inherited

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
PhabricatorUser$viewer
Return
wild

public function getApplicationTransactionRequiredHandlePHIDs($xaction)
Inherited

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function shouldHideInApplicationTransactions($xaction)
Inherited

This method is not documented.
Parameters
PhabricatorApplicationTransaction$xaction
Return
wild

public function shouldAppearInTransactionMail()
Inherited

This method is not documented.
Return
wild

public function updateTransactionMailBody($body, $editor, $xactions)
Inherited

This method is not documented.
Parameters
PhabricatorMetaMTAMailBody$body
PhabricatorApplicationTransactionEditor$editor
array$xactions
Return
wild

public function getEditEngineFields($engine)
Inherited

This method is not documented.
Parameters
PhabricatorEditEngine$engine
Return
wild

protected function newEditField()
Inherited

This method is not documented.
Return
wild

protected function newStandardEditField()
Inherited

This method is not documented.
Return
wild

protected function getBulkEditLabel()
Inherited

This method is not documented.
Return
wild

public function getBulkParameterType()
Inherited

This method is not documented.
Return
wild

protected function newBulkParameterType()
Inherited

This method is not documented.
Return
wild

protected function getHTTPParameterType()
Inherited

This method is not documented.
Return
wild

public function shouldAppearInEditView()
Inherited

This method is not documented.
Return
wild

public function shouldAppearInEditEngine()
Inherited

This method is not documented.
Return
wild

public function readValueFromRequest($request)
Inherited

This method is not documented.
Parameters
AphrontRequest$request
Return
wild

public function getRequiredHandlePHIDsForEdit()
Inherited

This method is not documented.
Return
wild

public function getInstructionsForEdit()
Inherited

This method is not documented.
Return
wild

public function renderEditControl($handles)
Inherited

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

public function shouldAppearInPropertyView()
Inherited

This method is not documented.
Return
wild

public function renderPropertyViewLabel()
Inherited

This method is not documented.
Return
wild

public function renderPropertyViewValue($handles)
Inherited

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

public function getStyleForPropertyView()
Inherited

This method is not documented.
Return
wild

public function getIconForPropertyView()
Inherited

This method is not documented.
Return
wild

public function getRequiredHandlePHIDsForPropertyView()
Inherited

This method is not documented.
Return
wild

public function shouldAppearInListView()
Inherited

This method is not documented.
Return
wild

public function renderOnListItem($view)
Inherited

This method is not documented.
Parameters
PHUIObjectItemView$view
Return
wild

public function shouldAppearInGlobalSearch()
Inherited

This method is not documented.
Return
wild

public function updateAbstractDocument($document)
Inherited

This method is not documented.
Parameters
PhabricatorSearchAbstractDocument$document
Return
wild

public function shouldAppearInDataExport()
Inherited

This method is not documented.
Return
wild

public function newExportField()
Inherited

This method is not documented.
Return
wild

public function newExportData()
Inherited

This method is not documented.
Return
wild

protected function newExportFieldType()
Inherited

This method is not documented.
Return
wild

public function shouldAppearInConduitDictionary()
Inherited

This method is not documented.
Return
wild

public function getConduitDictionaryValue()
Inherited

This method is not documented.
Return
wild

public function shouldAppearInConduitTransactions()
Inherited

This method is not documented.
Return
wild

public function getConduitSearchParameterType()
Inherited

This method is not documented.
Return
wild

protected function newConduitSearchParameterType()
Inherited

This method is not documented.
Return
wild

public function getConduitEditParameterType()
Inherited

This method is not documented.
Return
wild

protected function newConduitEditParameterType()
Inherited

This method is not documented.
Return
wild

public function getCommentAction()
Inherited

This method is not documented.
Return
wild

protected function newCommentAction()
Inherited

This method is not documented.
Return
wild

public function shouldAppearInHerald()
Inherited

PhabricatorCustomField

Return true to make this field available in Herald.

Return
boolTrue to expose the field in Herald.

public function getHeraldFieldName()
Inherited

PhabricatorCustomField

Get the name of the field in Herald. By default, this uses the normal field name.

Return
stringHerald field name.

public function getHeraldFieldValue()
Inherited

PhabricatorCustomField

Get the field value for evaluation by Herald.

Return
wildField value.

public function getHeraldFieldConditions()
Inherited

PhabricatorCustomField

Get the available conditions for this field in Herald.

Return
list<const>List of Herald condition constants.

public function getHeraldFieldValueType($condition)
Inherited

PhabricatorCustomField

Get the Herald value type for the given condition.

Parameters
const$conditionHerald condition constant.
Return
const|nullHerald value type, or null to use the default.

public function getHeraldFieldStandardType()
Inherited

This method is not documented.
Return
wild

public function getHeraldDatasource()
Inherited

This method is not documented.
Return
wild

public function shouldAppearInHeraldActions()
Inherited

This method is not documented.
Return
wild

public function getHeraldActionName()
Inherited

This method is not documented.
Return
wild

public function getHeraldActionStandardType()
Inherited

This method is not documented.
Return
wild

public function getHeraldActionDescription($value)
Inherited

This method is not documented.
Parameters
$value
Return
wild

public function getHeraldActionEffectDescription($value)
Inherited

This method is not documented.
Parameters
$value
Return
wild

public function getHeraldActionDatasource()
Inherited

This method is not documented.
Return
wild

private static function adjustCustomFieldsForObjectSubtype($object, $role, $fields)
Inherited

This method is not documented.
Parameters
PhabricatorCustomFieldInterface$object
$role
array$fields
Return
wild
This method is not documented.
Return
wild