ORDER_ASC
ORDER_ASC
Identificador de ordenação crescente.
Wrapper para array e suas funções da biblioteca padrão do PHP.
Na minha opinião (e na de muitos desenvolvedores, para falar a verdade), um dos piores aspectos do desenvolvimento em PHP é a nomenclatura das funções da biblioteca padrão. Muitas funções recebem nomes absolutamente idiotas por razões históricas (basicamente, "o nome da função C que executa isso é esse, vamos usar o mesmo nome"), o que acabou não só trazendo antigos hábitos de nomenclatura para dentro de uma linguagem que se pretende moderna, como ainda introduziu alguns novos maus hábitos de nomenclatura novos. E isso sem falar em problemas com ordem de parâmetros inconsistente, comportamentos inconsistentes entre funções que deveriam ser parecidas, etc.
Esta classe visa prover uma interface normalizada e uniforme para estas funções de array, de modo que o desenvolvedor possa facilmente autocompletá-las utilizando uma IDE minimamente decente sem ter que ficar lembrando ou consultando a documentação do PHP para lembrar exatamente como determinada função funciona. Eu acredito que os beneficios de clareza e legibilidade superem o custo de overhead de uma chamada a mais de função para executar a operação.
No desenvolvimento desta parte da biblioteca, meu objetivo foi manter um equilíbrio entre o padrão minimalista de nomes do PHP nativo e a ridícula verbosidade de nomes estilo Java. Abreviações, quando fazem sentido, foram mantidas.
getChave(array $array, mixed $valor) : array
Retorna todas as chaves do array que possuam o valor informado.
Ao contrário do funcionamento normal da função array_keys(), a comparação é sempre feita de forma estrita (operador ===).
\Numenor\Php\ArrayWrapper::getChave(array('A', 'B', 'C', 'first' => 'A', 'second' => 'B'), 'A');
// [0, 'first']
| array | $array | O array. |
| mixed | $valor | O valor para o qual se quer as chaves. |
Lista de chaves que possuem o valor informado.
getItemAleatorio(array $array, integer $numeroItens = 1) : mixed|array
Retorna um ou mais itens do array escolhidos aleatoriamente.
| array | $array | O array. |
| integer | $numeroItens | Número de itens desejados. O padrão é 1 (apenas um item). |
O item escolhido aleatoriamente, caso $numeroItens seja um; um array com $numeroItens escolhidos aleatoriamente, caso contrário.
getValorColuna(array $array, string $colunaChave, string $chaveIndice = '') : array
Retorna todos os valores de uma única coluna de um array multidimensional, como se fosse uma tabela.
$array = [
[
'id' => 2135,
'first_name' => 'John',
'last_name' => 'Doe',
],
[
'id' => 3245,
'first_name' => 'Sally',
'last_name' => 'Smith',
],
[
'id' => 5342,
'first_name' => 'Jane',
'last_name' => 'Jones',
],
[
'id' => 5623,
'first_name' => 'Peter',
'last_name' => 'Doe',
]
];
\Numenor\Php\ArrayWrapper::getValorColuna($array, 'first_name');
// ['John', 'Sally', 'Jane', 'Peter']
\Numenor\Php\ArrayWrapper::getValorColuna($array, 'first_name', 'id');
// [2135 => 'John', 3245 => 'Sally', 5342 => 'Jane', 5623 => 'Peter']
| array | $array | O array. |
| string | $colunaChave | Nome da chave representando a coluna dos valores desejados. |
| string | $chaveIndice | Nome da chave da coluna cujos valores serão usados como chave dos array resultante. |
se o número de parâmetros informados é inferior ao mínimo necessário (1).
se o parâmetro $columnKey não é do tipo {String}, ou não pode ser convertido para uma string.
se o parâmetro $indexKey foi informado e não é do tipo {String}, ou não pode ser convertido para uma string.
Lista de todos os valores da coluna correspondente.
encontrarItem(array $array, mixed $item) : mixed
Busca um item no array, retornando a chave correspondente ao item se encontrado.
| array | $array | O array. |
| mixed | $item | O item buscado. |
se o item não existe no array.
A chave correspondente ao item encontrado no array.
verificarChave(array $array, string|integer $chave) : boolean
Verifica a existência de uma chave no array.
| array | $array | O array. |
| string|integer | $chave | Chave a ser verificada no array |
se a chave não puder ser convertida para um tipo válido (string ou inteiro).
TRUE caso a chave exista no array, FALSE caso contrário.
inserir(array $array, mixed $item, integer|string $chave)
Insere um item no array com a chave indicada.
Se a chave já existir, substitui o valor.
| array | $array | O array. |
| mixed | $item | O item a ser inserido no array. |
| integer|string | $chave | A chave onde o item deve ser inserido. |
se a chave não puder ser convertida para um tipo válido (string ou inteiro).
remover(array $array, integer|string $chave) : mixed
Remove um item do array com a chave indicada.
O array é reindexado após a remoção, atualizando suas chaves numéricas. As chaves string não são afetadas.
| array | $array | O array. |
| integer|string | $chave | A chave do item a ser removido. |
se a chave não existir no array.
Item removido do array.
criar(integer $inicio, integer $quantidadeItens, mixed $item) : array
Cria um array preenchido com um único valor repetido $quantidadeItens vezes.
Ao contrário da função array_fill(), foi optado por não permitir que o índice seja negativo, nem que o número de itens seja menor do que 1.
| integer | $inicio | Índice inicial do array gerado. |
| integer | $quantidadeItens | Número de itens do array gerado. |
| mixed | $item | Valor colocado em todas as posições do array. |
se o $inicio informado for negativo.
se $quantidadeItens for um valor menor do que 1.
O array gerado.
dividir(array $array, integer $tamanho, boolean $preservarChaves = false) : array
Divide o array em pedaços menores.
| array | $array | O array. |
| integer | $tamanho | Tamanho máximo dos pedaços do array. O último pedaço pode ser menor do que o tamanho indicado. |
| boolean | $preservarChaves | Indica se os pedaços devem preservar as suas chaves originais. |
Array multidimensional contendo os pedaços do array.
combinar(array $chaves, array $valores) : array
Combina dois arrays em um único array, utilizando os valores do primeiro array informado como chaves e os valores do segundo array informado como valores no array resultante.
| array | $chaves | Array de chaves. |
| array | $valores | Array de valores. |
se os dois arrays informados não têm o mesmo tamanho.
Combinação dos dois arrays informados.
preencher(array $array, integer $novoTamanho, mixed $valor) : array
Preenche o array com um valor informado até o tamanho informado.
Se o $novoTamanho for um número positivo, os itens são acrescentados no final do array.
Se o $novoTamanho for um número negativo, os itens são acrescentados no início do array.
| array | $array | O array. |
| integer | $novoTamanho | Novo tamanho desejado para o array. |
| mixed | $valor | Valor a ser inserido nas novas posições do array. |
O array preenchido com os novos valores.
flip(array $array) : array
Inverte o array de forma que as chaves tornem-se valores e vice-versa.
Como a função array_flip() não interrompe a execução caso os valores do array não possam ser usados como chave, apenas emite um warning, foi acrescentado um laço extra para verificar todos os itens do array e levantar uma exceção caso isso ocorra. Por essa razão, a implementação deste método pode não ser indicada para processamento de alta performance.
| array | $array | O array. |
se qualquer um dos valores do array não poder ser convertido para um tipo que possa ser usado como chave do array invertido (string ou inteiro).
Array com as chaves e valores invertidos.
chaveMinuscula(array $array, \Numenor\Php\StringWrapper $stringWrapper) : array
Retorna uma cópia do array com os caracteres das suas chaves alterados para letras minúsculas.
Funciona para chaves com codificação UTF-8.
| array | $array | O array. |
| \Numenor\Php\StringWrapper | $stringWrapper | Instância do objeto de encapsulamento das operações de strings. |
O array com as chaves alteradas.
chaveMaiuscula(array $array, \Numenor\Php\StringWrapper $stringWrapper) : array
Retorna uma cópia do array com os caracteres das suas chaves alterados para letras maiúsculas.
Funciona para chaves com codificação UTF-8.
| array | $array | O array. |
| \Numenor\Php\StringWrapper | $stringWrapper | Instância do objeto de encapsulamento das operações de strings. |
O array com as chaves alteradas.
interseccao(array $array1, array $array2) : array
Retorna a intersecção entre dois arrays, ou seja, todos os elementos que estão presentes em ambos os arrays, preservando as chaves dos mesmos.
Caso um elemento tenha chaves diferentes nos dois arrays, a chave mantida é a chave do primeiro array. Ao contrário da função array_intersect(), este método trabalha com apenas dois arrays de cada vez.
$array1 = array('A', 'B', 'C');
$array2 = array('first' => 'A', 'second' => 'D', 'third' => 'C');
\Numenor\Php\ArrayWrapper::interseccao($array1, $array2);
// ['A', 'C']
| array | $array1 | Primeiro array. |
| array | $array2 | Segundo array. |
Intersecção dos dois arrays comparados.
interseccaoChaves(array $array1, array $array2) : array
Retorna a intersecção de chaves entre dois arrays, ou seja, todos as chaves que estão presentes em ambos os arrays, preservando os valores dos mesmos.
Caso uma chave tenha valores diferentes nos dois arrays, o valor mantido é o valor do primeiro array.
Ao contrário da função array_intersect_key(), este método trabalha com apenas dois arrays de cada vez.
$array1 = array('A', 'second' => 'B', 'third' => 'C');
$array2 = array('first' => 'A', 'second' => 'D', 'final' => 'C');
\Numenor\Php\ArrayWrapper::interseccaoChaves($array1, $array2);
// ['A', 'second' => 'B']
| array | $array1 | Primeiro array. |
| array | $array2 | Segundo array. |
Intersecção da chaves dos dois arrays comparados.
intersecacaoAssociativa(array $array1, array $array2) : array
Retorna a intersecção entre o dois arrays, ou seja, todos os elementos que estão presentes em ambos os arrays, considerando tanto os valores quanto as chaves do mesmo.
Ao contrário da função array_intersect_assoc(), este método trabalha com apenas dois arrays de cada vez.
$array1 = array('A', 'B', 'C');
$array2 = array('A', 'second' => 'D', 'third' => 'C');
\Numenor\Php\ArrayWrapper::interseccaoAssociativa($array1, $array2);
// ['A']
| array | $array1 | Primeiro array. |
| array | $array2 | Segundo array. |
Array contendo a intersecção dos dois arrays comparados.
diferenca(array $array1, array $array2) : array
Retorna a diferença entre o primeiro e o segundo array, ou seja, todos os elementos do primeiro array que não estão presentes no segundo array.
Ao contrário da função array_diff(), este método trabalha com apenas dois arrays de cada vez.
$array1 = array('A', 'B', 'C');
$array2 = array('first' => 'A', 'second' => 'D', 'third' => 'C');
\Numenor\Php\ArrayWrapper::diferenca($array1, $array2);
// ['B']
| array | $array1 | Primeiro array. |
| array | $array2 | Segundo array. |
Array contendo a diferença entre os dois arrays comparados.
diferencaAssociativa(array $array1, array $array2) : array
Retorna a diferença entre o array instanciado e o array informado, ou seja, todos os elementos do primeiro array que não estão presentes no segundo array, considerando tanto os valores quanto as chaves do mesmo.
Ao contrário da função array_diff_assoc(), este método trabalha com apenas dois arrays de cada vez.
$array1 = array('A', 'B', 'C');
$array2 = array('A', 'second' => 'D', 'third' => 'C');
\Numenor\Php\ArrayWrapper::diferencaAssociativa($array1, $array2);
// ['B', 'C']
| array | $array1 | Primeiro array. |
| array | $array2 | Segundo array. |
Array contendo a diferença entre os dois arrays comparados.
filtrar(array $array, callable $funcaoFiltro, integer $flag) : array
Filtra o array através de uma função de callback.
A função de callback é chamada para cada item do array; se ela retornar true, o item é incluído no array filtrado.
| array | $array | O array. |
| callable | $funcaoFiltro | Função aplicada em cada item do array filtrado. |
| integer | $flag | Flag determinando quais parâmetros são enviados para a função de callback. Se não for informado, o valor do item é informado; caso seja informado, deve ser uma das seguintes constantes: ARRAY_FILTER_USE_KEY (envia a chave do valor como único parâmetro) ou ARRAY_FILTER_USE_BOTH (envia o valor e a chave como parâmetros). |
se o parâmetro $flag for informado com um valor inválido.
O array filtrado.
aplicarCallback(array $array, callable $callback) : array
Aplica uma função de callback em cada item do array.
| array | $array | O array. |
| callable | $callback | Função de callback aplicada em cada item do array. A função deve aceitar um parâmetro, correspondente ao item do array sendo percorrido. |
O array alterado.
mesclar(array $array1, array $array2) : array
Mescla dois arrays.
Caso uma mesma chave esteja presente em ambos os arrays, então o array resultante terá o valor do segundo array nesta chave.
Ao contrário da função array_merge(), este método trabalha com apenas dois arrays de cada vez.
| array | $array1 | Primeiro array. |
| array | $array2 | Segundo array. |
O array resultante da mescla dos dois arrays.
ordenar(array $array, string $ordem = self::ASC, integer $tipoOrdenacao = \SORT_STRING) : array
Ordena o array, utilizando a implementação nativa do PHP para o algoritmo Quicksort.
Ao contrário da maioria das funções de array da biblioteca padrão, a função sort() não retorna uma cópia do array informado; ao invés disso, o parâmetro é passado por referência, e a função retorna um valor booleano. Para fins de padronização, este método retorna uma cópia do array.
ATENÇÃO: as chaves do array ordenado não são preservadas; o array é reindexado com chaves numéricas, o que pode ou não ser o comportamento desejado.
| array | $array | O array. |
| string | $ordem | Indica se a ordenação deve ser em ordem crescente ou decrescente. |
| integer | $tipoOrdenacao | Indica o tipo de comparação feita entre os valores:
|
se a ordem não corresponde a uma das ordens aceitas (crescente ou decrescente).
se o tipo de ordenação não corresponde a um dos tipos de ordenação aceitos.
O array ordenado.
ordenarAssociativo(array $array, string $ordem = self::ASC, integer $tipoOrdenacao = SORT_STRING) : array
Ordena o array, utilizando a implementação nativa do PHP para o algoritmo Quicksort, e mantendo a associação entre chaves e valores.
Ao contrário da maioria das funções de array da biblioteca padrão, a função sort() não retorna uma cópia do array informado; ao invés disso, o parâmetro é passado por referência, e a função retorna um valor booleano.
Para fins de padronização, este método retorna uma cópia do array.
| array | $array | O array. |
| string | $ordem | Indica se a ordenação deve ser em ordem crescente ou decrescente. |
| integer | $tipoOrdenacao | Indica o tipo de comparação feita entre os valores:
|
se a ordem não corresponde a uma das ordens aceitas (crescente ou decrescente).
se o tipo de ordenação não corresponde a um dos tipos de ordenação aceitos.
O array ordenado, com as suas chaves preservadas.
ordenarChave(array $array, string $ordem = self::ASC, integer $tipoOrdenacao = SORT_STRING) : array
Ordena o array pelas suas chaves, utilizando a implementação nativa do PHP para o algoritmo Quicksort.
Ao contrário da maioria das funções de array da biblioteca padrão, a função ksort() não retorna uma cópia do array informado; ao invés disso, o parâmetro é passado por referência, e a função retorna um valor booleano.
Para fins de padronização, este método retorna uma cópia do array.
| array | $array | O array. |
| string | $ordem | Indica se a ordenação deve ser em ordem crescente ou decrescente. |
| integer | $tipoOrdenacao | Indica o tipo de comparação feita entre os valores:
|
se a ordem não corresponde a uma das ordens aceitas (crescente ou decrescente).
se o tipo de ordenação não corresponde a um dos tipos de ordenação aceitos.
O array ordenado pelas chaves.
validarTipoChave(mixed $chave) : boolean
Valida o tipo de uma chave de array.
Uma chave é considerada válida se ela for um inteiro, uma string, ou um objeto representável como uma string (ou seja, um objeto que implemente o método __toString).
| mixed | $chave | A chave a ser validada. |
TRUE se a chave é de um tipo válido, FALSE caso contrário.