PHPackages                             lugotardo/forgeexel - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [PDF & Document Generation](/categories/documents)
4. /
5. lugotardo/forgeexel

ActiveLibrary[PDF & Document Generation](/categories/documents)

lugotardo/forgeexel
===================

Biblioteca PHP moderna e intuitiva para manipulação de arquivos Excel (XLSX) e CSV com suporte a formatação, fórmulas e múltiplas abas

v1.0.0(6mo ago)013MITPHPPHP >=7.4

Since Nov 6Pushed 6mo agoCompare

[ Source](https://github.com/lugotardo/ForgeExcel)[ Packagist](https://packagist.org/packages/lugotardo/forgeexel)[ Docs](https://github.com/lugotardo/ForgeExcel)[ RSS](/packages/lugotardo-forgeexel/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

📊 ForgeExcel
============

[](#-forgeexcel)

**A maneira mais fácil de trabalhar com arquivos Excel em PHP!**

ForgeExcel é uma biblioteca PHP que simplifica a leitura e escrita de arquivos Excel (XLSX, CSV, ODS), mas com uma interface muito mais simples e intuitiva.

🚀 Instalação
------------

[](#-instalação)

```
composer require lugotardo/forgeexel
```

✨ Características
-----------------

[](#-características)

- ✅ **Super Simples**: API limpa e fácil de usar
- 📖 **Leitura Rápida**: Lê arquivos Excel em segundos
- ✏️ **Escrita Fácil**: Cria arquivos Excel com poucas linhas
- 📑 **Múltiplas Abas**: Suporte para arquivos com várias abas
- 🔄 **Arrays Associativos**: Conversão automática de dados
- 💾 **Memória Eficiente**: Processa arquivos grandes em lotes (chunks)
- 📊 **Múltiplos Formatos**: XLSX, CSV, ODS
- 🇧🇷 **Documentação em Português**: Comentários explicativos em português
- 🎨 **Formatação Profissional**: Negrito, cores, fontes, alinhamento e bordas
- 📐 **Fórmulas do Excel**: Crie planilhas com cálculos automáticos
- 🎯 **Tabelas Estilizadas**: 5 temas prontos para usar

📚 Uso Básico
------------

[](#-uso-básico)

### Criar um arquivo Excel simples

[](#criar-um-arquivo-excel-simples)

```
use Lugotardo\Forgeexel\ForgeExcel;

$dados = [
    ['Nome', 'Email', 'Idade'],
    ['João Silva', 'joao@email.com', 25],
    ['Maria Santos', 'maria@email.com', 30],
];

ForgeExcel::write('pessoas.xlsx', $dados);
```

### Ler um arquivo Excel

[](#ler-um-arquivo-excel)

```
// Leitura simples (array numérico)
$dados = ForgeExcel::read('pessoas.xlsx');

// Leitura com headers (array associativo)
$dados = ForgeExcel::read('pessoas.xlsx', true);

foreach ($dados as $pessoa) {
    echo $pessoa['Nome'] . ' - ' . $pessoa['Email'] . "\n";
}
```

🎯 Exemplos Práticos
-------------------

[](#-exemplos-práticos)

### Exportar dados do banco para Excel

[](#exportar-dados-do-banco-para-excel)

```
// Simula dados do banco
$usuarios = $pdo->query("SELECT nome, email, idade FROM usuarios")->fetchAll(PDO::FETCH_ASSOC);

// Converte e salva em Excel (headers automáticos!)
$dadosExcel = ForgeExcel::arrayToExcel($usuarios);
ForgeExcel::write('usuarios.xlsx', $dadosExcel);
```

### Criar Excel com múltiplas abas

[](#criar-excel-com-múltiplas-abas)

```
$relatorio = [
    'Clientes' => [
        ['ID', 'Nome', 'Email'],
        [1, 'João', 'joao@email.com'],
        [2, 'Maria', 'maria@email.com'],
    ],
    'Produtos' => [
        ['Código', 'Produto', 'Preço'],
        ['A001', 'Notebook', 3500.00],
        ['A002', 'Mouse', 50.00],
    ],
    'Vendas' => [
        ['Data', 'Cliente', 'Valor'],
        ['2024-01-15', 'João', 3500.00],
        ['2024-01-16', 'Maria', 50.00],
    ]
];

ForgeExcel::writeWithSheets('relatorio.xlsx', $relatorio);
```

### Processar arquivos grandes (sem estourar memória)

[](#processar-arquivos-grandes-sem-estourar-memória)

```
// Processa arquivo enorme em lotes de 100 linhas
ForgeExcel::readInChunks('arquivo_gigante.xlsx', 100, function($lote) {
    foreach ($lote as $linha) {
        // Processa cada linha
        // Salva no banco, envia email, etc
        processarLinha($linha);
    }
});
```

### Ler apenas a primeira aba

[](#ler-apenas-a-primeira-aba)

```
// Mais rápido quando você só precisa da primeira aba
$dados = ForgeExcel::readFirstSheet('arquivo.xlsx', true);
```

### Ler todas as abas separadamente

[](#ler-todas-as-abas-separadamente)

```
$todasAbas = ForgeExcel::readAllSheets('arquivo.xlsx', true);

foreach ($todasAbas as $nomeAba => $dados) {
    echo "Aba: {$nomeAba} tem " . count($dados) . " registros\n";

    foreach ($dados as $linha) {
        // Processa cada linha de cada aba
    }
}
```

### Criar arquivo CSV

[](#criar-arquivo-csv)

```
$dados = [
    ['Produto', 'Quantidade', 'Preço'],
    ['Caneta', 100, 2.50],
    ['Caderno', 50, 15.00],
];

ForgeExcel::write('estoque.csv', $dados, 'csv');
```

### Contar linhas de um arquivo

[](#contar-linhas-de-um-arquivo)

```
$total = ForgeExcel::countRows('arquivo.xlsx');
$totalSemHeader = ForgeExcel::countRows('arquivo.xlsx', false);

echo "Total de linhas: {$total}\n";
```

📖 Documentação Completa dos Métodos
-----------------------------------

[](#-documentação-completa-dos-métodos)

### `read(string $filePath, bool $firstRowAsHeader = false): array`

[](#readstring-filepath-bool-firstrowasheader--false-array)

Lê um arquivo Excel e retorna todos os dados em array.

**Parâmetros:**

- `$filePath`: Caminho completo do arquivo
- `$firstRowAsHeader`: Se TRUE, usa primeira linha como chave do array (array associativo)

**Retorna:** Array com os dados da planilha

```
// Array numérico
$dados = ForgeExcel::read('arquivo.xlsx');
// [['João', 'joao@email.com'], ['Maria', 'maria@email.com']]

// Array associativo
$dados = ForgeExcel::read('arquivo.xlsx', true);
// [['Nome' => 'João', 'Email' => 'joao@email.com'], ['Nome' => 'Maria', 'Email' => 'maria@email.com']]
```

---

### `write(string $filePath, array $data, string $type = 'xlsx'): bool`

[](#writestring-filepath-array-data-string-type--xlsx-bool)

Escreve dados em um arquivo Excel.

**Parâmetros:**

- `$filePath`: Caminho onde o arquivo será salvo
- `$data`: Array de dados (cada item é uma linha)
- `$type`: Tipo do arquivo ('xlsx', 'csv' ou 'ods')

**Retorna:** TRUE se salvou com sucesso

```
$dados = [
    ['Nome', 'Email'],
    ['João', 'joao@email.com']
];

ForgeExcel::write('arquivo.xlsx', $dados);        // Excel
ForgeExcel::write('arquivo.csv', $dados, 'csv');  // CSV
ForgeExcel::write('arquivo.ods', $dados, 'ods');  // ODS
```

---

### `writeWithSheets(string $filePath, array $sheets): bool`

[](#writewithsheetsstring-filepath-array-sheets-bool)

Escreve dados em múltiplas abas de um arquivo Excel.

**Parâmetros:**

- `$filePath`: Caminho onde o arquivo será salvo
- `$sheets`: Array associativo \[nome\_aba => dados\]

**Retorna:** TRUE se salvou com sucesso

```
$abas = [
    'Aba1' => [['Coluna1', 'Coluna2'], ['Valor1', 'Valor2']],
    'Aba2' => [['Coluna1', 'Coluna2'], ['Valor1', 'Valor2']]
];

ForgeExcel::writeWithSheets('arquivo.xlsx', $abas);
```

---

### `arrayToExcel(array $associativeArray, bool $includeHeader = true): array`

[](#arraytoexcelarray-associativearray-bool-includeheader--true-array)

Converte um array associativo em array formatado para Excel.

**Parâmetros:**

- `$associativeArray`: Array de arrays associativos
- `$includeHeader`: Se TRUE, adiciona linha de cabeçalho automaticamente

**Retorna:** Array formatado para escrita no Excel

```
$usuarios = [
    ['nome' => 'João', 'email' => 'joao@email.com'],
    ['nome' => 'Maria', 'email' => 'maria@email.com']
];

$dadosExcel = ForgeExcel::arrayToExcel($usuarios);
// [['nome', 'email'], ['João', 'joao@email.com'], ['Maria', 'maria@email.com']]

ForgeExcel::write('usuarios.xlsx', $dadosExcel);
```

---

### `readFirstSheet(string $filePath, bool $firstRowAsHeader = false): array`

[](#readfirstsheetstring-filepath-bool-firstrowasheader--false-array)

Lê apenas a primeira aba de um arquivo Excel (mais rápido).

**Parâmetros:**

- `$filePath`: Caminho do arquivo
- `$firstRowAsHeader`: Se TRUE, usa primeira linha como chave

**Retorna:** Array com dados da primeira aba

```
$dados = ForgeExcel::readFirstSheet('arquivo.xlsx', true);
```

---

### `readAllSheets(string $filePath, bool $firstRowAsHeader = false): array`

[](#readallsheetsstring-filepath-bool-firstrowasheader--false-array)

Lê todas as abas de um arquivo Excel separadamente.

**Parâmetros:**

- `$filePath`: Caminho do arquivo
- `$firstRowAsHeader`: Se TRUE, usa primeira linha como chave

**Retorna:** Array associativo \[nome\_aba => dados\]

```
$todasAbas = ForgeExcel::readAllSheets('arquivo.xlsx', true);

foreach ($todasAbas as $nomeAba => $dados) {
    echo "Processando aba: {$nomeAba}\n";
}
```

---

### `countRows(string $filePath, bool $countHeader = true): int`

[](#countrowsstring-filepath-bool-countheader--true-int)

Conta quantas linhas tem um arquivo Excel.

**Parâmetros:**

- `$filePath`: Caminho do arquivo
- `$countHeader`: Se FALSE, não conta a primeira linha

**Retorna:** Número total de linhas

```
$total = ForgeExcel::countRows('arquivo.xlsx');
echo "Total de linhas: {$total}";
```

---

### `readInChunks(string $filePath, int $chunkSize, callable $callback, bool $firstRowAsHeader = false): void`

[](#readinchunksstring-filepath-int-chunksize-callable-callback-bool-firstrowasheader--false-void)

Processa arquivo Excel em lotes (ideal para arquivos muito grandes).

**Parâmetros:**

- `$filePath`: Caminho do arquivo
- `$chunkSize`: Quantas linhas processar por vez
- `$callback`: Função que recebe cada lote de dados
- `$firstRowAsHeader`: Se TRUE, usa primeira linha como chave

```
ForgeExcel::readInChunks('arquivo_grande.xlsx', 100, function($lote) {
    // Processa 100 linhas por vez
    foreach ($lote as $linha) {
        processarDados($linha);
    }
});
```

🧪 Testando
----------

[](#-testando)

Execute o arquivo de testes incluído:

```
php test.php
```

Este comando vai criar vários arquivos Excel de exemplo demonstrando todos os recursos da biblioteca!

🎨 Exemplos de Casos de Uso
--------------------------

[](#-exemplos-de-casos-de-uso)

### 1. Importar planilha de clientes

[](#1-importar-planilha-de-clientes)

```
$clientes = ForgeExcel::read('clientes.xlsx', true);

foreach ($clientes as $cliente) {
    $pdo->prepare("INSERT INTO clientes (nome, email, telefone) VALUES (?, ?, ?)")
        ->execute([$cliente['Nome'], $cliente['Email'], $cliente['Telefone']]);
}
```

### 2. Exportar relatório mensal

[](#2-exportar-relatório-mensal)

```
$vendas = $pdo->query("SELECT * FROM vendas WHERE MONTH(data) = 1")->fetchAll(PDO::FETCH_ASSOC);
$dados = ForgeExcel::arrayToExcel($vendas);
ForgeExcel::write('relatorio_janeiro.xlsx', $dados);
```

### 3. Processar arquivo enorme (milhões de linhas)

[](#3-processar-arquivo-enorme-milhões-de-linhas)

```
$total = 0;
$soma = 0;

ForgeExcel::readInChunks('vendas_2023.xlsx', 1000, function($lote) use (&$total, &$soma) {
    foreach ($lote as $venda) {
        $total++;
        $soma += $venda['Valor'];
    }
}, true);

echo "Total de vendas: {$total}\n";
echo "Valor total: R$ {$soma}\n";
```

### 4. Criar dashboard em Excel

[](#4-criar-dashboard-em-excel)

```
$dashboard = [
    'Resumo Geral' => [
        ['Métrica', 'Valor'],
        ['Total de Clientes', 1523],
        ['Total de Vendas', 'R$ 458.230,00'],
        ['Ticket Médio', 'R$ 301,00']
    ],
    'Top 10 Clientes' => ForgeExcel::arrayToExcel($topClientes),
    'Vendas por Mês' => ForgeExcel::arrayToExcel($vendasMes)
];

ForgeExcel::writeWithSheets('dashboard.xlsx', $dashboard);
```

🎨 Paleta de Cores
-----------------

[](#-paleta-de-cores)

Use cores predefinidas:

```
$cores = ForgeExcel::colors();
// black, white, red, green, blue, yellow, orange, purple, pink,
// gray, light_gray, dark_gray, cyan, magenta, lime, navy, teal,
// olive, maroon, aqua

$estilo = ForgeExcel::createStyle([
    'color' => $cores['white'],
    'background' => $cores['blue']
]);
```

📊 Fórmulas Suportadas
---------------------

[](#-fórmulas-suportadas)

- **Matemáticas**: SUM, AVERAGE, COUNT, MAX, MIN, ROUND, ABS
- **Lógicas**: IF, AND, OR, NOT
- **Condicionais**: COUNTIF, SUMIF, AVERAGEIF
- **Texto**: CONCATENATE, UPPER, LOWER, LEN, LEFT, RIGHT
- **Data**: TODAY, NOW, DATE, YEAR, MONTH, DAY
- E muito mais!

🤝 Contribuindo
--------------

[](#-contribuindo)

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou pull requests.

📝 Licença
---------

[](#-licença)

Este projeto está sob a licença MIT.

👨‍💻 Autor
---------

[](#‍-autor)

**Luan Gotardo**

- Email:

⚡ Performance
-------------

[](#-performance)

- ✅ Lê arquivos de 100MB+ sem problemas
- ✅ Usa stream reading (não carrega tudo na memória)
- ✅ Processa milhões de linhas com `readInChunks()`
- ✅ Escrita otimizada e rápida

🐛 Problemas Conhecidos
----------------------

[](#-problemas-conhecidos)

- O box/spout está marcado como "abandoned", mas ainda funciona perfeitamente
- Para arquivos MUITO grandes (1GB+), use sempre `readInChunks()`

🆕 Novos Recursos
----------------

[](#-novos-recursos)

### Formatação e Estilos

[](#formatação-e-estilos)

```
// Criar estilo personalizado
$estilo = ForgeExcel::createStyle([
    'bold' => true,
    'fontSize' => 14,
    'color' => 'FFFFFF',
    'background' => '4472C4',
    'align' => 'center'
]);

// Escrever com formatação
$estilos = [
    0 => ['bold' => true, 'color' => 'FFFFFF', 'background' => '4472C4']
];

ForgeExcel::writeWithStyle('arquivo.xlsx', $dados, $estilos);
```

### Fórmulas do Excel

[](#fórmulas-do-excel)

```
$dados = [
    ['Produto', 'Quantidade', 'Preço', 'Total'],
    ['Notebook', 2, 3500, '=B2*C2'],
    ['Mouse', 5, 50, '=B3*C3'],
    ['TOTAL', '', '', '=SUM(D2:D3)']
];

ForgeExcel::writeWithFormulas('vendas.xlsx', $dados);
```

### Tabelas com Temas

[](#tabelas-com-temas)

```
// 5 temas disponíveis: blue, green, red, orange, purple
ForgeExcel::writeTable('funcionarios.xlsx', $dados, 'blue');
```

### Múltiplas Abas com Estilos

[](#múltiplas-abas-com-estilos)

```
$abas = [
    'Dashboard' => [
        'data' => $dados,
        'headerStyle' => ['bold' => true, 'color' => 'FFFFFF', 'background' => '4472C4']
    ],
    'Detalhes' => [
        'data' => $detalhes,
        'headerStyle' => ['bold' => true, 'color' => 'FFFFFF', 'background' => '70AD47']
    ]
];

ForgeExcel::writeStyledSheets('relatorio.xlsx', $abas);
```

📚 Documentação Completa
-----------------------

[](#-documentação-completa)

Para documentação detalhada, consulte:

- **[Guia Completo](docs/GUIA_COMPLETO.md)** - Documentação completa com todos os recursos
- **[Guia de Formatação](docs/FORMATACAO.md)** - Tudo sobre estilos, cores e formatação
- **[Guia de Fórmulas](docs/FORMULAS.md)** - Como usar fórmulas do Excel

🧪 Testando
----------

[](#-testando-1)

Execute os arquivos de teste incluídos:

```
# Testes básicos
php test.php

# Testes avançados (formatação e fórmulas)
php test_advanced.php
```

🎯 Roadmap
---------

[](#-roadmap)

- Suporte para formatação de células (negrito, cores, etc) ✅
- Suporte para fórmulas ✅
- Tabelas estilizadas com temas ✅
- Suporte para imagens
- Suporte para gráficos nativos
- CLI para conversões rápidas

---

**Feito com ❤️ para facilitar sua vida trabalhando com Excel em PHP!**

###  Health Score

30

—

LowBetter than 64% of packages

Maintenance67

Regular maintenance activity

Popularity5

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity35

Early-stage or recently created project

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

193d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8f61e6e35b2dec05aa4bb5b277c3abf6492f49c3991b7ba59c180b7658b9a189?d=identicon)[lugotardo](/maintainers/lugotardo)

---

Top Contributors

[![lugotardo](https://avatars.githubusercontent.com/u/212004267?v=4)](https://github.com/lugotardo "lugotardo (4 commits)")

---

Tags

phpexportexcelxlsxcsvspreadsheetimportforgeexcel

### Embed Badge

![Health badge](/badges/lugotardo-forgeexel/health.svg)

```
[![Health](https://phpackages.com/badges/lugotardo-forgeexel/health.svg)](https://phpackages.com/packages/lugotardo-forgeexel)
```

###  Alternatives

[openspout/openspout

PHP Library to read and write spreadsheet files (CSV, XLSX and ODS), in a fast and scalable way

1.2k57.6M131](/packages/openspout-openspout)[avadim/fast-excel-writer

Lightweight and very fast XLSX Excel Spreadsheet Writer in PHP

2951.2M7](/packages/avadim-fast-excel-writer)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)