API Reference

class SphinxInventoryParser

Parser for Sphinx objects.inv inventory file format.

This is the main class of the library. It provides a static method parseFromDoc() that should handle the most frequent use case. For more control, it can be instanciated, each instance then provide a public method parse(), which allows to parse a stream of data into a PHP object.

For even more control over the parsing, the underlying methods parseHeader() and parseObjects() can be used directly.

public static parseFromDoc(string $url, string $path = 'objects.inv') → SphinxInventory

Parse a Sphinx inventory directly from an online documentation’s URL.

This is the simplest way to use this library. Its parameters are similar to Sphinx’s intersphinx_mapping configuration value. Example:

$inventory = SphinxInventoryParser::parseFromDoc('https://club1.fr/docs/');
Parameters:

  • $url (string) – The URL of the documentation’s root, with or without the trailing slash. It is used both as the location to fetch the inventory and as the base for the SphinxObject::$uri.

  • $path (string) – The path to the inventory within the documentation. Defaults to objects.inv.

Returns:

The parsed inventory.

Return type:

SphinxInventory

Throws:

  • UnexpectedValueException – If an unexpected value is encountered while parsing.

  • RuntimeException – If the stream can not be open.

public __construct($stream)

Create a SphinxInventoryParser for the given stream.

Such a stream is usually obtained with fopen(), using the r mode. For example, with a remote file over HTTPS it is possible to do this:

$stream = fopen('https://club1.fr/docs/fr/objects.inv', 'r');
$parser = new SphinxInventoryParser($stream);
$inventory = $parser->parse('https://club1.fr/docs/fr/');
fclose($stream);
Parameters:

  • $stream (resource) – The resource to parse, opened in read mode.

public parse(string $baseURI = '') → SphinxInventory

Parse the stream into an indexed SphinxInventory object.

The Sphinx objects.inv v2 Syntax encode some values in a compressed form:

  • The {uri} part is encoded as a relative path that can end with a $ which needs to be replaced by the name of the object.

  • The {dispname} part can be a - when it is the identical to the name of the object.

These are expanded before creating the SphinxObjects so that no more processing needs to be done later.

Parameters:

  • $baseURI (string) – The base string to prepend to an object’s location to get its final URI.

Returns:

The inventory parsed from the stream.

Return type:

SphinxInventory

Throws:

UnexpectedValueException – If an unexpected value is encountered while parsing.

public parseHeader() → SphinxInventoryHeader

Parse only the header of the stream.

Read the first line of the stream to determine the inventory version, then, if the version is supported, parse the rest of the header.

This consumes the header part of the stream, leaving only the objects part, ready to be parsed by parseObjects().

Returns:

The header of the inventory.

Return type:

SphinxInventoryHeader

Throws:

UnexpectedValueException – If an unexpected value is encoutered while parsing.

public parseObjects(SphinxInventoryHeader $header, string $baseURI = '') → Generator

Parse the objects part of the stream.

Read the stream as if it consists only of the objects part. This function assumes that the header part of the stream has already been read. If the stream contains a standard inventory, parseHeader() must be called beforehand.

Parameters:

  • $header (SphinxInventoryHeader) – The header of the inventory, obtained via parseHeader() or manually created.

  • $baseURI (string) – The base string to prepend to an object’s location to get its final URI.

Returns:

An iterator of SphinxObject objects.

Return type:

Generator&iterable

Throws:

  • InvalidArgumentException – If the inventory version given in the header is unsupported.

  • UnexpectedValueException – If an unexpected value is encountered while parsing.

class SphinxInventory
property project

string – Name of the project of the inventory.

property version

string – Version of the project of the inventory.

property objects

SphinxObject[] – List of all Sphinx objects of the inventory.

property domains

SphinxObject[][][] – Tree index of the objects of the inventory.

This index allows to find the objects faster. It is a multi-level hashmap indexed with the $domain, $role and $name of the objects. For example, the object of the glossary term API can be retrieved like so:

$APIObject = $inventory->domains['std']['term']['API'];
public __construct(string $project, string $version)

Basic constructor.

public addObject(SphinxObject $object) → void

Add a Sphinx object to the inventory.

The object will be added both to the $objects array and the $domains index.

Parameters:
class SphinxObject

Data class of a Sphinx object.

All of its properties are public as it is only meant to be a data structure. The values are expanded while parsing, so no more processing need to be done.

property name

string – Name of the object.

This property, combined with $domain and $role form the identifier of the object.

property domain

string – Domain of the object.

See Domains in Sphinx documentation for more information.

property role

string – Role of the object.

See Roles in Sphinx documentation for more information.

property priority

int – Priority of the object.

Used by Sphinx to order search results. See also {priority} in Sphobjinv documentation.

property uri

string – Full URI of the object.

The fully resolved URI of the object. It has been expanded by SphinxInventoryParser and can be used as is.

property displayName

string – Display name of the object.

The value to use when displaying the object in a document. It is often the same as the $name but can differ occasionally. It has been expanded by SphinxInventoryParser and can be used as is.

public __construct(string $name, string $domain, string $role, int $priority, string $uri, string $displayName)

Basic constructor.

Simply assign the properties of the objects with the given values.

class SphinxInventoryHeader

Metadata of a Sphinx inventory.

Usually obtained vith SphinxInventoryParser::parseHeader(), but it can also be created manually if needed.

property version

int – Version of the inventory.

property projectName

string – The inventory’s project name.

property projectVersion

string – The inventory’s project version.

public __construct(int $version = 2, string $projectName = '', string $projectVersion = '')

Basic constructor.