Page MenuHomePhorge

final class PhutilClassMapQuery
libphutil 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

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$keyName of the constant.
int|null$byte_limitMaximum number of bytes permitted in the value.
Return
stringValue of the constant.

public function setAncestorClass($class)

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

Parameters
string$classAncestor 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_methodName of the unique key method.
bool$filter_nullIf 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_methodName 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_methodName of the sorting method.
Return
this

public function setFilterMethod($filter_method)

Provide a method to filter the map.

Parameters
string$filter_methodName 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
stringCache key.