Primeiros Passos — PHP

Índice

• Requisitos
• Instalação
• Uso Básico
• Sistema de Plugins

Ver também:

• Consultas e Filtros
• Formatos & Utilitários
• Recursos Avançados
• Segurança & Integrações

Requisitos

• PHP 8.2 ou superior
• ext-json (embutido)
• ext-simplexml (embutido, para suporte XML)

Suporte a YAML e TOML está incluído sem configuração. YAML prefere ext-yaml quando disponível, caindo para symfony/yaml. TOML usa devium/toml. Ambos são instalados como dependências.

Instalação

composer require safe-access-inline/safe-access-inline

Uso Básico

Acessando dados com notação de ponto

use SafeAccessInline\SafeAccess;

$json = '{"user": {"profile": {"name": "Ana", "age": 30}}}';
$accessor = SafeAccess::fromJson($json);

// Acesso simples
$accessor->get('user.profile.name');     // "Ana"
$accessor->get('user.profile.age');      // 30

// Acesso seguro — nunca lança, retorna valor padrão
$accessor->get('user.email', 'N/A');     // "N/A"
$accessor->get('nonexistent.path');      // null (padrão)

// Verificar existência
$accessor->has('user.profile.name');     // true
$accessor->has('user.email');            // false

Trabalhando com arrays

$data = [
    'users' => [
        ['name' => 'Ana', 'role' => 'admin'],
        ['name' => 'Bob', 'role' => 'user'],
        ['name' => 'Carol', 'role' => 'user'],
    ],
];

$accessor = SafeAccess::fromArray($data);

// Acesso por índice
$accessor->get('users.0.name');          // "Ana"
$accessor->get('users.2.role');          // "user"

// Wildcard — obter todos os valores correspondentes
$accessor->get('users.*.name');          // ["Ana", "Bob", "Carol"]
$accessor->get('users.*.role');          // ["admin", "user", "user"]

Modificações imutáveis

$accessor = SafeAccess::fromJson('{"name": "Ana", "age": 30}');

// set() retorna uma NOVA instância
$modified = $accessor->set('email', 'ana@example.com');
$modified->get('email');                 // "ana@example.com"
$accessor->get('email');                 // null (original inalterado)

// remove() também retorna uma nova instância
$cleaned = $accessor->remove('age');
$cleaned->has('age');                    // false
$accessor->has('age');                   // true (original inalterado)

Auto-detecção de formato

$array = SafeAccess::detect(['key' => 'value']);    // ArrayAccessor
$json  = SafeAccess::detect('{"key": "value"}');    // JsonAccessor
$obj   = SafeAccess::detect((object)['a' => 1]);    // ObjectAccessor

Transformação cross-format

$accessor = SafeAccess::fromJson('{"name": "Ana", "age": 30}');

$accessor->toArray();    // ['name' => 'Ana', 'age' => 30]
$accessor->toObject();   // stdClass { name: "Ana", age: 30 }
$accessor->toXml();      // "<root><name>Ana</name><age>30</age></root>"
$accessor->toJson();     // '{"name":"Ana","age":30}'
$accessor->toYaml();     // "name: Ana\nage: 30\n"
$accessor->toToml();     // 'name = "Ana"\nage = 30\n'

---

Sistema de Plugins

YAML e TOML funcionam sem configuração. O Sistema de Plugins permite registrar parsers e serializers customizados para formatos adicionais.

Consulte a página do Sistema de Plugins para documentação completa, plugins embutidos, exemplos customizados e utilitários de teste.