join()

Introdução

A função join() em PHP une os elementos de um array em uma única string, colocando um separador (frequentemente chamado de "cola") entre cada elemento. É um alias de implode() — as duas funções são idênticas, portanto você pode usar o nome que tornar o código mais legível.

Esta página aborda a sintaxe de join(), as duas formas de chamá-la, o que acontece com valores de tipos mistos e valores aninhados, e os erros comuns a evitar.

Sintaxe

join(string $separator, array $array): string
join(array $array): string

• $separator — a string de cola inserida entre cada elemento. Se omitido, uma string vazia "" é utilizada.
• $array — o array cujos valores são unidos. Apenas os valores são usados; as chaves do array são ignoradas.

A função retorna a string unida.

Ordem dos argumentos: Como join() é um alias de implode(), a ordem histórica "separador primeiro, array segundo" é a que você deve usar. A forma legada onde o array vinha primeiro foi removida no PHP 8.0.

Exemplo básico

Isso produz:

apple, banana, orange

Aqui join() une os três valores com ", " entre eles. O resultado é armazenado em $fruit_string e exibido com echo.

Unindo sem separador

Se você chamar join() apenas com o array, os elementos são concatenados diretamente sem nada entre eles:

<?php

$parts = ["2024", "06", "21"];
echo join($parts);        // 20240621
echo "\n";
echo join("-", $parts);   // 2024-06-21

Como os valores são convertidos

Cada valor é convertido para string antes de ser unido, seguindo as regras normais de conversão de string do PHP:

<?php

$mixed = [1, 2.5, true, false, null, "text"];
echo join("|", $mixed);

Isso produz:

1|2.5|1|||text

Observe que true se torna "1", enquanto false e null se tornam strings vazias — é por isso que você vê separadores | consecutivos. Tenha cuidado ao unir arrays que possam conter booleanos ou null.

Construindo saída no estilo CSV ou HTML

join() é útil sempre que você precisa transformar uma lista em texto — strings de consulta, linhas CSV ou uma lista de atributos HTML:

<?php

$row = ["Alice", "[email protected]", "Admin"];
echo join(",", $row);        // Alice,[email protected],Admin
echo "\n";

$classes = ["btn", "btn-primary", "active"];
echo '<button class="' . join(" ", $classes) . '">OK</button>';

Erros comuns

• Arrays multidimensionais não funcionam. join() só achata um nível. Um elemento de array aninhado é convertido para a string literal "Array" e emite um aviso. Achate os dados primeiro.
• join() é o inverso de explode(). Use explode() para dividir uma string de volta em um array, e join()/implode() para reconstituí-la.
• As chaves são descartadas. Tanto as chaves numéricas quanto as de string são ignoradas; apenas os valores são unidos, na sua ordem interna.

Funções relacionadas

• implode() — função idêntica sob seu nome primário.
• explode() — divide uma string em um array (a operação inversa).
• str_split() — divide uma string em partes de tamanho fixo.

Prática