Diviner Arcanist Tech Docs PhutilClassMapQuery

final class PhutilClassMapQuery
Arcanist Technical Documentation ()

Load a map of concrete subclasses of some abstract parent class.

libphutil is extensively modular through runtime introspection of class maps. This method makes querying class maps easier.

There are several common patterns used with modular class maps:

A getUniqueKey() method which returns a unique scalar key identifying the class.
An expandVariants() method which potentially returns multiple instances of the class with different configurations.
A getSortName() method which sorts results.
Caching of the map.

This class provides support for these mechanisms.

Using the unique key mechanism with setUniqueMethod() allows you to use a more human-readable, storage-friendly key to identify objects, allows classes to be freely renamed, and enables variant expansion.

Using the expansion mechanism with setExpandMethod() allows you to have multiple similar modular instances, or configuration-driven instances.

Even if they have no immediate need for either mechanism, class maps should generally provide unique keys in their initial design so they are more flexible later on. Adding unique keys later can require database migrations, while adding an expansion mechanism is trivial if a class map already has unique keys.

This class automatically caches class maps and does not need to be wrapped in caching logic.

Tasks

Configuring the Query

public function setAncestorClass($class) — Set the ancestor class or interface name to load the concrete descendants of.
public function setUniqueMethod($unique_method, $filter_null) — Provide a method to select a unique key for each instance.
public function setExpandMethod($expand_method) — Provide a method to expand each concrete subclass into available instances.
public function setSortMethod($sort_method) — Provide a method to sort the final map.
public function setFilterMethod($filter_method) — Provide a method to filter the map.

Executing the Query

public function execute() — Execute the query as configured.
public static function deleteCaches() — Delete all class map caches.
private function loadMap() — Generate the core query results.

Managing the Map Cache

public function getCacheKey() — Return a cache key for this query.

Other Methods

public function __get($name)
public function __set($name, $value)
public function current()
public function key()
public function next()
public function rewind()
public function valid()
private function throwOnAttemptedIteration()
public function getPhobjectClassConstant($key, $byte_limit) — Read the value of a class constant.
public function setContinueOnFailure($continue)

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	$key	Name of the constant.
int\|null	$byte_limit	Maximum number of bytes permitted in the value.

Return

string

Value of the constant.

public function setAncestorClass($class)

Set the ancestor class or interface name to load the concrete descendants of.

Parameters

string

$class

Ancestor class or interface name.

Return

this

public function setUniqueMethod($unique_method, $filter_null)

Provide a method to select a unique key for each instance.

If you provide a method here, the map will be keyed with these values, instead of with class names. Exceptions will be raised if entries are not unique.

You must provide a method here to use setExpandMethod().

Parameters

string	$unique_method	Name of the unique key method.
bool	$filter_null	If true, then classes which return `null` will be filtered from the results.

Return

this

public function setExpandMethod($expand_method)

Provide a method to expand each concrete subclass into available instances.

With some class maps, each class is allowed to provide multiple entries in the map by returning alternatives from some method with a default implementation like this:

public function generateVariants() {
  return array($this);
}

For example, a "color" class may really generate and configure several instances in the final class map:

public function generateVariants() {
  return array(
    self::newColor('red'),
    self::newColor('green'),
    self::newColor('blue'),
  );
}

This allows multiple entires in the final map to share an entire implementation, rather than requiring that they each have their own unique subclass.

This pattern is most useful if several variants are nearly identical (so the stub subclasses would be essentially empty) or the available variants are driven by configuration.

If a class map uses this pattern, it must also provide a unique key for each instance with setUniqueMethod().

Parameters

string

$expand_method

Name of the expansion method.

Return

this

public function setSortMethod($sort_method)

Provide a method to sort the final map.

The map will be sorted using msort() and passing this method name.

Parameters

string

$sort_method

Name of the sorting method.

Return

this

public function setFilterMethod($filter_method)

Provide a method to filter the map.

Parameters

string

$filter_method

Name of the filtering method.

Return

this

public function setContinueOnFailure($continue)

This method is not documented.

Parameters

$continue

Return

wild

public function execute()

Execute the query as configured.

Return

map<string, object>

Realized class map.

public static function deleteCaches()

Delete all class map caches.

Return

void

private function loadMap()

Generate the core query results.

This method is used to fill the cache.

Return

map<string, object>

Realized class map.

public function getCacheKey()

Return a cache key for this query.

Return

string

Cache key.

Defined: src/symbols/PhutilClassMapQuery.php:40
Extends: Phobject

final class PhutilClassMapQueryArcanist Technical Documentation ()

Tasks

Configuring the Query

Executing the Query

Managing the Map Cache

Other Methods

Methods

public function __get($name)Inherited

public function __set($name, $value)Inherited

public function current()Inherited

public function key()Inherited

public function next()Inherited

public function rewind()Inherited

public function valid()Inherited

private function throwOnAttemptedIteration()Inherited

public function getPhobjectClassConstant($key, $byte_limit)Inherited

public function setAncestorClass($class)

public function setUniqueMethod($unique_method, $filter_null)

public function setExpandMethod($expand_method)

public function setSortMethod($sort_method)

public function setFilterMethod($filter_method)

public function setContinueOnFailure($continue)

public function execute()

public static function deleteCaches()

private function loadMap()

public function getCacheKey()

final class PhutilClassMapQuery
Arcanist Technical Documentation ()

public function __get($name)
Inherited

public function __set($name, $value)
Inherited

public function current()
Inherited

public function key()
Inherited

public function next()
Inherited

public function rewind()
Inherited

public function valid()
Inherited

private function throwOnAttemptedIteration()
Inherited

public function getPhobjectClassConstant($key, $byte_limit)
Inherited