# 5. Formatacao de Strings e Cores

## Introdução

O **PHP** (Hypertext Preprocessor) é uma linguagem de script amplamente utilizada no desenvolvimento web, mas também pode ser executada via linha de comando (CLI). Diferente do Bash, que usa códigos ANSI para formatação no terminal, o PHP oferece múltiplas formas de formatar strings e gerar saída, tanto para navegadores quanto para terminais. Esta documentação foca na **formatação de strings**, **funções de output**, e **códigos de cores ANSI** em ambientes CLI, detalhando sintaxe, comportamento do computador e exemplos práticos.

***

## Importação no PHP

Antes de explorar formatação, é importante entender como importar bibliotecas de formatação no PHP.

### Sintaxe Básica

```php
include 'caminho/para/formatacao.php';
require_once 'caminho/para/cores.php';
```

* **`include`**: Inclui o arquivo, emite warning se não encontrado.
* **`require`**: Inclui o arquivo, emite fatal error se não encontrado.
* **`_once`**: Garante inclusão única.

### Exemplo de Biblioteca de Formatação

**cores.php**:

```php
<?php
function vermelho($texto) {
    return "\033[31m{$texto}\033[0m";
}

function verde($texto) {
    return "\033[32m{$texto}\033[0m";
}

function amarelo($texto) {
    return "\033[33m{$texto}\033[0m";
}
```

**main.php**:

```php
<?php
require_once 'cores.php';

echo vermelho("Erro!") . PHP_EOL;
echo verde("Sucesso!") . PHP_EOL;
```

***

## Formatação de Strings no PHP

O PHP oferece diversas funções para manipular e formatar strings, essenciais para gerar saída estruturada e segura.

{% stepper %}
{% step %}

### Concatenação de Strings

```php
$nome = "Alice";
$idade = 25;

// Concatenação com ponto (.)
echo "Nome: " . $nome . ", Idade: " . $idade;

// Interpolação com aspas duplas
echo "Nome: $nome, Idade: $idade";

// Interpolação com chaves (recomendado)
echo "Nome: {$nome}, Idade: {$idade}";
```

* **Comportamento do Computador**:
  * O PHP processa strings entre aspas duplas (`"`) interpretando variáveis.
  * Aspas simples (`'`) tratam tudo como texto literal, sem interpolação.
  * A concatenação com `.` cria uma nova string em memória.
    {% endstep %}

{% step %}

### Funções de Formatação

#### `printf` e `sprintf`

```php
$nome = "Alice";
$idade = 25;
$altura = 1.65;

// printf: exibe diretamente
printf("Nome: %s, Idade: %d, Altura: %.2f", $nome, $idade, $altura);
// Saída: Nome: Alice, Idade: 25, Altura: 1.65

// sprintf: retorna a string formatada
$formatado = sprintf("Nome: %s, Idade: %d", $nome, $idade);
echo $formatado;
```

**Especificadores Comuns**:

| Especificador | Tipo                    |
| ------------- | ----------------------- |
| `%s`          | String                  |
| `%d`          | Inteiro decimal         |
| `%f`          | Float (ponto flutuante) |
| `%b`          | Binário                 |
| `%x`          | Hexadecimal (minúsculo) |
| `%X`          | Hexadecimal (maiúsculo) |

#### `number_format` (Formatação de Números)

```php
$numero = 1234567.891;

echo number_format($numero);             // 1,234,568
echo number_format($numero, 2);          // 1,234,567.89
echo number_format($numero, 2, ',', '.'); // 1.234.567,89
```

#### `str_pad` (Preenchimento de Strings)

```php
echo str_pad("Texto", 10, "-", STR_PAD_RIGHT);  // "Texto-----"
echo str_pad("Texto", 10, "-", STR_PAD_LEFT);   // "-----Texto"
echo str_pad("Texto", 10, "-", STR_PAD_BOTH);   // "--Texto---"
```

#### `str_replace` e `preg_replace`

```php
// Substituição simples
$texto = "Olá mundo!";
echo str_replace("mundo", "Alice", $texto);  // "Olá Alice!"

// Substituição com regex
$texto = "Data: 2024-01-15";
echo preg_replace("/(\d{4})-(\d{2})-(\d{2})/", "$3/$2/$1", $texto);
// Saída: Data: 15/01/2024
```

{% endstep %}

{% step %}

### Manipulação de Case

```php
$texto = "Olá Mundo!";

echo strtoupper($texto);    // "OLÁ MUNDO!"
echo strtolower($texto);    // "olá mundo!"
echo ucfirst($texto);       // "Olá mundo!" (primeira maiúscula)
echo ucwords($texto);       // "Olá Mundo!" (cada palavra maiúscula)
```

{% endstep %}

{% step %}

### Remoção de Espaços

```php
$texto = "  Texto com espaços  ";

echo trim($texto);          // "Texto com espaços"
echo ltrim($texto);         // "Texto com espaços  "
echo rtrim($texto);         // "  Texto com espaços"
```

{% endstep %}
{% endstepper %}

