Adding Custom Fields

// Upsert. $values is a map of name => value; a custom field's name is "field_{id}".
// Returns true when at least one row was written.
public static function AddInfo($owner_id = 0, $values = []);
public static function setInfo($owner_id = 0, $values = []);   // alias of AddInfo

// Read. $names is an array (a comma separated string is also accepted and split).
// Returns a map with EVERY requested name present; a missing row reads as null.
// $noCache = true skips the per-request memo, which you need right after a write.
public static function getInfo($owner_id = 0, $names = [], $noCache = false): array;

// Remove rows entirely. $name is a single name or an array of names.
public static function deleteInfo($owner_id = 0, $name = ''): int|bool;

// Row id of an existing value, 0 when there is none.
public static function isInfo($owner_id = 0, $name = ''): int;

// Reverse lookup: which members hold this value. $first = true returns one row.
public static function findInfo($name = '', $value = '', $first = true): array;

// The completeness gate. Returns [field key => label] for everything still empty;
// an empty array means the account may use the client area.
public static function missing_required_fields($id = 0): array;

// Fired from User::AddInfo(), immediately before the insert or update.
// $value      mixed, by reference. What you leave here is what is stored.
// $field_id   int, the definition id parsed out of "field_5".
// $owner_id   int, the member the value belongs to.
Hook::add('filter:custom_field.save_value', 10, function (&$value, $field_id, $owner_id) {
    // ...
});

// Fired from User::getInfo(), after the rows are collected and before they are returned.
// Same three arguments, same order.
Hook::add('filter:custom_field.load_value', 10, function (&$value, $field_id, $owner_id) {
    // ...
});

// Department axis, used by the ticket CREATE form. $did = 0 returns every field.
// Rows carry the localized name, description, type, properties and options, plus
// department_name. Ordered by did DESC, then rank ASC.
public static function custom_fields($lang = '', $did = 0, $status = '');

// Access-group axis, used by the REPLY composer's credential rows. Reads the group's
// own comma separated list of field ids and returns them IN THAT ORDER, which is the
// drag-and-drop order the operator set. An empty group returns [].
public static function custom_fields_by_group($lang = '', $groupId = 0, $status = 'active');

// The groups themselves, for building the selector.
public static function access_groups($lang = '', $status = 'active');
public static function get_access_group($id = 0, $lang = '', $select = '');

// The definition ids of the same logical field in each installed language. A client
// field is one row per language, so a single label maps to several ids.
const ACME_TAX_FIELD_IDS = [11, 12];

Hook::add('filter:custom_field.save_value', 10, function (&$value, $field_id, $owner_id) {
    if (!in_array($field_id, ACME_TAX_FIELD_IDS, true)) return;

    $value = trim((string) $value);
    if ($value === '') return;                      // an empty answer stays empty

    $value = Crypt::encode($value, Config::get('crypt/system') . '_ACME_TAX');
});

Hook::add('filter:custom_field.load_value', 10, function (&$value, $field_id, $owner_id) {
    if (!in_array($field_id, ACME_TAX_FIELD_IDS, true)) return;
    if ((string) $value === '') return;

    // decode() returns false on a value that was written before this listener existed,
    // so the original text is kept rather than blanking the member's answer.
    $plain = Crypt::decode((string) $value, Config::get('crypt/system') . '_ACME_TAX');
    if ($plain !== false) $value = $plain;
});

$uid = 42;

// Ask for the names you want. Every name comes back, missing rows as null.
$info = User::getInfo($uid, ['field_11', 'gsm']);
$tax  = (string) ($info['field_11'] ?? '');

// A multi-choice field is one comma joined string; split it back yourself.
$picked = array_values(array_filter(explode(',', (string) ($info['field_12'] ?? ''))));

// Write. The same names, the same "field_{id}" convention.
User::setInfo($uid, ['field_11' => 'GB123456789']);

// The reader memoises per request, so re-read with the third argument after a write.
$fresh = User::getInfo($uid, ['field_11'], true);

// Removing a row is not the same as writing an empty string: only the removal makes
// the account look like one that never answered.
if ($tax === '') User::deleteInfo($uid, ['field_11']);

$ids = [];

foreach (['en' => 'VAT Number', 'tr' => 'Vergi Numarası'] as $lang => $label) {
    $ids[$lang] = WDB::insert('users_custom_fields', [
        'lang'          => $lang,
        'type'          => 'text',       // text | textarea | select | checkbox | radio
        'name'          => $label,
        'status'        => 'active',     // STRING, unlike every flag below
        'required'      => 0,
        'uneditable'    => 0,
        'client_hidden' => 0,
        'invoice'       => 1,
        'signForm'      => 1,
        'options'       => '',           // comma separated, for select/checkbox/radio
        'rank'          => 90,
    ]) ? WDB::lastID() : 0;
}

// Keep the ids: they are the only stable handle to the field, and they differ per language.
Config::setd('acme_vat_field_ids', Utility::jencode($ids));