PHPackages                             ananiaslitz/hyperf-avro - 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. [API Development](/categories/api)
4. /
5. ananiaslitz/hyperf-avro

ActiveLibrary[API Development](/categories/api)

ananiaslitz/hyperf-avro
=======================

Avro integration for Hyperf framework with AOP support

1.0.0(4mo ago)00MITPHPPHP >=8.1CI passing

Since Feb 23Pushed 4mo agoCompare

[ Source](https://github.com/Ananiaslitz/hyperf-avro)[ Packagist](https://packagist.org/packages/ananiaslitz/hyperf-avro)[ RSS](/packages/ananiaslitz-hyperf-avro/feed)WikiDiscussions main Synced today

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

hyperf-avro
===========

[](#hyperf-avro)

[![License: MIT](https://camo.githubusercontent.com/08cef40a9105b6526ca22088bc514fbfdbc9aac1ddbf8d4e6c750e3a88a44dca/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c6963656e73652d4d49542d626c75652e737667)](LICENSE)

Integração do [Apache Avro](https://avro.apache.org/) com o framework [Hyperf](https://hyperf.io/) focada em **Kafka** e **Confluent Schema Registry**.

Recursos
--------

[](#recursos)

- **Confluent Wire Format**: Suporte nativo ao formato `0x00` (magic byte) + 4 bytes (Schema ID).
- **Schema Registry**: Cliente Guzzle para integração com Confluent Schema Registry.
- **Cache de Performance**: Cache em memória para Schema IDs (permanente) e Subjects (com TTL configurável).
- **AOP Support**: Atributos `#[AvroSerialize]` e `#[AvroDeserialize]` para facilitar a integração.
- **Fail-fast**: Erros de validação e comunicação encapsulados em `AvroSerializationException`.

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

[](#instalação)

```
composer require ananiaslitz/hyperf-avro
```

Publique o arquivo de configuração:

```
php bin/hyperf.php vendor:publish ananiaslitz/hyperf-avro
```

Configuração
------------

[](#configuração)

O arquivo `config/autoload/avro.php` permite configurar o path local e a conexão com o Registry:

```
return [
    'schema_path' => BASE_PATH . '/storage/avro',
    'registry' => [
        'base_url' => env('SCHEMA_REGISTRY_URL', 'http://localhost:8081'),
        'auth' => [
            'key'    => env('SCHEMA_REGISTRY_KEY'),
            'secret' => env('SCHEMA_REGISTRY_SECRET'),
            'token'  => env('SCHEMA_REGISTRY_TOKEN'),
        ],
        'subject_cache_ttl' => (int) env('SCHEMA_REGISTRY_SUBJECT_CACHE_TTL', 300),
        'ssl_verify' => (bool) env('SCHEMA_REGISTRY_SSL_VERIFY', true),
    ],
];
```

Uso com Kafka
-------------

[](#uso-com-kafka)

### 1. Produzir Mensagem (Producer)

[](#1-produzir-mensagem-producer)

Use o `KafkaAvroSerializer` para converter seus dados no formato compatível com o ecossistema Confluent:

```
use Ananiaslitz\HyperfAvro\KafkaAvroSerializer;

class UserProducer
{
    public function __construct(private KafkaAvroSerializer $avro) {}

    public function send(array $userData)
    {
        // encode() registra/busca o schema, resolve o ID e retorna o binário (wire format)
        $payload = $this->avro->encode($userData, 'user-events-value');

        // Agora envie $payload via hyperf/kafka ou similar
    }
}
```

### 2. Consumir Mensagem (Consumer)

[](#2-consumir-mensagem-consumer)

O deserializer identifica automaticamente o schema pelo ID embutido nos primeiros bytes da mensagem:

```
use Ananiaslitz\HyperfAvro\KafkaAvroSerializer;

class UserConsumer
{
    public function __construct(private KafkaAvroSerializer $avro) {}

    public function onMessage(string $value)
    {
        // decode() lê o ID, busca o schema no registry (cached) e deserializa os dados
        $data = $this->avro->decode($value);

        // $data['username']...
    }
}
```

### 3. Usando Atributos (AOP)

[](#3-usando-atributos-aop)

Para consumidores que recebem a string binária como primeiro argumento:

```
use Ananiaslitz\HyperfAvro\Annotation\AvroDeserialize;

class EventConsumer
{
    #[AvroDeserialize(schema: 'user-events-value')]
    public function handle(string $payload): void
    {
        // $payload já chega como array associativo
    }
}
```

Exceções
--------

[](#exceções)

Trate erros de schema ou registry de forma granular:

```
use Ananiaslitz\HyperfAvro\Exception\AvroSerializationException;

try {
    $payload = $avro->encode($data, 'subject');
} catch (AvroSerializationException $e) {
    // Erro no registry, schema incompatível ou payload inválido
}
```

Licença
-------

[](#licença)

MIT

###  Health Score

33

—

LowBetter than 72% of packages

Maintenance76

Regular maintenance activity

Popularity0

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

 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

130d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/963a9f4c77e080eaafe63352d0ec2e1dc101cb54b734c0a144223893793000b5?d=identicon)[Ananiaslitz](/maintainers/Ananiaslitz)

---

Top Contributors

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

---

Tags

phpaopserializationavrohyperf

###  Code Quality

TestsPHPUnit

Static AnalysisPHPStan

Code StylePHP CS Fixer

Type Coverage Yes

### Embed Badge

![Health badge](/badges/ananiaslitz-hyperf-avro/health.svg)

```
[![Health](https://phpackages.com/badges/ananiaslitz-hyperf-avro/health.svg)](https://phpackages.com/packages/ananiaslitz-hyperf-avro)
```

###  Alternatives

[laravel/framework

The Laravel Framework.

34.8k543.8M20.1k](/packages/laravel-framework)[sylius/sylius

E-Commerce platform for PHP, based on Symfony framework.

8.5k5.9M736](/packages/sylius-sylius)[drupal/core

Drupal is an open source content management platform powering millions of websites and applications.

21866.0M1.7k](/packages/drupal-core)[tencentcloud/tencentcloud-sdk-php

TencentCloudApi php sdk

3741.3M47](/packages/tencentcloud-tencentcloud-sdk-php)[drupal/core-recommended

Locked core dependencies; require this project INSTEAD OF drupal/core.

6942.5M421](/packages/drupal-core-recommended)[civicrm/civicrm-core

Open source constituent relationship management for non-profits, NGOs and advocacy organizations.

751291.4k43](/packages/civicrm-civicrm-core)

PHPackages © 2026

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