README

范围

这个库可以帮助您使用简洁二进制对象表示（CBOR - RFC8949）解码和创建对象。

安装

使用 Composer 安装库：composer require spomky-labs/cbor-php。

该项目严格遵守语义版本控制。

支持

我会为您解决问题，并回答您的问题。

如果您真的喜欢这个项目，或者我想优先处理您的问题，那么您可以通过赞助我一些🍻或更多来帮助我！

成为赞助者

或者

文档

对象创建

这个库支持 RFC8949 中定义的所有主要类型，并具有支持任何类型标签（主要类型 6）和其他对象（主要类型 7）的能力。

每个对象至少有

• 一个静态方法 create。该方法将正确实例化对象。
• 可以被转换为二进制字符串：$object->__toString(); 或 (string) $object。

正整数（主要类型 0）

<?php

use CBOR\UnsignedIntegerObject;

$object = UnsignedIntegerObject::create(10);
$object = UnsignedIntegerObject::create(1000);
$object = UnsignedIntegerObject::create(10000);
$object = UnsignedIntegerObject::createFromHex('0AFFEBFF');

echo bin2hex((string)$object); // 1a0affebff

负整数（主要类型 1）

<?php

use CBOR\NegativeIntegerObject;

$object = NegativeIntegerObject::create(-10);
$object = NegativeIntegerObject::create(-1000);
$object = NegativeIntegerObject::create(-10000);

字节字符串 / 不定长字节字符串（主要类型 2）

字节字符串和不定长字节字符串对象具有相同的主要类型，但在这个库中由两个不同的类处理。

<?php

use CBOR\ByteStringObject; // Byte String
use CBOR\IndefiniteLengthByteStringObject; // Indefinite Length Byte String

// Create a Byte String with value "Hello"
$object = ByteStringObject::create('Hello');

// Create an Indefinite Length Byte String with value "Hello" ("He" + "" + "ll" + "o")
$object = IndefiniteLengthByteStringObject::create()
    ->append('He')
    ->append('')
    ->append('ll')
    ->append('o')
;

文本字符串 / 不定长文本字符串（主要类型 3）

文本字符串和不定长文本字符串对象具有相同的主要类型，但在这个库中由两个不同的类处理。

<?php

use CBOR\TextStringObject; // Text String
use CBOR\IndefiniteLengthTextStringObject; // Indefinite Length Text String

// Create a Text String with value "(｡◕‿◕｡)⚡"
$object = TextStringObject::create('(｡◕‿◕｡)⚡');

// Create an Indefinite Length Text String with value "(｡◕‿◕｡)⚡" ("(｡◕" + "" + "‿◕" + "｡)⚡")
$object = IndefiniteLengthTextStringObject::create()
    ->append('(｡◕')
    ->append('')
    ->append('‿◕')
    ->append('｡)⚡')
;

列表 / 不定长列表（主要类型 4）

列表和不定长列表对象具有相同的主要类型，但在这个库中由两个不同的类处理。列表对象中的项可以是任何 CBOR 对象类型。

<?php

use CBOR\ListObject; // List
use CBOR\IndefiniteLengthListObject; // Infinite List
use CBOR\TextStringObject;
use CBOR\UnsignedIntegerObject;

// Create a List with a single item
$object = ListObject::create()
    ->add(TextStringObject::create('(｡◕‿◕｡)⚡'))
;

// Create an Infinite List with several items
$object = IndefiniteLengthListObject::create()
    ->add(TextStringObject::create('(｡◕‿◕｡)⚡'))
    ->add(UnsignedIntegerObject::create(25))
;

映射 / 不定长映射（主要类型 5）

映射和不定长映射对象具有相同的主要类型，但在这个库中由两个不同的类处理。映射对象中的键和值可以是任何 CBOR 对象类型。

但是，请务必小心处理键。请遵循以下建议

• 键不应重复
• 键应该是正整数或负整数，（不定长）字节字符串或（不定长）文本字符串。其他类型可能会导致错误。

<?php

use CBOR\MapObject; // Map
use CBOR\IndefiniteLengthMapObject; // Infinite Map
use CBOR\ByteStringObject;
use CBOR\TextStringObject;
use CBOR\UnsignedIntegerObject;
use CBOR\NegativeIntegerObject;

// Create a Map with a single item
$object = MapObject::create()
    ->add(UnsignedIntegerObject::create(25), TextStringObject::create('(｡◕‿◕｡)⚡'))
;

// Create an Infinite Map with several items
$object = IndefiniteLengthMapObject::create()
    ->append(ByteStringObject::create('A'), NegativeIntegerObject::create(-652))
    ->append(UnsignedIntegerObject::create(25), TextStringObject::create('(｡◕‿◕｡)⚡'))
;

标签（主要类型 6）

这个库可以支持任何类型的标签。它包含了一些在规范中描述的标签

• 十六进制编码
• Base64 编码
• Base64 URL 安全编码
• 大浮点数
• 小数分数
• 纪元
• 时间戳
• 正大整数
• 负大整数

