LaunchDarkly PHP SDK 6.3.0

LDContext
in package
implements JsonSerializable

A collection of attributes that can be referenced in flag evaluations and analytics events.

This entity is also called an "evaluation context."

To create an LDContext of a single kind, such as a user, you may use LDContext::create() when only the key and the kind are relevant; or, to specify other attributes, use LDContext::builder().

To create an LDContext with multiple kinds (a multi-context), use LDContext::createMulti() or LDContext::multiBuilder().

An LDContext can be in an error state if it was built with invalid attributes. See LDContext::isValid() and LDContext::getError().

Interfaces, Classes, Traits and Enums

JsonSerializable

Table of Contents

DEFAULT_KIND  = 'user'
A constant for the default kind of "user".
MULTI_KIND  = 'multi'
A constant for the kind that all multi-contexts have.
__construct()  : mixed
Constructs an instance, setting all properties. Avoid using this constructor directly.
__toString()  : string
Returns a string representation of the LDContext.
builder()  : LDContextBuilder
Creates a builder for building an LDContext.
create()  : LDContext
Creates a single-kind LDContext with only the key and the kind specified.
createMulti()  : LDContext
Creates a multi-context out of the specified single-kind LDContexts.
equals()  : bool
Tests whether two contexts are logically equal.
fromJson()  : LDContext
Creates an LDContext from a parsed JSON representation.
get()  : mixed
Looks up the value of any attribute of the context by name.
getCustomAttributeNames()  : array<string|int, mixed>
Returns the names of all non-built-in attributes that have been set in this context.
getError()  : string|null
Returns `null` for a valid LDContext, or an error message for an invalid one.
getFullyQualifiedKey()  : string
Returns a string that describes the LDContext uniquely based on `kind` and `key` values.
getIndividualContext()  : LDContext|null
Returns the single-kind LDContext corresponding to one of the kinds in this context.
getIndividualContextCount()  : int
Returns the number of context kinds in this context.
getKey()  : string
Returns the context's `key` attribute.
getKeys()  : array<string|int, mixed>
Returns an associate array mapping each context kind to its key.
getKind()  : string
Returns the context's `kind` attribute.
getName()  : string|null
Returns the context's `name` attribute.
getPrivateAttributes()  : array<string|int, AttributeReference>|null
Gets the list of all attribute references marked as private for this specific LDContext.
isAnonymous()  : bool
Returns true if this context is only intended for flag evaluations and will not be indexed by LaunchDarkly.
isMultiple()  : bool
Returns true if this is a multi-context.
isValid()  : bool
Returns `true` for a valid LDContext, `false` for an invalid one.
jsonSerialize()  : array<string|int, mixed>
Returns a JSON representation of the context (as an associative array), in the format used by LaunchDarkly SDKs.
multiBuilder()  : LDContextMultiBuilder
Creates a builder for building a multi-context.

Constants

DEFAULT_KIND

A constant for the default kind of "user".

public mixed DEFAULT_KIND = 'user'

MULTI_KIND

A constant for the kind that all multi-contexts have.

public mixed MULTI_KIND = 'multi'

Methods

__construct()

Constructs an instance, setting all properties. Avoid using this constructor directly.

public __construct(string|null $kind, string $key, string|null $name, bool $anonymous, array<string|int, mixed>|null $attributes, array<string|int, AttributeReference>|null $privateAttributes, array<string|int, LDContext>|null $multiContexts, string|null $error) : mixed

Applications should not normally use this constructor; the intended pattern is to use factory methods or builders. Calling this constructor directly may result in some context validation being skipped.

Parameters
$kind : string|null

the context kind

$key : string

the context key

$name : string|null

the optional name attribute

$anonymous : bool

the anonymous attribute

$attributes : array<string|int, mixed>|null

associative array of additional attributes

$privateAttributes : array<string|int, AttributeReference>|null

private attribute references

$multiContexts : array<string|int, LDContext>|null

contexts within this if this is a multi-context

$error : string|null

error string or null if valid

Return values
mixed —

__toString()

Returns a string representation of the LDContext.

public __toString() : string

For a valid LDContext, this is currently defined as being the same as the JSON representation, since that is the simplest way to represent all of the Context properties. However, application code should not rely on __toString() always being the same as the JSON representation. If you specifically want the latter, use json_encode() or LDContext::jsonSerialize(). For an invalid LDContext, __toString() returns a description of why it is invalid.

Return values
string —

a string representation

builder()

Creates a builder for building an LDContext.

public static builder(string $key) : LDContextBuilder

You may use LDContextBuilder methods to set additional attributes and/or change the kind before calling LDContextBuilder::build(). If you do not change any values, the defaults for the LDContext are that its kind is LDContext::DEFAULT_KIND ("user"), its key is set to the key parameter specified here, anonymous is false, and it has no values for any other attributes.

