README

MGTOON é uma biblioteca leve e minimalista escrita em PHP para trabalhar com arquivos no formato TOON (Text-Oriented Object Notation), um formato textual simples e humano para armazenamento estruturado de dados tabulares.

Ela foi projetada para oferecer CRUD completo, validação, serialização determinística e zero dependências, sendo ideal para CLIs, ferramentas internas, projetos embarcados, configurações e pequenos bancos de dados em texto puro.

✨ Características

Formato de dados simples, legível e versionável
CRUD completo (create, read, update, delete)
Definição explícita de chave primária
Validação estrutural e semântica do TOON
Serialização consistente (toString)
Suporte a carregamento e salvamento em arquivos
Zero dependências externas
Compatível com PHP 8.4 ou superior
Ideal para substituir CSV, INI ou JSON simples

📄 Formato TOON

Exemplo de um arquivo TOON:

user[id|name|email]
1|Pedro|pedro@email.com
2|Ana|ana@email.com

Estrutura

tipo[campo1|campo2|campo3]
valor1|valor2|valor3
valor1|valor2|valor3

A primeira linha define o tipo e os campos
As linhas seguintes são os registros
Um campo é definido como chave primária

📦 Instalação

Via Composer (recomendado)

composer require mugomes/mgtoon

Manual

Copie o arquivo MGTOON.php para o seu projeto e faça a inclusão manual.

🚀 Uso básico

Criar uma estrutura TOON

<?php

use MGTOON\MGTOON;

$toon = new MGTOON();

$toon->create('user', ['id', 'name', 'email'], 'id');

$toon->add([
    'id' => 1,
    'name' => 'Pedro',
    'email' => 'pedro@email.com'
]);

$toon->add([
    'id' => 2,
    'name' => 'Ana',
    'email' => 'ana@email.com'
]);

echo $toon->toString();

📂 Trabalhando com arquivos

Carregar arquivo

$toon = new MGTOON();
$toon->loadFile('users.toon', 'id');

Salvar em arquivo

$toon->saveFile('users.toon');

📖 Leitura de dados

Ler todos os registros

$records = $toon->read();

Ler por chave primária

$user = $toon->read('1');

✏️ Atualização

$toon->update('1', [
    'email' => 'novo@email.com'
]);

Apenas campos definidos no cabeçalho são atualizados
Campos inexistentes são ignorados

❌ Exclusão

$toon->delete('2');

🧪 Validação

É possível validar um conteúdo TOON sem carregá-lo:

$result = $toon->validate($text);

if ($result['valid']) {
    echo 'TOON válido';
} else {
    echo $result['error'];
}

O que é validado?

Estrutura do cabeçalho
Quantidade de colunas
Existência da chave primária
Duplicidade de valores da chave primária

🔐 Chave primária

Definida no momento da criação ou carregamento
Obrigatória em novos registros
Não pode conter valores duplicados

$toon->create('product', ['sku', 'name', 'price'], 'sku');

🧠 Casos de uso ideais

Pequenos bancos de dados locais
Ferramentas CLI
Configurações versionáveis
Dados temporários ou embarcados
Alternativa simples a CSV/JSON

👤 Autor

Murilo Gomes Julio

🔗 https://mugomes.github.io

📺 https://youtube.com/@mugomesoficial

🤝 Support

GitHub Sponsors: https://github.com/sponsors/mugomes
Apoie o projeto: https://mugomes.github.io/apoie.html

📜 License

Licensed under the MIT.

All contributions to the MiTemplate are subject to this license.

mugomes / mgtoon

Maintainers

Details