README

A comprehensive PHP library for encoding and decoding CBOR (Concise Binary Object Representation) data according to RFC 8949.

Features

• ✅ Full support for all CBOR major types (0-7)
• ✅ Extensible tag system with built-in support for common tags
• ✅ Streaming decoder for efficient memory usage
• ✅ Type-safe API with modern PHP 8.0+ features
• ✅ Comprehensive support for indefinite-length objects
• ✅ Built-in normalization to PHP native types

Installation

composer require spomky-labs/cbor-php

Requirements:

• PHP 8.0 or higher
• ext-mbstring
• brick/math

Optional but recommended:

• ext-gmp or ext-bcmath for improved performance with large integers
• ext-bcmath for Big Float and Decimal Fraction support

This project follows semantic versioning strictly.

Quick Start

<?php

use CBOR\Decoder;
use CBOR\MapObject;
use CBOR\TextStringObject;
use CBOR\UnsignedIntegerObject;

// Encoding: Create a CBOR object
$map = MapObject::create()
    ->add(TextStringObject::create('name'), TextStringObject::create('John Doe'))
    ->add(TextStringObject::create('age'), UnsignedIntegerObject::create(30));

$encoded = (string) $map;

// Decoding: Parse CBOR data
$decoder = Decoder::create();
$decoded = $decoder->decode(StringStream::create($encoded));

// Normalize to native PHP types
$data = $decoded->normalize();
// ['name' => 'John Doe', 'age' => '30']

Documentation

???? Complete Documentation - Full API reference and guides

Quick Links

• Tags Reference - Complete guide to all 15+ supported CBOR tags
• Creating Custom Tags - Implement your own tags for domain-specific needs
• API Reference - Encoding and decoding API
• Examples - WebAuthn, COSE, IoT, and more

Major Types Overview

This library supports all CBOR major types defined in RFC 8949:

Common API:

• All objects have a static create() method for instantiation
• All objects can be converted to binary: (string) $object
• Many objects implement Normalizable to convert to native PHP types

Basic Usage Examples

For complete documentation with all examples, see the Documentation.

Working with Basic Types

use CBOR\UnsignedIntegerObject;
use CBOR\TextStringObject;
use CBOR\ListObject;
use CBOR\MapObject;

// Integers
$number = UnsignedIntegerObject::create(42);

// Strings
$text = TextStringObject::create('Hello World');

// Arrays
$list = ListObject::create([
    UnsignedIntegerObject::create(1),
    TextStringObject::create('two'),
]);

// Maps/Objects
$map = MapObject::create()
    ->add(TextStringObject::create('key'), TextStringObject::create('value'));

Working with Tags

???? For complete tags documentation, see Tags Reference

use CBOR\Tag\TimestampTag;
use CBOR\Tag\DecimalFractionTag;
use CBOR\UnsignedIntegerObject;

// Timestamps
$timestamp = TimestampTag::create(UnsignedIntegerObject::create(time()));
$dateTime = $timestamp->normalize(); // DateTimeImmutable

// Decimal fractions
$decimal = DecimalFractionTag::createFromFloat(3.14159);
echo $decimal->normalize(); // "3.14159"

Supported Tags:

• Date/Time (Tags 0, 1)
• Big Numbers (Tags 2, 3)
• Decimal/Binary Fractions (Tags 4, 5)
• Encoding hints (Tags 21, 22, 23)
• URIs and MIME (Tags 32, 36)
• And more...

Create your own: See Creating Custom Tags guide.

Complete Example

use CBOR\Decoder;
use CBOR\MapObject;
use CBOR\ListObject;
use CBOR\TextStringObject;
use CBOR\UnsignedIntegerObject;
use CBOR\StringStream;
use CBOR\Tag\TimestampTag;

// Build a complex nested structure
$data = MapObject::create()
    ->add(
        TextStringObject::create('user'),
        MapObject::create()
            ->add(TextStringObject::create('name'), TextStringObject::create('Alice'))
            ->add(TextStringObject::create('age'), UnsignedIntegerObject::create(30))
    )
    ->add(
        TextStringObject::create('scores'),
        ListObject::create([
            UnsignedIntegerObject::create(95),
            UnsignedIntegerObject::create(87),
        ])
    )
    ->add(
        TextStringObject::create('timestamp'),
        TimestampTag::create(UnsignedIntegerObject::create(time()))
    );

// Encode to binary
$encoded = (string) $data;

// Decode back
$decoder = Decoder::create();
$decoded = $decoder->decode(StringStream::create($encoded));

// Convert to native PHP types
$phpData = $decoded->normalize();

For more examples including WebAuthn, COSE, IoT scenarios, and advanced usage, see the complete documentation.

Contributing

Contributions are welcome! Here's how you can help:

• Report bugs and request features via GitHub Issues
• Fix issues labeled "help wanted"
• Improve documentation
• Submit pull requests

Please read our contribution guidelines before submitting.

Support

If you find this project valuable, consider supporting its development:

• Become a GitHub Sponsor
• Support via Patreon

License

This project is released under the MIT License.

Maintained by: Florent Morselli and contributors