Page MenuHomePhabricator

final class PhutilSymbolLoader
libphutil Technical Documentation ()

Query and load Phutil classes, interfaces and functions.

PhutilSymbolLoader is a query object which selects symbols which satisfy certain criteria, and optionally loads them. For instance, to load all classes in a library:

$symbols = id(new PhutilSymbolLoader())
  ->setType('class')
  ->setLibrary('example')
  ->selectAndLoadSymbols();

When you execute the loading query, it returns a dictionary of matching symbols:

array(
  'class$Example' => array(
    'type'    => 'class',
    'name'    => 'Example',
    'library' => 'libexample',
    'where'   => 'examples/example.php',
  ),
  // ... more ...
);

The library and where keys show where the symbol is defined. The type and name keys identify the symbol itself.

NOTE: This class must not use libphutil functions, including id() and idx().

Tasks

Configuring the Query

  • public function setType($type) — Select the type of symbol to load, either `class`, `function` or `interface`.
  • public function setLibrary($library) — Restrict the symbol query to a specific library; only symbols from this library will be loaded.
  • public function setPathPrefix($path) — Restrict the symbol query to a specific path prefix; only symbols defined in files below that path will be selected.
  • public function setName($name) — Restrict the symbol query to a single symbol name, e.g. a specific class or function name.
  • public function setAncestorClass($base) — Restrict the symbol query to only descendants of some class. This will strictly select descendants, the base class will not be selected. This implies loading only classes.
  • public function setConcreteOnly($concrete) — Restrict the symbol query to only concrete symbols; this will filter out abstract classes.

Loading Symbols

  • public function selectAndLoadSymbols() — Execute the query and select matching symbols, then load them so they can be used.
  • public function selectSymbolsWithoutLoading() — Execute the query and select matching symbols, but do not load them. This will perform slightly better if you are only interested in the existence of the symbols and don't plan to use them; otherwise, use @{method:selectAndLoadSymbols}.

Internals

Other Methods

  • public function setContinueOnFailure($continue)
  • public function loadObjects($argv) — Select symbols matching the query and then instantiate them, returning concrete objects. This is a convenience method which simplifies symbol handling if you are only interested in building objects.

Methods

public function setType($type)

Select the type of symbol to load, either class, function or interface.

Parameters
string$typeType of symbol to load.
Return
this

public function setLibrary($library)

Restrict the symbol query to a specific library; only symbols from this library will be loaded.

Parameters
string$libraryLibrary name.
Return
this

public function setPathPrefix($path)

Restrict the symbol query to a specific path prefix; only symbols defined in files below that path will be selected.

Parameters
string$pathPath relative to library root, like "apps/cheese/".
Return
this

public function setName($name)

Restrict the symbol query to a single symbol name, e.g. a specific class or function name.

Parameters
string$nameSymbol name.
Return
this

public function setAncestorClass($base)

Restrict the symbol query to only descendants of some class. This will strictly select descendants, the base class will not be selected. This implies loading only classes.

Parameters
string$baseBase class name.
Return
this

public function setConcreteOnly($concrete)

Restrict the symbol query to only concrete symbols; this will filter out abstract classes.

NOTE: This currently causes class symbols to load, even if you run selectSymbolsWithoutLoading().
Parameters
bool$concreteTrue if the query should load only concrete symbols.
Return
this

public function setContinueOnFailure($continue)

This method is not documented.
Parameters
$continue
Return
wild

public function selectAndLoadSymbols()

Execute the query and select matching symbols, then load them so they can be used.

Return
dictA dictionary of matching symbols. See top-level class documentation for details. These symbols will be loaded and available.

public function selectSymbolsWithoutLoading()

Execute the query and select matching symbols, but do not load them. This will perform slightly better if you are only interested in the existence of the symbols and don't plan to use them; otherwise, use selectAndLoadSymbols().

Return
dictA dictionary of matching symbols. See top-level class documentation for details.

public function loadObjects($argv)

Select symbols matching the query and then instantiate them, returning concrete objects. This is a convenience method which simplifies symbol handling if you are only interested in building objects.

If you want to do more than build objects, or want to build objects with varying constructor arguments, use selectAndLoadSymbols() for fine-grained control over results.

This method implicitly restricts the query to match only concrete classes.

Parameters
list<wild>$argvList of constructor arguments.
Return
map<string, object>Map of class names to constructed objects.

private function selectDescendantsOf($tree, $root)

This method is not documented.
Parameters
array$tree
$root
Return
wild

private function loadSymbol($symbol_spec)

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