您可以通过扩展抽象类 CBOR\TagObject 轻松创建自己的标签。这个库提供了一个 CBOR\Tag\GenericTag 类，可以用于任何其他未知/不受支持的标签。

<?php

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

// Create an unsigned object that represents the current timestamp
$object = UnsignedIntegerObject::create(time()); // e.g. 1525873787

//We tag the object with the Timestamp Tag
$taggedObject = TimestampTag::create($object); // Returns a \DateTimeImmutable object with timestamp at 1525873787

其他对象（主要类型 7）

这个库可以支持任何类型的“其他对象”。它包含了一些在规范中描述的对象

• 假
• 真
• 空
• 未定义
• 半精度浮点数
• 单精度浮点数
• 双精度浮点数
• 简单值

您可以通过扩展抽象类 CBOR\OtherObject 轻松创建自己的对象。此库提供了一个 CBOR\OtherObject\GenericTag 类，可用于任何其他未知或不支持的对象。

由于 PHP 不支持 'undefined' 对象，规范化方法将返回 'undefined'。

<?php

use CBOR\OtherObject\FalseObject;
use CBOR\OtherObject\NullObject;
use CBOR\OtherObject\UndefinedObject;

$object = FalseObject::create();
$object = NullObject::create();
$object = UndefinedObject::create();

示例

<?php

use CBOR\MapObject;
use CBOR\OtherObject\UndefinedObject;
use CBOR\TextStringObject;
use CBOR\ListObject;
use CBOR\NegativeIntegerObject;
use CBOR\UnsignedIntegerObject;
use CBOR\OtherObject\TrueObject;
use CBOR\OtherObject\FalseObject;
use CBOR\OtherObject\NullObject;
use CBOR\Tag\DecimalFractionTag;
use CBOR\Tag\TimestampTag;

$object = MapObject::create()
    ->add(
        TextStringObject::create('(｡◕‿◕｡)⚡'),
        ListObject::create([
            TrueObject::create(),
            FalseObject::create(),
            UndefinedObject::create(),
            DecimalFractionTag::createFromExponentAndMantissa(
                NegativeIntegerObject::create(-2),
                UnsignedIntegerObject::create(1234)
            ),
        ])
    )
    ->add(
        UnsignedIntegerObject::create(2000),
        NullObject::create()
    )
    ->add(
        TextStringObject::create('date'),
        TimestampTag::create(UnsignedIntegerObject::create(1577836800))
    )
;

编码后的结果将是 0xa37428efbda1e29795e280bfe29795efbda129e29aa183f5f4c482211904d21907d0f66464617465c11a5e0be100。

对象加载

如果您想加载 CBOR 编码的字符串，只需实例化一个 CBOR\Decoder 类。此类不需要任何参数。

<?php

use CBOR\Decoder;

$decoder = Decoder::create();

如有需要，您可以定义自定义的标签和其他对象支持管理器集。

<?php

use CBOR\Decoder;
use CBOR\OtherObject;
use CBOR\Tag;

$otherObjectManager = OtherObject\OtherObjectManager::create()
    ->add(OtherObject\SimpleObject::class)
    ->add(OtherObject\FalseObject::class)
    ->add(OtherObject\TrueObject::class)
    ->add(OtherObject\NullObject::class)
    ->add(OtherObject\UndefinedObject::class)
    ->add(OtherObject\HalfPrecisionFloatObject::class)
    ->add(OtherObject\SinglePrecisionFloatObject::class)
    ->add(OtherObject\DoublePrecisionFloatObject::class)
;

$tagManager = Tag\TagManager::create()
    ->add(Tag\DatetimeTag::class)
    ->add(Tag\TimestampTag::class)
    ->add(Tag\UnsignedBigIntegerTag::class)
    ->add(Tag\NegativeBigIntegerTag::class)
    ->add(Tag\DecimalFractionTag::class)
    ->add(Tag\BigFloatTag::class)
    ->add(Tag\Base64UrlEncodingTag::class)
    ->add(Tag\Base64EncodingTag::class)
    ->add(Tag\Base16EncodingTag::class)
;

$decoder = Decoder::create($tagManager, $otherObjectManager);

然后，解码器将读取您想要加载的数据。数据必须由实现 CBOR\Stream 接口的对象处理。此库提供了一个 CBOR\StringStream 类以流式传输字符串。

<?php

use CBOR\StringStream;

// CBOR object (in hex for the example)
$data = hex2bin('fb3fd5555555555555');

// String Stream
$stream = StringStream::create($data);

// Load the data
$object = $decoder->decode($stream); // Return a CBOR\OtherObject\DoublePrecisionFloatObject class with normalized value ~0.3333 (1/3)

贡献

欢迎对新功能、错误修复以及所有其他使此项目有用的想法提出请求。您可以提供的最佳贡献是修复那些需要帮助的 开放问题。

请在 主存储库 中报告所有问题。

请确保遵循这些 最佳实践。

许可证

此项目基于 MIT 许可证 发布。