***

## Output no PHP

O PHP pode gerar saída para diferentes contextos: navegador web (HTML) ou terminal (CLI).

### 1. Saída para Navegador (HTML)

#### `echo` e `print`

```php
echo "Texto simples";
print "Texto com print";

echo "<h1>Título HTML</h1>";  // Renderizado como HTML
echo "<script>alert('JS!');</script>";  // Executa JavaScript
```

#### `var_dump` e `print_r` (Debug)

```php
$array = ["nome" => "Alice", "idade" => 25];

print_r($array);
/*
Array
(
    [nome] => Alice
    [idade] => 25
)
*/

var_dump($array);
/*
array(2) {
  ["nome"]=>
  string(5) "Alice"
  ["idade"]=>
  int(25)
}
*/
```

* **Comportamento do Computador**:
  * `var_dump` exibe tipo e comprimento, útil para debug.
  * `print_r` é mais legível para humanos.

### 2. Saída para CLI (Terminal)

Quando o PHP é executado via linha de comando, a saída vai para o terminal.

```bash
php script.php
```

#### Códigos ANSI no CLI

Assim como no Bash, o PHP suporta códigos ANSI para cores e estilos no terminal.

```php
<?php
// Cores no terminal
echo "\033[31mTexto vermelho\033[0m\n";
echo "\033[1;32mTexto verde em negrito\033[0m\n";
echo "\033[43mFundo amarelo\033[0m\n";
```

#### Função para Cores ANSI

```php
<?php
function cor($texto, $cor) {
    $cores = [
        'vermelho' => '31',
        'verde' => '32',
        'amarelo' => '33',
        'azul' => '34',
        'magenta' => '35',
        'ciano' => '36',
        'branco' => '37'
    ];
    
    $codigo = $cores[$cor] ?? '0';
    return "\033[{$codigo}m{$texto}\033[0m";
}

echo cor("Erro crítico!", "vermelho") . PHP_EOL;
echo cor("Operação concluída", "verde") . PHP_EOL;
```

#### `PHP_EOL` (End of Line)

```php
echo "Linha 1" . PHP_EOL;
echo "Linha 2" . PHP_EOL;
```

* **Comportamento do Computador**:
  * `PHP_EOL` é uma constante que contém o caractere de quebra de linha apropriado para o sistema operacional (`\n` no Linux/macOS, `\r\n` no Windows).

***

## Formatação Avançada de Strings

### 1. Heredoc e Nowdoc

#### Heredoc (interpreta variáveis)

```php
$nome = "Alice";
$texto = <<<TEXTO
Olá, $nome!
Esta é uma string multilinha.
Aspas "duplas" e 'simples' são permitidas.
TEXTO;

echo $texto;
```

#### Nowdoc (não interpreta variáveis)

```php
$nome = "Alice";
$texto = <<<'TEXTO'
Olá, $nome!  // Não será interpretado
Texto literal.
TEXTO;

echo $texto;  // Saída: Olá, $nome! Texto literal.
```

### 2. JSON (JavaScript Object Notation)

```php
$dados = [
    'nome' => 'Alice',
    'idade' => 25,
    'hobbies' => ['leitura', 'corrida']
];

// Codificar para JSON
$json = json_encode($dados, JSON_PRETTY_PRINT);
echo $json;

/*
{
    "nome": "Alice",
    "idade": 25,
    "hobbies": [
        "leitura",
        "corrida"
    ]
}
*/

// Decodificar JSON
$decodificado = json_decode($json, true);  // true = array associativo
print_r($decodificado);
```

### 3. XML

```php
$xml = new SimpleXMLElement('<root/>');
$xml->addChild('nome', 'Alice');
$xml->addChild('idade', 25);

echo $xml->asXML();
```

### 4. HTML Entities (Segurança)

```php
$input = "<script>alert('XSS');</script>";

// Escapa caracteres especiais HTML
$seguro = htmlspecialchars($input, ENT_QUOTES, 'UTF-8');
echo $seguro;  // &lt;script&gt;alert(&#039;XSS&#039;);&lt;/script&gt;
```

***

## Funções Avançadas de Output

### 1. `ob_start()` (Output Buffering)

Permite capturar toda a saída antes de enviá-la ao navegador.

```php
<?php
ob_start();  // Inicia buffer

echo "Isso será capturado";
echo " e isso também";

$conteudo = ob_get_clean();  // Captura e limpa buffer
echo "Conteúdo capturado: " . $conteudo;
```

* **Comportamento do Computador**:
  * A saída é armazenada em memória em vez de ser enviada imediatamente.
  * Útil para manipular headers ou comprimir conteúdo.

### 2. `header()` (Cabeçalhos HTTP)

```php
// Redirecionamento
header('Location: https://exemplo.com');
exit;

// Definir conteúdo JSON
header('Content-Type: application/json');
echo json_encode(['status' => 'ok']);

// Download de arquivo
header('Content-Type: application/pdf');
header('Content-Disposition: attachment; filename="arquivo.pdf"');
readfile('documento.pdf');
```

