Download the PHP package spomky-labs/cbor-bundle without Composer

CBOR Bundle for Symfony

A Symfony bundle that provides CBOR (Concise Binary Object Representation) encoding and decoding support for the Symfony Serializer component.

CBOR is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation. It is defined in RFC 8949.

Features

• 🔄 Full Symfony Serializer Integration: Works seamlessly with Symfony's serializer component
• 📦 Complete Type Support: Encode/decode all PHP types (scalars, arrays, objects, enums)
• ⚙️ Context Options: Fine-grained control over encoding behavior
• 🎯 Object Serialization: Serialize any PHP object to CBOR format
• 🔢 Enum Support: Native support for PHP 8.1+ backed and unit enums
• 📝 Well Documented: Comprehensive PHPDoc and guides
• ✅ Well Tested: Extensive test coverage

Requirements

• PHP 8.3 or higher
• Symfony 6.4, 7.x, or 8.x

Installation

Install the bundle using Composer:

If you're using Symfony Flex, the bundle will be automatically registered. Otherwise, register it manually in config/bundles.php:

Configuration

The bundle works out of the box. A single option controls how deeply nested a CBOR data item may be before the decoder rejects it:

Decoding is a recursive operation: a deeply nested payload — nested arrays, maps or tags cost one byte per level — can exhaust the call stack and crash the PHP process. Data nested deeper than max_depth is rejected with an InvalidArgumentException instead. When the data comes from an untrusted source, a much lower value is recommended:

Basic Usage

Encoding Data

Decoding Data

Object Serialization

Advanced Usage

Context Options

You can control encoding behavior using context options:

Available context options:

• cbor_single_precision_float (bool): Use 32-bit floats instead of 64-bit
• cbor_indefinite_text_string (bool): Use indefinite length for text strings
• cbor_indefinite_byte_string (bool): Use indefinite length for byte strings
• cbor_indefinite_list (bool): Use indefinite length for arrays
• cbor_indefinite_map (bool): Use indefinite length for maps

Enum Support

The bundle natively supports PHP 8.1+ enums:

Direct Service Access

You can also use the encoder/decoder services directly:

Or use the service aliases:

Supported Types

The bundle supports encoding and decoding of:

• Scalars: int, float, string, bool, null
• Arrays: Indexed arrays (as CBOR lists) and associative arrays (as CBOR maps)
• Objects: Any object that can be normalized by Symfony's normalizers
• Enums: PHP 8.1+ backed and unit enums
• DateTime: Automatically handled via Symfony's normalizers
• Nested structures: Arrays of objects, objects containing arrays, etc.

Extending the Bundle

The decoder service is built with a tag manager and an "other object" manager that know every tag class spomky-labs/cbor-php implements from the IANA registry -- date/time, big numbers, UUIDs, COSE messages and CBOR Web Tokens, typed arrays, IP addresses and so on -- and every simple value and float of major type 7. Both managers are services you can inject through their interface:

Tag classes and other object classes are not services: the decoder instantiates them itself, with the data of each item it reads. Registering one is therefore a matter of naming the class, and a class you register for a tag number (or a simple value) the library already handles replaces the built-in one.

Custom CBOR Tags

Implement CBOR\Tag\TagInterface (usually by extending CBOR\Tag, see the library guide) and list the class in the configuration:

A class that lives in a directory the service container discovers (src/ in a standard application) is registered automatically: the bundle autoconfigures every TagInterface implementation with the cbor.tag service tag, and only takes the class of such a service definition -- the container never tries to build it. The same tag can be set by hand on a class that is not discovered:

Custom CBOR Objects

Major type 7 items -- simple values, floats, the break code -- work the same way with CBOR\OtherObjectInterface (usually by extending CBOR\OtherObject), the other_objects configuration key and the cbor.other_object service tag:

Upgrading

See UPGRADE-4.0.md for migration instructions from version 3.x to 4.0.

Documentation

For more detailed information about CBOR:

• RFC 8949 - CBOR Specification
• CBOR Website

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

Security

If you discover a security vulnerability, please follow our security policy.

Support

If you find this project useful and want to support its development:

• ⭐ Star the project on GitHub
• 💰 Become a sponsor
• ☕ Support via Patreon

License

This project is released under the MIT License.

Credits

This bundle is maintained by Florent Morselli and contributors.