Пример рефакторинга «извлечение функции» для кода добавления нового поля

Исходный код

$key_tr = $_key-1;  //// Последний ключ массива (получаем для размещения не базового поля (Media file) на строку выше положенного)
$new = new stdClass;
$new->caption = "Media File";
$new->name = "media";
$new->table = "media";
$new->type = "file";
if ($role == "transcriber")
    $new->read_only = "read_only";
$fields[$key_tr.'.5'] = $new;

ksort($fields);

Что не так в этом коде

В этом коде смешаны две разных ответственности (два разных знания):

создать новый элемент
добавить новый элемент в список существующих

Рецепт, как обычно — рефакторинг «извлечение метода».

Второй сомнительный момент в коде — хак с вставкой элемента внутрь существующего массива. Его можно спокойно заменить на array_splice.

Пример рефакторинга

function newMediaFile($role) {
    $new = new stdClass;
    $new->caption = "Media File";
    $new->name = "media";
    $new->table = "media";
    $new->type = "file";
    if ($role == "transcriber")
        $new->read_only = "read_only";
    return $new;
}

array_splice($fields, $_key - 1, 0, [new MediaFile($role)]);

Теория

Принцип единственного знания
Рефакторинг «извлечение метода»