### 3. `http_response_code()`

```php
http_response_code(404);
echo "Página não encontrada";
```

***

## Formatação para Logs e Debug

### 1. `error_log()`

```php
error_log("Erro de conexão com banco de dados");
error_log("Mensagem detalhada", 3, "/var/log/meu_app.log");
```

### 2. Formatação de Data/Hora

```php
date_default_timezone_set('America/Sao_Paulo');

echo date('Y-m-d H:i:s');  // 2024-01-15 14:30:00
echo date('d/m/Y');        // 15/01/2024

$timestamp = time();
echo date('H:i:s', $timestamp);
```

### 3. Log Estruturado

```php
function log_formatado($nivel, $mensagem) {
    $timestamp = date('Y-m-d H:i:s');
    return "[{$timestamp}] [{$nivel}] {$mensagem}" . PHP_EOL;
}

file_put_contents('app.log', log_formatado('ERROR', 'Falha na conexão'), FILE_APPEND);
```

***

## Biblioteca Completa de Formatação

**formatacao.php**:

```php
<?php
class Formatador {
    // Cores ANSI (CLI)
    private static $cores = [
        'vermelho' => '31',
        'verde' => '32',
        'amarelo' => '33',
        'azul' => '34',
        'magenta' => '35',
        'ciano' => '36'
    ];
    
    public static function cor($texto, $cor) {
        if (PHP_SAPI === 'cli') {
            $codigo = self::$cores[$cor] ?? '0';
            return "\033[{$codigo}m{$texto}\033[0m";
        }
        return $texto;  // Web: sem cores
    }
    
    public static function tabela($dados) {
        if (empty($dados)) return '';
        
        $headers = array_keys($dados[0]);
        $output = "";
        
        // Cabeçalho
        foreach ($headers as $header) {
            $output .= str_pad($header, 15) . " ";
        }
        $output .= PHP_EOL;
        $output .= str_repeat("-", 15 * count($headers)) . PHP_EOL;
        
        // Dados
        foreach ($dados as $linha) {
            foreach ($headers as $header) {
                $output .= str_pad($linha[$header], 15) . " ";
            }
            $output .= PHP_EOL;
        }
        
        return $output;
    }
    
    public static function json_pretty($dados) {
        return json_encode($dados, JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
    }
}
```

**Uso**:

```php
<?php
require_once 'formatacao.php';

// CLI com cores
echo Formatador::cor("[SUCESSO] Operação concluída", "verde") . PHP_EOL;

// Tabela formatada
$usuarios = [
    ['nome' => 'Alice', 'idade' => 25, 'cidade' => 'São Paulo'],
    ['nome' => 'Bob', 'idade' => 30, 'cidade' => 'Rio de Janeiro']
];
echo Formatador::tabela($usuarios);

// JSON formatado
$dados = ['status' => 'ok', 'mensagem' => 'Processado com sucesso'];
echo Formatador::json_pretty($dados);
```

***

## Boas Práticas para Formatação e Output

* **Escapar saída para HTML**: Use `htmlspecialchars()` para evitar XSS.
* **Use `sprintf` para strings complexas**: Melhor legibilidade que concatenação excessiva.
* **Verifique o ambiente**: `PHP_SAPI === 'cli'` para saber se está no terminal.
* **Cores apenas em CLI**: Em navegador, cores ANSI não funcionam.
* **Use `PHP_EOL` para quebras de linha**: Mantém portabilidade entre SOs.
* **Buffer de saída**: Use `ob_start()` quando precisar manipular headers após conteúdo.
* **Logs estruturados**: Inclua timestamp, nível e contexto.

***

## Resumo para Segurança

| Prática                 | Risco                       | Mitigação                              |
| ----------------------- | --------------------------- | -------------------------------------- |
| Saída não escapada      | XSS (Cross-Site Scripting)  | `htmlspecialchars()`                   |
| Headers após conteúdo   | Erro "headers already sent" | Buffer de saída ou mover lógica        |
| Dados sensíveis em logs | Exposição de informações    | Redação ou exclusão de dados sensíveis |
| Cores ANSI em navegador | Códigos visíveis como texto | Detectar ambiente (`PHP_SAPI`)         |

***

## Recursos Adicionais

* Manual: [PHP: Strings](https://www.php.net/manual/pt_BR/language.types.string.php)
* Manual: [PHP: printf](https://www.php.net/manual/pt_BR/function.printf.php)
* Manual: [PHP: Output Control](https://www.php.net/manual/pt_BR/book.outcontrol.php)
* Manual: [PHP: JSON](https://www.php.net/manual/pt_BR/book.json.php)
* ANSI Escape Codes: [Wikipedia](https://en.wikipedia.org/wiki/ANSI_escape_code)
* OWASP: [XSS Prevention Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Cross_Site_Scripting_Prevention_Cheat_Sheet.html)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://0xmorte.gitbook.io/bibliadopentestbr/conceitos/programacao-e-linguagens/php/5.-formatacao-de-strings-e-cores.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.