PHPackages                             soarestheu/sqlstate-handler - 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. [Database & ORM](/categories/database)
4. /
5. soarestheu/sqlstate-handler

ActiveLibrary[Database & ORM](/categories/database)

soarestheu/sqlstate-handler
===========================

Pacote para tratamento de erros SQLSTATE no Laravel.

v1.0.0(1y ago)43MITPHPPHP >=7.3

Since Mar 12Pushed 1y ago1 watchersCompare

[ Source](https://github.com/soarestheu/sqlstate-handler)[ Packagist](https://packagist.org/packages/soarestheu/sqlstate-handler)[ RSS](/packages/soarestheu-sqlstate-handler/feed)WikiDiscussions main Synced 1mo ago

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

🚀 Laravel SQLSTATE Handler
==========================

[](#-laravel-sqlstate-handler)

[![Packagist](https://camo.githubusercontent.com/a5a7da81d458d60be73e97c837bde9cc50d689f01f00812220f8be842010d1ba/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736f61726573746865752f73716c73746174652d68616e646c6572)](https://camo.githubusercontent.com/a5a7da81d458d60be73e97c837bde9cc50d689f01f00812220f8be842010d1ba/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f736f61726573746865752f73716c73746174652d68616e646c6572)[![License](https://camo.githubusercontent.com/3e5dbd87e5e20cb9b0aa13f8d9ea91e7830ffc99d9a28ad8b42817a4d1a7150d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f736f61726573746865752f73716c73746174652d68616e646c6572)](https://camo.githubusercontent.com/3e5dbd87e5e20cb9b0aa13f8d9ea91e7830ffc99d9a28ad8b42817a4d1a7150d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f736f61726573746865752f73716c73746174652d68616e646c6572)[![Laravel](https://camo.githubusercontent.com/ac903b5b6c1e365d74eca2322c5c40b37f487b05783b6d8106c3ee9e603da674/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d37253230253743253230382532302537432532303925323025374325323031302d626c7565)](https://camo.githubusercontent.com/ac903b5b6c1e365d74eca2322c5c40b37f487b05783b6d8106c3ee9e603da674/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d37253230253743253230382532302537432532303925323025374325323031302d626c7565)

### **Pacote Laravel para tratamento de erros SQLSTATE de forma amigável**

[](#pacote-laravel-para-tratamento-de-erros-sqlstate-de-forma-amigável)

Este pacote permite capturar e tratar **códigos de erro SQLSTATE** no Laravel, fornecendo mensagens personalizadas e registrando logs automaticamente para debug.

📌 **Instalação**
----------------

[](#-instalação)

Você pode instalar o pacote via Composer:

```
composer require soarestheu/sqlstate-handler
```

📌 **Publicação da Configuração**
--------------------------------

[](#-publicação-da-configuração)

Após instalar o pacote, publique o arquivo de configuração para personalizar as mensagens SQLSTATE:

```
php artisan vendor:publish --tag=config
```

Isso criará um arquivo `config/sqlstate.php` no seu projeto, onde você pode personalizar as mensagens.

📌 **Como Usar no Laravel**
--------------------------

[](#-como-usar-no-laravel)

### 🔹 **Exemplo com Exception Personalizada**

[](#-exemplo-com-exception-personalizada)

```
use Illuminate\Database\QueryException;
use SqlstateHandler\HandlerQueryException;

class StateException extends \Exception
{
    use HandlerQueryException;
}
```

Agora, você pode capturar erros SQLSTATE automaticamente:

```
try {
    DB::table('user')->insert(['id' => 1, 'nome' => null]);
} catch (QueryException $e) {
    throw StateException::fromQueryException($e);
}
```

📌 Exemplo de Retorno JSON
-------------------------

[](#-exemplo-de-retorno-json)

Se ocorrer um erro SQLSTATE, como uma violação de chave única (`23000`), o Laravel retornará um JSON estruturado:

```
{
    "message": "Violação de integridade: dado já cadastrado ou relacionado.",
    "code": 500,
}
```

Esse retorno facilita a depuração e mantém um padrão de resposta em APIs Laravel.

### 🔹 **Logs Automáticos para Debug**

[](#-logs-automáticos-para-debug)

Sempre que um erro SQLSTATE for capturado, ele será registrado automaticamente no **log do Laravel** (`storage/logs/laravel.log`).

Exemplo de log gerado:

```
{
    "sqlstate": "23000",
    "mensagem": "Violação de integridade: dado já cadastrado ou relacionado.",
    "query": "INSERT INTO users (id, email) VALUES (?, ?)",
    "bindings": [1, "email@teste.com"],
    "arquivo": "/var/www/html/app/Http/Controllers/StateController.php",
    "linha": 22
}
```

Isso facilita o debug sem expor detalhes sensíveis para o usuário.

### 🔹 **Acessando via Container**

[](#-acessando-via-container)

O pacote também registra um singleton no Laravel, permitindo que você o acesse diretamente:

```
$sqlHandler = app('sqlstate.handler');
```

📌 **Personalização das Mensagens**
----------------------------------

[](#-personalização-das-mensagens)

Para modificar as mensagens de erro, edite o arquivo **`config/sqlstate.php`**:

```
return [
    'messages' => [
        '23000' => 'Este registro já existe no banco de dados.',
        '23503' => 'Erro de integridade: chave estrangeira inválida.',
        '42000' => 'Erro de sintaxe na query. Verifique seu SQL.',
    ]
];
```

📌 **Contribuindo**
------------------

[](#-contribuindo)

Contribuições são bem-vindas! Para melhorar o pacote:

1. **Clone o repositório**

    ```
    git clone https://github.com/username/sqlstate-handler.git
    ```
2. **Crie um branch para suas alterações**

    ```
    git checkout -b minha-melhoria
    ```
3. **Faça o commit e envie o PR**

    ```
    git commit -m "Melhoria na documentação"
    git push origin minha-melhoria
    ```

📌 **Licença**
-------------

[](#-licença)

Este pacote está sob a licença **MIT**.

###  Health Score

24

—

LowBetter than 32% of packages

Maintenance45

Moderate activity, may be stable

Popularity7

Limited adoption so far

Community4

Small or concentrated contributor base

Maturity32

Early-stage or recently created project

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

432d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/68f71b270f32f7edb8a32585b3bfba3618aa9c6313e011257e54b57c74a9f9f5?d=identicon)[soarestheu](/maintainers/soarestheu)

### Embed Badge

![Health badge](/badges/soarestheu-sqlstate-handler/health.svg)

```
[![Health](https://phpackages.com/badges/soarestheu-sqlstate-handler/health.svg)](https://phpackages.com/packages/soarestheu-sqlstate-handler)
```

###  Alternatives

[owen-it/laravel-auditing

Audit changes of your Eloquent models in Laravel

3.4k33.0M95](/packages/owen-it-laravel-auditing)[staudenmeir/eloquent-json-relations

Laravel Eloquent relationships with JSON keys

1.1k5.8M24](/packages/staudenmeir-eloquent-json-relations)[bavix/laravel-wallet

It's easy to work with a virtual wallet.

1.3k1.1M11](/packages/bavix-laravel-wallet)[dragon-code/migrate-db

Easy data transfer from one database to another

15717.4k](/packages/dragon-code-migrate-db)[gearbox-solutions/eloquent-filemaker

A package for getting FileMaker records as Eloquent models in Laravel

6454.8k2](/packages/gearbox-solutions-eloquent-filemaker)[cybercog/laravel-ownership

Laravel Ownership simplify management of Eloquent model's owner.

9126.6k3](/packages/cybercog-laravel-ownership)

PHPackages © 2026

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