This method is for building an LDContext that has only a single kind. To define a multi-context, use LDContext::createMulti() or LDContext::multiBuilder().

If key is an empty string, there is no default. An LDContext must have a non-empty key, so if you call LDContextBuilder::build() in this state without using LDContextBuilder::key() to set the key, you will get an invalid LDContext.

Parameters
$key : string

the context key

Tags
see
LDContext::multiBuilder()
see
LDContext::create()
Return values
LDContextBuilder —

a builder

create()

Creates a single-kind LDContext with only the key and the kind specified.

public static create(string $key[, string|null $kind = null ]) : LDContext

If you omit the kind, it defaults to "user" (LDContext::DEFAULT_KIND).

To specify additional properties, use LDContext::builder(). To create a multi-context instead of a single one, use LDContext::createMulti() or LDContext::multiBuilder().

Parameters
$key : string

the context key

$kind : string|null = null

the context kind; if null, LDContext::DEFAULT_KIND is used

Tags
see
LDContext::createMulti()
see
LDContext::builder()
Return values
LDContext —

an LDContext

createMulti()

Creates a multi-context out of the specified single-kind LDContexts.

public static createMulti(LDContext ...$contexts) : LDContext

To create an LDContext for a single context kind, use LDContext::create() or LDContext::builder().

For the returned LDContext to be valid, the contexts list must not be empty, and all of its elements must be valid LDContexts. Otherwise, the returned LDContext will be invalid as reported by LDContext::getError().

If only one context parameter is given, the method returns that same context.

If the nested context is a multi-context, this is exactly equivalent to adding each of the individual kinds from it separately. See LDContextMultiBuilder::add().

Parameters
$contexts : LDContext
Tags
see
LDContext::create()
see
LDContext::multiBuilder()
Return values
LDContext —

an LDContext

equals()

Tests whether two contexts are logically equal.

public equals(LDContext $other) : bool

Equality for single contexts means that all of their attributes are equal. Equality for multi-contexts means that the same context kinds are present in both, and the individual contexts for each kind are equal.

Parameters
$other : LDContext

another context

Return values
bool —

true if it is equal to this context

fromJson()

Creates an LDContext from a parsed JSON representation.

public static fromJson(string|array<string|int, mixed>|object $jsonObject) : LDContext

The JSON must be in one of the standard formats used by LaunchDarkly.

    $json = '{"kind": "user", "key": "aaa"}';
    $context = LDContext::fromJson($json);

    // or:
    $props = ['kind' => 'user', 'key' => 'true'];
    $context = LDContext::fromJson($props);
Parameters
$jsonObject : string|array<string|int, mixed>|object

a JSON representation as a string; or, an object or associative array corresponding to the parsed JSON

Tags
throws
InvalidArgumentException

if any properties were invalid, or if you passed a string that was not well-formed JSON

Return values
LDContext —

a context

get()

Looks up the value of any attribute of the context by name.

public get(string $attributeName) : mixed

For a single-kind context, the attribute name can be any custom attribute that was set by LDContextBuilder::set(). It can also be one of the built-in ones like "kind", "key", or "name"; in such cases, it is equivalent to LDContext::getKind(), LDContext::getKey(), or LDContext::getName().

For a multi-context, the only supported attribute name is "kind". Use LDContext::getIndividualContext() to get the context for a particular kind and then get its attributes.

If the value is found, the return value is the attribute value. If there is no such attribute, the return value is null. An attribute that actually exists cannot have a null value.

Parameters
$attributeName : string

the desired attribute name

Tags
see
LDContextBuilder::set()
Return values
mixed —

the attribute value, or null if there is no such attribute

getCustomAttributeNames()

Returns the names of all non-built-in attributes that have been set in this context.

public getCustomAttributeNames() : array<string|int, mixed>

For a single-kind context, this includes all the names that were passed to LDContextBuilder::set() as long as the values were not null (since a null value in LaunchDarkly is equivalent to the attribute not being set).

For a multi-context, there are no such names.

Return values
array<string|int, mixed> —

an array of strings (may be empty, but will never be null)

getFullyQualifiedKey()

Returns a string that describes the LDContext uniquely based on `kind` and `key` values.

public getFullyQualifiedKey() : string

This value is used whenever LaunchDarkly needs a string identifier based on all of the kind and key values in the context. Applications typically do not need to use it.

Return values
string —

the fully-qualified key

getIndividualContext()

Returns the single-kind LDContext corresponding to one of the kinds in this context.

public getIndividualContext(int|string $kind) : LDContext|null

The kind parameter can be either a number representing a zero-based index, or a string representing a context kind.

If this method is called on a single-kind LDContext, then the only allowable value for kind is either zero or the same value as LDContext::getKind() , and the return value on success is the same LDContext.

