uksort()

Introducción

uksort() ordena un array por sus claves usando una función de comparación que tú mismo escribes. A diferencia de ksort(), que solo ordena las claves en su orden ascendente natural, uksort() te permite decidir el orden — alfabético, inverso, por longitud de cadena, por una lista de prioridades personalizada, o cualquier regla que puedas expresar en código. La asociación clave-valor siempre se preserva.

Esta página cubre la sintaxis y el valor de retorno, cómo funciona el callback de comparación, varios ejemplos ejecutables (incluyendo el operador spaceship), errores comunes, y cómo uksort() difiere de las funciones de ordenación relacionadas.

Sintaxis

uksort(array &$array, callable $callback): true

• $array — el array a ordenar. Se pasa por referencia y se ordena in situ, por lo que la variable original se modifica directamente.
• $callback — una función de comparación que recibe dos claves ($a y $b) y devuelve un entero:
  • un número negativo si $a debe ir antes que $b,
  • 0 si se consideran iguales,
  • un número positivo si $a debe ir después de $b.

La función devuelve true (en PHP 8+; antes devolvía un bool). Como la ordenación ocurre por referencia, lees el resultado desde la variable del array original — no desde el valor de retorno.

El callback compara claves, no valores. Ese es el único hecho que distingue uksort() de usort() (que compara valores) y uasort() (que compara valores pero mantiene la asociación de claves).

Ejemplo básico: ordenar claves alfabéticamente

Supongamos que tenemos un array de frutas indexado por nombre, y queremos que estén en orden alfabético por clave:

<?php

$fruits = [
    "orange" => 3,
    "apple"  => 2,
    "banana" => 1,
];

function cmp($a, $b)
{
    return strcmp($a, $b);
}

uksort($fruits, "cmp");

print_r($fruits);

strcmp() ya devuelve un entero negativo, cero o positivo, por lo que encaja directamente en el callback. La salida está ordenada por clave:

Array
(
    [apple] => 2
    [banana] => 1
    [orange] => 3
)

Usando el operador spaceship

Desde PHP 7, el operador spaceship <=> devuelve -1, 0 o 1 para menor que, igual o mayor que — exactamente el formato que uksort() espera. Con una arrow function, el callback se convierte en una sola línea:

<?php

$data = ["delta" => 1, "alpha" => 2, "charlie" => 3, "bravo" => 4];

uksort($data, fn($a, $b) => $a <=> $b);

print_r($data);

Esto ordena las claves de forma ascendente:

Array
(
    [alpha] => 2
    [bravo] => 4
    [charlie] => 3
    [delta] => 1
)

Para invertir el orden, intercambia los operandos: fn($a, $b) => $b <=> $a.

Un orden personalizado

El verdadero poder de uksort() es ordenar por una regla que ninguna función incorporada proporciona — por ejemplo, por longitud de clave, y luego alfabéticamente en caso de empate:

<?php

$config = [
    "id"          => 1,
    "name"        => "Ann",
    "is_active"   => true,
    "x"           => 0,
];

uksort($config, function ($a, $b) {
    return strlen($a) <=> strlen($b)   // shortest keys first
        ?: strcmp($a, $b);             // ties broken alphabetically
});

print_r($config);

El operador ?: en cortocircuito devuelve la comparación por longitud a menos que sea 0, en cuyo caso recurre a la comparación alfabética:

Array
(
    [x] => 0
    [id] => 1
    [name] => Ann
    [is_active] => 1
)

Errores comunes

• Devuelve true, no el array ordenado. Escribir $sorted = uksort($arr, ...) te da true. Usa $arr después en su lugar.
• El array original se muta. Cópialo primero ($copy = $arr;) si necesitas conservar el orden original.
• El callback debe ser consistente. Devolver valores aleatorios (p. ej., rand(-1, 1)) produce resultados indefinidos. Para mezclar, usa shuffle() en los valores o array_rand() en las claves.
• Devuelve un entero. Devolver un bool funciona por coerción pero es frágil — false se convierte en 0 (igual), por lo que return $a < $b; es un error. Usa <=> o strcmp().

Cómo se compara uksort() con funciones relacionadas

En resumen: usa uksort() siempre que necesites ordenar un array asociativo por sus claves con una regla que ksort() no puede expresar. Para más información sobre el tema, consulta Ordenar Arrays en PHP.

Conclusión

uksort() ordena un array asociativo por sus claves usando un callback de comparación que tú controlas, modificando el array in situ y preservando los vínculos clave-valor. Con el operador spaceship el callback es conciso, y la lógica personalizada te permite implementar ordenaciones que ninguna función incorporada ofrece.

Diagrama

graph LR
A[Array] --> B(Function);
B --> C[Comparison result];
C --> D{Is result negative?};
D -->|Yes| E[Swap];
C -->|No| F[Do not swap];
F --> G[Next comparison];
E --> G[Next comparison];

Práctica