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

Return a human-readable field name.

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

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.

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.

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.

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 an index string which uniquely identifies this field.

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.

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

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

Sets the object this field belongs to.

Read object data into local field storage, if applicable.

Get the object this field belongs to.

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

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 a new, empty storage object. This should be a subclass of PhabricatorCustomFieldStorage which is bound to the application's database.

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).

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().

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

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 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.

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

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

Build and populate storage for a string index.

Build and populate storage for a numeric index.

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.

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

Append search controls to the interface.

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

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.

Return true to make this field available in Herald.

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

Get the field value for evaluation by Herald.

Get the available conditions for this field in Herald.

Get the Herald value type for the given condition.

TODO: It would be nice to remove this, but a lot of different code is bound together by it. Until everything is modernized, retaining the old field keys is the only reasonable way to update things one piece at a time.