AttributeReference
in package
An attribute name or path expression identifying a value within an {@see \LaunchDarkly\LDContext}.
Applications are unlikely to need to use this type directly, but see below for details of the attribute reference syntax used by methods like LDContextBuilder::private().
The string representation of an attribute reference in LaunchDarkly data uses the following syntax:
- If the first character is not a slash, the string is interpreted literally as an attribute name. An attribute name can contain any characters, but must not be empty.
- If the first character is a slash, the string is interpreted as a slash-delimited path where the first path component is an attribute name, and each subsequent path component is the name of a property in a JSON object. Any instances of the characters "/" or "~" in a path component are escaped as "~1" or "~0" respectively. This syntax deliberately resembles JSON Pointer, but no JSON Pointer behaviors other than those mentioned here are supported.
Table of Contents
- ERR_ATTR_EMPTY = 'attribute reference cannot be empty'
- ERR_ATTR_EXTRA_SLASH = 'attribute reference contained a double slash or a trailing slash'
- ERR_ATTR_INVALID_ESCAPE = 'attribute reference contained an escape character (~) that was not followed by 0 or 1'
- fromLiteral() : AttributeReference
- Similar to {@see \LaunchDarkly\AttributeReference::fromPath()}, except that it always interprets the string as a literal attribute name, never as a slash-delimited path expression.
- fromPath() : AttributeReference
- Creates an AttributeReference from a string. For the supported syntax and examples, see comments on the {@see \LaunchDarkly\AttributeReference} type.
- getComponent() : string
- Retrieves a single path component from the attribute reference.
- getDepth() : int
- The number of path components in the AttributeReference.
- getError() : string|null
- Returns null for a valid reference, or an error string for an invalid one.
- getPath() : string
- Returns the original attribute reference path string.
Constants
ERR_ATTR_EMPTY
public
mixed
ERR_ATTR_EMPTY
= 'attribute reference cannot be empty'
ERR_ATTR_EXTRA_SLASH
public
mixed
ERR_ATTR_EXTRA_SLASH
= 'attribute reference contained a double slash or a trailing slash'
ERR_ATTR_INVALID_ESCAPE
public
mixed
ERR_ATTR_INVALID_ESCAPE
= 'attribute reference contained an escape character (~) that was not followed by 0 or 1'
Methods
fromLiteral()
Similar to {@see \LaunchDarkly\AttributeReference::fromPath()}, except that it always interprets the string as a literal attribute name, never as a slash-delimited path expression.
public
static fromLiteral(string $attributeName) : AttributeReference
There is no escaping or unescaping, even if the name contains literal '/' or '~' characters. Since an attribute name can contain any characters, this method always returns a valid AttributeReference unless the name is empty.
Parameters
- $attributeName : string
-
an attribute name
Return values
AttributeReference —fromPath()
Creates an AttributeReference from a string. For the supported syntax and examples, see comments on the {@see \LaunchDarkly\AttributeReference} type.
public
static fromPath(string $refPath) : AttributeReference
This method always returns an AttributeRef that preserves the original string, even if validation fails. If validation fails, AttributeReference::getError() will return a non-null error and any SDK method that takes this AttributeReference as a parameter will consider it invalid.
Parameters
- $refPath : string
-
an attribute name or path
Return values
AttributeReference —the parsed reference
getComponent()
Retrieves a single path component from the attribute reference.
public
getComponent(int $index) : string
For a simple attribute reference such as "name" with no leading slash, it returns the attribute name if index is zero, and an empty string otherwise.
For an attribute reference with a leading slash, if index is non-negative and less than getDepth(), it returns the path component string at that position.
Parameters
- $index : int
Return values
string —the path component, or an empty string if not available
getDepth()
The number of path components in the AttributeReference.
public
getDepth() : int
For a simple attribute reference such as "name" with no leading slash, this returns 1.
For an attribute reference with a leading slash, it is the number of slash-delimited path components after the initial slash. For instance, for "/a/b" it returns 2.
For an invalid attribute reference, it returns zero.
Return values
int —the number of path components
getError()
Returns null for a valid reference, or an error string for an invalid one.
public
getError() : string|null
Return values
string|null —an error string or null
getPath()
Returns the original attribute reference path string.
public
getPath() : string