A comprehensive PHP library providing annotations/attributes for the AsyncAPI 3.0.0 specification. This library enables you to define AsyncAPI specifications using modern PHP 8.3+ attributes.
- ✅ Complete AsyncAPI 3.0.0 Support - Full implementation of all AsyncAPI 3.0.0 objects and properties
- ✅ Modern PHP 8.3+ - Uses PHP 8.3+ attributes with strict typing
- ✅ Protocol Bindings - Support for all protocol-specific bindings (Kafka, MQTT, AMQP, HTTP, WebSockets, etc.)
- ✅ Security Schemes - Complete security scheme support (OAuth2, API Keys, HTTP Auth, etc.)
- ✅ Reusable Components - Full support for reusable components via the Components object
- ✅ Specification Extensions - Support for custom x-* fields
- ✅ PSR Compliant - Follows PSR-12 coding standards and PSR-4 autoloading
- ✅ Well Tested - Comprehensive PHPUnit test suite
- ✅ Portable - Designed to be integrated into Symfony bundles, Laravel packages, and other frameworks
Install via Composer:
composer require drmmr763/php-asyncapi-annotations
<?php
use AsyncApi\Attributes\AsyncApi;
use AsyncApi\Attributes\Info;
use AsyncApi\Attributes\Contact;
use AsyncApi\Attributes\License;
use AsyncApi\Attributes\Server;
use AsyncApi\Attributes\Channel;
use AsyncApi\Attributes\Message;
use AsyncApi\Attributes\Schema;
#[AsyncApi(
asyncapi: '3.0.0',
info: new Info(
title: 'User Service API',
version: '1.0.0',
description: 'API for managing user events',
contact: new Contact(
name: 'API Support',
email: 'support@example.com',
url: 'https://example.com/support'
),
license: new License(
name: 'MIT',
url: 'https://opensource.org/licenses/MIT'
)
),
defaultContentType: 'application/json'
)]
class UserServiceApi
{
// Your API implementation
}
use AsyncApi\Attributes\Server;
use AsyncApi\Attributes\ServerVariable;
use AsyncApi\Attributes\Servers;
#[Server(
host: '{environment}.example.com:9092',
protocol: 'kafka',
protocolVersion: '2.8.0',
description: 'Kafka broker for user events',
variables: [
'environment' => new ServerVariable(
enum: ['dev', 'staging', 'prod'],
default: 'dev',
description: 'Environment name'
)
]
)]
class KafkaServer
{
}
use AsyncApi\Attributes\Message;
use AsyncApi\Attributes\Schema;
#[Message(
name: 'UserCreated',
title: 'User Created Event',
summary: 'Event emitted when a new user is created',
contentType: 'application/json',
payload: new Schema(
type: 'object',
required: ['id', 'email', 'createdAt'],
properties: [
'id' => new Schema(
type: 'string',
description: 'Unique user identifier',
format: 'uuid'
),
'email' => new Schema(
type: 'string',
description: 'User email address',
format: 'email'
),
'name' => new Schema(
type: 'string',
description: 'User full name'
),
'createdAt' => new Schema(
type: 'string',
description: 'Timestamp when user was created',
format: 'date-time'
)
]
)
)]
class UserCreatedMessage
{
}
Defining Channels and Operations
use AsyncApi\Attributes\Channel;
use AsyncApi\Attributes\Operation;
use AsyncApi\Attributes\Reference;
#[Channel(
address: 'user.events.{eventType}',
description: 'Channel for user-related events',
parameters: new Parameters(
parameters: [
'eventType' => new Parameter(
description: 'Type of user event',
enum: ['created', 'updated', 'deleted']
)
]
)
)]
class UserEventsChannel
{
}
#[Operation(
action: 'send',
channel: new Reference(ref: '#/channels/userEvents'),
summary: 'Send user events',
messages: [
new Reference(ref: '#/components/messages/UserCreated')
]
)]
class SendUserEvent
{
}
use AsyncApi\Attributes\SecurityScheme;
use AsyncApi\Attributes\OAuthFlows;
use AsyncApi\Attributes\OAuthFlow;
#[SecurityScheme(
type: 'oauth2',
description: 'OAuth2 authentication',
flows: new OAuthFlows(
authorizationCode: new OAuthFlow(
authorizationUrl: 'https://example.com/oauth/authorize',
tokenUrl: 'https://example.com/oauth/token',
scopes: [
'read:users' => 'Read user information',
'write:users' => 'Create and update users'
]
)
)
)]
class OAuth2Security
{
}
Using Components for Reusability
use AsyncApi\Attributes\Components;
#[Components(
schemas: [
'User' => new Schema(
type: 'object',
properties: [
'id' => new Schema(type: 'string', format: 'uuid'),
'email' => new Schema(type: 'string', format: 'email'),
'name' => new Schema(type: 'string')
]
)
],
messages: [
'UserCreated' => new Message(
payload: new Reference(ref: '#/components/schemas/User')
)
]
)]
class ApiComponents
{
}
- AsyncApi - Root document object
- Info - API metadata
- Contact - Contact information
- License - License information
- Server - Server/broker definition
- ServerVariable - Server URL template variable
- Servers - Collection of servers
- Channel - Communication channel
- Channels - Collection of channels
- Operation - Send/receive operation
- Operations - Collection of operations
- OperationTrait - Reusable operation properties
- OperationReply - Request/reply pattern response
- OperationReplyAddress - Reply address specification
- Message - Message definition
- Messages - Collection of messages
- MessageTrait - Reusable message properties
- MessageExample - Message example
- Parameter - Channel parameter
- Parameters - Collection of parameters
- Components - Reusable components
- Schema - JSON Schema Draft 07 superset
- MultiFormatSchema - Multi-format schema support (Avro, etc.)
- Tag - Metadata tag
- ExternalDocumentation - External documentation reference
- Reference - Component reference ($ref)
- CorrelationId - Message correlation identifier
- ServerBindings - Protocol-specific server configuration
- ChannelBindings - Protocol-specific channel configuration
- OperationBindings - Protocol-specific operation configuration
- MessageBindings - Protocol-specific message configuration
- SecurityScheme - Security scheme definition
- OAuthFlows - OAuth flow configurations
- OAuthFlow - Individual OAuth flow
The library supports bindings for all AsyncAPI protocols:
- HTTP
- WebSockets
- Kafka
- AMQP 0-9-1
- AMQP 1.0
- MQTT
- MQTT 5
- NATS
- JMS
- SNS
- SQS
- STOMP
- Redis
- Solace
- Mercure
- IBM MQ
- Google Pub/Sub
- Pulsar
- Anypoint MQ
composer test
# Run all quality checks
composer quality
# Individual checks
composer phpstan # Static analysis
composer cs:check # Code style check
composer cs:fix # Fix code style
composer phpmd # Mess detector
Contributions are welcome! Please feel free to submit a Pull Request.
This library is licensed under the MIT License. See the LICENSE file for details.