LaunchDarkly PHP SDK 6.3.0

LDContextBuilder
in package

A mutable object that uses the builder pattern to specify properties for LDContext.

Use this type if you need to construct a context that has only a single kind. To define a multi-context, use LDContext::createMulti() or LDContext::multiBuilder().

Obtain an instance of LDContextBuilder by calling LDContext::builder(). Then, call setter methods such as LDContextBuilder::name() or LDContextBuilder::set() to specify any additional attributes. Then, call LDContextBuilder::build() to create the context. LDContextBuilder setters return a reference to the same builder, so calls can be chained:

    $context = LDContext::builder('user-key')
        ->name('my-name')
        ->set('country', 'us')
        ->build();
Tags
see
LDContext

Table of Contents

__construct()  : LDContextBuilder
Constructs a new builder.
anonymous()  : LDContextBuilder
Sets whether the context is only intended for flag evaluations and should not be indexed by LaunchDarkly.
build()  : LDContext
Creates an LDContext from the current builder properties.
key()  : LDContextBuilder
Sets the context's key attribute.
kind()  : LDContextBuilder
Sets the context's kind attribute.
name()  : LDContextBuilder
Sets the context's name attribute.
private()  : LDContextBuilder
Designates any number of LDContext attributes, or properties within them, as private: that is, their values will not be sent to LaunchDarkly.
set()  : LDContextBuilder
Sets the value of any attribute for the context.
trySet()  : bool
Same as set(), but returns a boolean indicating whether the attribute was successfully set.

Methods

anonymous()

Sets whether the context is only intended for flag evaluations and should not be indexed by LaunchDarkly.

public anonymous(bool $anonymous) : LDContextBuilder

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.

Parameters
$anonymous : bool

true if the context should be excluded from the LaunchDarkly database

Tags
see
LDContext::isAnonymous()
Return values
LDContextBuilder —

the builder

build()

Creates an LDContext from the current builder properties.

public build() : LDContext

The LDContext is immutable and will not be affected by any subsequent actions on the builder.

It is possible to specify invalid attributes for an LDContextBuilder, such as an empty key. Instead of throwing an exception, the LDContextBuilder always returns an LDContext and you can check LDContext::isValid() or LDContext::getError() to see if it has an error. See LDContext::isValid() for more information about invalid conditions. If you pass an invalid LDContext to an SDK method, the SDK will detect this and will log a description of the error.

Return values
LDContext —

a new LDContext

key()

Sets the context's key attribute.

public key(string $key) : LDContextBuilder

Every context has a key, which is always a string. It cannot be an empty string, but there are no other restrictions on its value.

The key attribute can be referenced by flag rules, flag target lists, and segments.

Parameters
$key : string

the context key

Tags
see
LDContext::getKey()
Return values
LDContextBuilder —

the builder

kind()

Sets the context's kind attribute.

public kind(string $kind) : LDContextBuilder

Every context has a kind. Setting it to an empty string or null is equivalent to LDContext::DEFAULT_KIND ("user"). This value is case-sensitive.

The meaning of the context kind is completely up to the application. Validation rules are as follows:

  • It may only contain letters, numbers, and the characters ., _, and -.
  • It cannot equal the literal string "kind".
  • For a single context, it cannot equal "multi".
Parameters
$kind : string

the context kind

Tags
see
LDContext::getKind()
Return values
LDContextBuilder —

the builder

name()

Sets the context's name attribute.

public name(string|null $name) : LDContextBuilder

This attribute is optional. It has the following special rules:

  • Unlike most other attributes, it is always a string if it is specified.
  • The LaunchDarkly dashboard treats this attribute as the preferred display name for contexts.
Parameters
$name : string|null

the name attribute (null to unset the attribute)

Tags
see
LDContext::getName()
Return values
LDContextBuilder —

the builder

private()

Designates any number of LDContext attributes, or properties within them, as private: that is, their values will not be sent to LaunchDarkly.

public private(array<string|int, mixed> ...$attributeRefs) : LDContextBuilder

Each parameter can be either a simple attribute name, or a slash-delimited path (in the format defined by AttributeReference) referring to a JSON object property within an attribute.

Parameters
$attributeRefs : array<string|int, mixed>

attribute names or references to mark as private

Tags
see
LDContext::getPrivateAttributes()
Return values
LDContextBuilder —

the builder

set()

Sets the value of any attribute for the context.

public set(string $attributeName, mixed $value) : LDContextBuilder

This includes only attributes that are addressable in evaluations-- not metadata such as LDContextBuilder::private(). If attributeName is 'private', you will be setting an attribute with that name which you can use in evaluations or to record data for your own purposes, but it will be unrelated to LDContextBuilder::private().

The allowable types for context attributes are equivalent to JSON types: boolean, number, string, array, or object. For all attribute names that do not have special meaning to LaunchDarkly, you may use any of those types. Values of different JSON types are always treated as different values: for instance, the number 1 is not the same as the string "1".

The following attribute names have special restrictions on their value types, and any value of an unsupported type will be ignored (leaving the attribute unchanged):

The attribute name "_meta" is not allowed, because it has special meaning in the JSON schema for contexts; any attempt to set an attribute with this name has no effect.

Values that are JSON arrays or objects have special behavior when referenced in flag/segment rules.

A value of null is equivalent to removing any current non-default value of the attribute. Null is not a valid attribute value in the LaunchDarkly model; any expressions in feature flags that reference an attribute with a null value will behave as if the attribute did not exist.

Parameters
$attributeName : string

the attribute name to set

$value : mixed

the value to set

Tags
see
LDContext::get()
see
LDContextBuilder::trySet()
Return values
LDContextBuilder —

the builder

trySet()

Same as set(), but returns a boolean indicating whether the attribute was successfully set.

public trySet(string $attributeName, mixed $value) : bool
Parameters
$attributeName : string

the attribute name to set

$value : mixed

the value to set

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

true if successful; false if the name was invalid or the value was not an allowed type for that attribute

Search results