If the method is called on a multi-context, and kind is a number, it must be a non-negative index that is less than the number of kinds (that is, less than the return value of LDContext::getIndividualContextCount(), and the return value on success is one of the individual LDContexts within. Or, if kind is a string, it must match the context kind of one of the individual contexts.

If there is no context corresponding to kind, the method returns null.

Parameters
$kind : int|string

the index or string value of a context kind

Return values
LDContext|null —

the context corresponding to that index or kind, or null if none

getIndividualContextCount()

Returns the number of context kinds in this context.

public getIndividualContextCount() : int

For a valid individual context, this returns 1. For a multi-context, it returns the number of context kinds. For an invalid context, it returns zero.

Return values
int —

the number of context kinds

getKey()

Returns the context's `key` attribute.

public getKey() : string

For a single context, this value is set by LDContext::create(), LDContext::builder(), or LDContextBuilder::key().

For a multi-context, there is no single value and getKey() returns an empty string. empty string. Use LDContext::getIndividualContext() to get the context for a particular kind, then call getKey() on it.

This value is never null.

Tags
see
LDContextBuilder::key()
Return values
string —

the context key

getKeys()

Returns an associate array mapping each context kind to its key.

public getKeys() : array<string|int, mixed>

If the context is invalid, this will return an empty array. A single kind context will return an array with a single mapping.

Return values
array<string|int, mixed> —

getName()

Returns the context's `name` attribute.

public getName() : string|null

For a single context, this value is set by LDContextBuilder::name(). It is null if no value was set.

For a multi-context, there is no single value and getName() returns null. Use LDContext::getIndividualContext() to get the context for a particular kind, then call getName() on it.

Tags
see
LDContextBuilder::name()
Return values
string|null —

the context name or null

getPrivateAttributes()

Gets the list of all attribute references marked as private for this specific LDContext.

public getPrivateAttributes() : array<string|int, AttributeReference>|null

This includes all attribute names/paths that were specified with LDContextBuilder::private(). If there are none, it is null.

Return values
array<string|int, AttributeReference>|null —

the list of private attributes, if any

isAnonymous()

Returns true if this context is only intended for flag evaluations and will not be indexed by LaunchDarkly.

public isAnonymous() : bool

The default value is false. False means that this LDContext represents an entity such as a user that you want to be able to see on the LaunchDarkly dashboard.

Setting anonymous to true excludes this context from the database that is used by the dashboard. It does not exclude it from analytics event data, so it is not the same as making attributes private; all non-private attributes will still be included in events and data export. There is no limitation on what other attributes may be included (so, for instance, anonymous does not mean there is no name), and the context will still have whatever key you have given it.

This value is also addressable in evaluations as the attribute name "anonymous". It is always treated as a boolean true or false in evaluations.

Tags
see
LDContextBuilder::anonymous()
Return values
bool —

true if the context should be excluded from the LaunchDarkly database

isValid()

Returns `true` for a valid LDContext, `false` for an invalid one.

public isValid() : bool

A valid context is one that can be used in SDK operations. An invalid context is one that is missing necessary attributes or has invalid attributes, indicating an incorrect usage of the SDK API. The only ways for a context to be invalid are:

  • The kind property had a disallowed value. See LDContextBuilder::kind().
  • For a single context, the key property was null or empty.
  • You tried to create a multi-context without specifying any contexts.
  • You tried to create a multi-context using the same context kind more than once.
  • You tried to create a multi-context where at least one of the individual LDContexts was invalid.

In any of these cases, isValid() will return false, and LDContext::getError() will return a description of the error.

Since in normal usage it is easy for applications to be sure they are using context kinds correctly, and because throwing an exception is undesirable in application code that uses LaunchDarkly, the SDK stores the error state in the LDContext itself and checks for such errors at the time the Context is used, such as in a flag evaluation. At that point, if the context is invalid, the operation will fail in some well-defined way as described in the documentation for that method, and the SDK will generally log a warning as well. But in any situation where you are not sure if you have a valid LDContext, you can check isValid() or LDContext::getError().

Tags
see
LDContext::getError()
Return values
bool —

true if the context is valid

jsonSerialize()

Returns a JSON representation of the context (as an associative array), in the format used by LaunchDarkly SDKs.

public jsonSerialize() : array<string|int, mixed>

Use this method if you are passing context data to the front end for use with the LaunchDarkly JavaScript SDK.

Note that calling json_encode() on an LDContext object will automatically use the jsonSerialize() method.

Return values
array<string|int, mixed> —

an associative array suitable for passing as a JSON object

multiBuilder()

Creates a builder for building a multi-context.

public static multiBuilder() : LDContextMultiBuilder

This method is for building an LDContext that contains multiple contexts, each for a different context kind. To define a single context, use LDContext::builder() or LDContext::create() instead.

The difference between this method and LDContext::createMulti() is simply that the builder allows you to add contexts one at a time, if that is more convenient for your logic.

Tags
see
LDContext::createMulti()
see
LDContext::builder()
Return values
LDContextMultiBuilder —

a builder

Search results