ParticipantAttributeService
in package
Service class for managing participant attributes.
All dependencies are injected to enable mocking.
There is still plenty of attribute related functions scattered in the codebase (see ParticipantsAction.php and Participant.php) which should be moved in here.
This service class also deals with attributes of survey participants (tokens) which are related to CPDB attributes but still stored differently.
Table of Contents
Properties
- $attributeTypes : mixed
- $modelParticipantAttributeLang : ParticipantAttributeNameLang
- $modelParticipantAttributeName : ParticipantAttributeName
- $modelParticipantAttributeValue : ParticipantAttributeValue
Methods
- __construct() : mixed
- convertCPDBDateToStoreFormat() : string
- Converts a CPDB (Central Participant Database) date attribute to standard storage format.
- convertDateAttribute() : string
- Converts a date attribute value to standard storage format if it's a date picker type.
- convertDateAttributeToDisplayFormat() : mixed
- Converts a date attribute from storage format to display format.
- decodeJsonEncodedTypeOptions() : array<string|int, mixed>
- Decodes JSON encoded options string and returns an array.
- getParticipantAttributeNameType() : string|null
- Retrieves the attribute type for a given participant attribute ID.
- normalizeAttributeDataset() : array<string|int, mixed>
- Normalizes attribute data by ensuring all required keys exist with default values.
- prepareAttributesForSave() : array<string|int, mixed>
- Used by registration form we get array of attribute names and their values we figure out the type and convert the date if type is DP (date picker) we replace the converted date in the array and return it back
- saveDropdownAttributeOptions() : void
- Saves dropdown attribute options to the participant_attribute_values table.
- saveParticipantAttribute() : int
- Saves a complete participant attribute with its name, localization, and dropdown options.
- saveParticipantAttributeL10n() : void
- Saves a localized name for a participant attribute.
- saveParticipantAttributeName() : int
- Saves a new participant attribute to the database.
- convertDateToStoreFormat() : string|false
- Converts a date string from a specified format to the standard storage format.
Properties
$attributeTypes
private
mixed
$attributeTypes
= null
$modelParticipantAttributeLang
private
ParticipantAttributeNameLang
$modelParticipantAttributeLang
$modelParticipantAttributeName
private
ParticipantAttributeName
$modelParticipantAttributeName
$modelParticipantAttributeValue
private
ParticipantAttributeValue
$modelParticipantAttributeValue
Methods
__construct()
public
__construct(ParticipantAttributeName $modelParticipantAttributeName, ParticipantAttributeNameLang $modelParticipantAttributeLang, ParticipantAttributeValue $modelParticipantAttributeValue) : mixed
Parameters
- $modelParticipantAttributeName : ParticipantAttributeName
- $modelParticipantAttributeLang : ParticipantAttributeNameLang
- $modelParticipantAttributeValue : ParticipantAttributeValue
convertCPDBDateToStoreFormat()
Converts a CPDB (Central Participant Database) date attribute to standard storage format.
public
convertCPDBDateToStoreFormat(int $attributeId, mixed $attributeValue) : string
This method retrieves the attribute type by ID and converts date picker (DP) values from the user's session date format to the standard database storage format (Y-m-d). For non-date attributes, the original value is returned unchanged.
Parameters
- $attributeId : int
-
The ID of the participant attribute
- $attributeValue : mixed
-
The attribute value to be converted
Return values
string —The converted date string in 'Y-m-d' format if type is 'DP' and conversion succeeds, an empty string if type is 'DP' but conversion fails, or the original value for non-date types.
convertDateAttribute()
Converts a date attribute value to standard storage format if it's a date picker type.
public
convertDateAttribute(array<string|int, mixed> $attributeData, mixed $attributeValue) : string
This method checks if the attribute is a date picker (DP) type and converts its value from the user's session date format to the standard database storage format (Y-m-d). For non-date attributes, the original value is returned unchanged. If the date conversion fails, an empty string is returned.
Parameters
- $attributeData : array<string|int, mixed>
-
Array containing attribute metadata with keys:
- 'type': The attribute type (e.g., 'DP' for date picker)
- $attributeValue : mixed
-
The attribute value to be converted. Expected to be a date string if the attribute type is 'DP', otherwise can be any value.
Return values
string —The converted date string in 'Y-m-d' format if type is 'DP' and conversion succeeds, an empty string if type is 'DP' but conversion fails, or the original value cast to string for non-date types.
convertDateAttributeToDisplayFormat()
Converts a date attribute from storage format to display format.
public
convertDateAttributeToDisplayFormat(int $attributeId, mixed $value[, bool $checkForType = true ]) : mixed
This method retrieves the attribute type by ID and converts date picker (DP) values from the standard database storage format (Y-m-d) to the user's session date format. For non-date attributes, the original value is returned unchanged.
Parameters
- $attributeId : int
-
The ID of the participant attribute
- $value : mixed
-
The attribute value to be converted
- $checkForType : bool = true
-
Whether to check the attribute type and convert only if it's a date picker (DP) type. Default is true.
Return values
mixed —The converted date string in the user's preferred format if type is 'DP' and value is in Y-m-d format, or the original value for non-date types or invalid dates.
decodeJsonEncodedTypeOptions()
Decodes JSON encoded options string and returns an array.
public
decodeJsonEncodedTypeOptions(string $jsonEncodedOptions) : array<string|int, mixed>
Parameters
- $jsonEncodedOptions : string
-
JSON string to decode
Return values
array<string|int, mixed> —Decoded array or empty array if invalid JSON or not an array
getParticipantAttributeNameType()
Retrieves the attribute type for a given participant attribute ID.
public
getParticipantAttributeNameType(int $attributeId) : string|null
This method uses lazy loading to cache all attribute types on first call, then returns the type for the requested attribute ID from the cache. The cache persists for the lifetime of the service instance.
Parameters
- $attributeId : int
-
The ID of the participant attribute
Return values
string|null —The attribute type (e.g., 'DD', 'TB', 'DP') if found, null if the attribute ID doesn't exist
normalizeAttributeDataset()
Normalizes attribute data by ensuring all required keys exist with default values.
public
normalizeAttributeDataset(array<string|int, mixed> $attributeData) : array<string|int, mixed>
This method validates and fills in missing attribute data keys with sensible defaults to ensure consistent data structure when creating or updating participant attributes.
Parameters
- $attributeData : array<string|int, mixed>
-
The attribute data to normalize
Return values
array<string|int, mixed> —The normalized attribute data with all required keys
prepareAttributesForSave()
Used by registration form we get array of attribute names and their values we figure out the type and convert the date if type is DP (date picker) we replace the converted date in the array and return it back
public
prepareAttributesForSave(array<string|int, mixed> $attributes, string $fromFormat, array<string|int, mixed> $registerAttributesInfo) : array<string|int, mixed>
Parameters
- $attributes : array<string|int, mixed>
- $fromFormat : string
- $registerAttributesInfo : array<string|int, mixed>
Return values
array<string|int, mixed>saveDropdownAttributeOptions()
Saves dropdown attribute options to the participant_attribute_values table.
public
saveDropdownAttributeOptions(int $attributeId, array<string|int, mixed> $attributeData) : void
This method processes dropdown (DD) type attributes by decoding their JSON-encoded options and creating individual ParticipantAttributeValue records for each option. If the attribute type is not 'DD', no action is taken.
Parameters
- $attributeId : int
-
The ID of the participant attribute from ParticipantAttributeName
- $attributeData : array<string|int, mixed>
-
Array containing attribute data, must include 'type' and 'type_options' keys
saveParticipantAttribute()
Saves a complete participant attribute with its name, localization, and dropdown options.
public
saveParticipantAttribute(array<string|int, mixed> $attributeData, string $attributeName) : int
This method orchestrates the creation of a new participant attribute by:
- Creating the base attribute record with type and encryption settings
- Adding a localized name for the attribute in the current admin language
- If the attribute is a dropdown type, saving all available options
Parameters
- $attributeData : array<string|int, mixed>
-
Array containing attribute configuration with keys:
- 'type': The attribute type (e.g., 'DD' for dropdown, 'TB' for textbox)
- 'encrypted': Whether the attribute should be encrypted ('Y' or 'N')
- 'type_options': JSON-encoded string of dropdown options (if type is 'DD')
- $attributeName : string
-
The name/identifier for the attribute (e.g., 'attribute_1')
Tags
Return values
int —The primary key (attribute_id) of the newly created attribute
saveParticipantAttributeL10n()
Saves a localized name for a participant attribute.
public
saveParticipantAttributeL10n(string $attributeName, int $attributeId) : void
Creates a new ParticipantAttributeNameLang record to store the translated/localized name of a participant attribute in the current admin language. This allows attributes to have different display names in different languages.
Parameters
- $attributeName : string
-
The localized/translated name for the attribute
- $attributeId : int
-
The ID of the participant attribute from ParticipantAttributeName
Tags
saveParticipantAttributeName()
Saves a new participant attribute to the database.
public
saveParticipantAttributeName(array<string|int, mixed> $attributeData, string $attributeName) : int
Creates a new central participant attribute with the specified type, encryption setting, and default name. The attribute is set as visible by default.
Parameters
- $attributeData : array<string|int, mixed>
-
Array containing attribute configuration with keys:
- 'type': The attribute type (e.g., 'DD' for dropdown, 'TB' for textbox)
- 'encrypted': Whether the attribute should be encrypted ('Y' or 'N')
- $attributeName : string
-
The default name/identifier for the attribute (e.g., 'attribute_1')
Tags
Return values
int —The primary key (attribute_id) of the newly created attribute
convertDateToStoreFormat()
Converts a date string from a specified format to the standard storage format.
private
convertDateToStoreFormat(string $dateString, string $fromFormat) : string|false
This method takes a date string in a given format and converts it to the standard datetime format used for database storage (Y-m-d). If the conversion fails due to an invalid date string or format mismatch, false is returned.
Parameters
- $dateString : string
-
The date string to be converted
- $fromFormat : string
-
The PHP date format string that describes the input date format
Return values
string|false —The converted datetime string in 'Y-m-d' format, or false if conversion fails