git.m6w6.name Git - awesomized/ext-ion/blob - ion.stub.php

   1 <?php
   2
   3 /**
   4  * Amazon ION serialization format.
   5  *
   6  * @link https://github.com/awesomized/ext-ion
   7  *
   8  * @see https://github.com/amzn/ion-c amzn/ion-c
   9  * @see https://amzn.github.io/ion-docs/ Amazon ION spec
  10  *
  11  * @generate-class-entries static
  12  * @generate-function-entries static
  13  */
  14
  15 namespace ion;
  16
  17 /**
  18  * Serialize a PHP value as ION data.
  19  *
  20  * Serializes supported PHP values with the optionally provided \ion\Serializer:
  21  *  * NULL
  22  *  * bool
  23  *  * int
  24  *  * float
  25  *  * string
  26  *  * references
  27  *  * arrays
  28  *  * objects (incl. \Serializable, and classes implementing magic and custom __serialize)
  29  *
  30  * @param mixed $data PHP value(s).
  31  * @param Serializer|null $serializer Custom serializer.
  32  * @return string serialized ION data
  33  * @throws ion\Exception
  34  */
  35 function serialize(mixed $data, ?Serializer $serializer = null) : string {}
  36
  37 /**
  38  * Unserialize ION data (stream) as PHP value(s).
  39  *
  40  * @param string|resource $data Serialized ION data, either as string buffer or stream,.
  41  * @return mixed unserialized PHP values
  42  * @throws ion\Exception
  43  */
  44 function unserialize($data, ?Unserializer $unserializer = null) : mixed {}
  45
  46 /**
  47  * Serializer interface, used to customize ion\serialize()'s behavior.
  48  */
  49 interface Serializer {
  50     public function serialize(mixed $data) : string;
  51 }
  52
  53 /**
  54  * Unserializer interface, used to customize ion\unserialize()'s behavior.
  55  */
  56 interface Unserializer {
  57     /** @param string|resource $data */
  58     public function unserialize($data) : mixed;
  59 }
  60
  61 /**
  62  * Base exception for the ION extension.
  63  */
  64 class Exception extends \Exception {
  65 }
  66
  67 /**
  68  * ION data type.
  69  *
  70  * The following special PHP classes are provided for some data types:
  71  * * ion\Decimal
  72  * * ion\Timestamp
  73  * * ion\Symbol
  74  * * ion\Lob
  75  */
  76 enum Type : int {
  77     case Null       = 0x000;
  78     case Bool       = 0x100;
  79     case Int        = 0x200;
  80     case Float      = 0x400;
  81     case Decimal    = 0x500;
  82     case Timestamp  = 0x600;
  83     case Symbol     = 0x700;
  84     case String     = 0x800;
  85     case CLob       = 0x900;
  86     case BLob       = 0xa00;
  87     case List       = 0xb00;
  88     case SExp       = 0xc00;
  89     case Struct     = 0xd00;
  90     case Datagram   = 0xf00;
  91
  92     case EOF        =-0x100;
  93     case NONE       =-0x200;
  94 }
  95
  96 /**
  97  * @see https://amzn.github.io/ion-docs/docs/spec.html#symbol ION spec's symbol definition
  98  * @see https://amzn.github.io/ion-docs/guides/symbols-guide.html ION spec's symbol guide
  99  */
 100 class Symbol {
 101     /**
 102      * Create an ION symbol.
 103      */
 104     public function __construct(
 105         /**
 106          * The symbol's text representation.
 107          */
 108         public readonly ?string $value = null,
 109         /**
 110          * The symbols ID, referencing its location within a shared symbol table.
 111          */
 112         public readonly int $sid = -1,
 113         /**
 114          * The import location referencing a shared symbol table.
 115          */
 116         public readonly ?Symbol\ImportLocation $importLocation = null,
 117     ) {}
 118
 119     /**
 120      * Compare two symbols for equality.
 121      *
 122      * Two symbols are considered equal, if either:
 123      * * both are the same object or NULL
 124      * * both values are NULL (unknown text), and both $importLocations match
 125      * * both values match, regardless of $sid and $importLocation
 126      *
 127      * @param Symbol $symbol
 128      * @return bool whether the two Symbols equal
 129      */
 130     public function equals(Symbol $symbol): bool {}
 131     public function __toString() : string {}
 132     /** @alias ion\Symbol::__toString */
 133     public function toString() : string {}
 134 }
 135
 136 /**
 137  * The Catalog holds a collection of ion\Symbol\Table instances queried from ion\Reader and ion\Writer instances.
 138  *
 139  * @see https://amzn.github.io/ion-docs/docs/symbols.html#the-catalog the ION spec's symbol guide chapter on catalog.
 140  */
 141 class Catalog implements \Countable {
 142     /** Internal cache. */
 143     private array $symbolTables = [];
 144
 145     /** Create a new Catalog. */
 146     public function __construct() {}
 147
 148     /** Count how many symbol tables the catalog holds. */
 149     public function count() : int {}
 150
 151     /**
 152      * Add a shared symbol table to the catalog.
 153      *
 154      * @param Symbol\Table $table The new table to add.
 155      */
 156     public function add(Symbol\Table $table) : void {}
 157
 158     /**
 159      * Remove a shared symbol table from the catalog.
 160      *
 161      * @param Symbol\Table|string $table The symbol table to renmove.
 162      * @return bool Success.
 163      */
 164     public function remove(Symbol\Table|string $table) : bool {}
 165
 166     /**
 167      * Find a shared symbol table within the catalog.
 168      *
 169      * @param string $name The name of the symbol table.
 170      * @param int $version The version the symbol table should match.
 171      * @return Symbol\Table|null The symbol table found, if any.
 172      */
 173     public function find(string $name, int $version = 0) : ?Symbol\Table {}
 174
 175     /**
 176      * Find a "best match" for a shared symbol table within the catalog.
 177      *
 178      * @param string $name The name of the symbol table,
 179      * @param int $version The minimum version of the symbol table.
 180      * @return Symbol\Table|null The symbol table found, if any.
 181      */
 182     public function findBest(string $name, int $version = 0) : ?Symbol\Table {}
 183 }
 184
 185 /**
 186  * A large object.
 187  *
 188  * @see ion\Type
 189  * @see https://amzn.github.io/ion-docs/docs/spec.html#blob the ION spec's BLob definition
 190  * @see https://amzn.github.io/ion-docs/docs/spec.html#clob the ION sepc's CLob definition
 191  */
 192 class LOB {
 193     /**
 194      * Create an ION large object.
 195      */
 196     public function __construct(
 197         /**
 198          * The value of the large object.
 199          */
 200         public readonly string $value,
 201         /**
 202          * The type (CLob/BLob).
 203          */
 204         public readonly Type $type = Type::CLob,
 205     ) {}
 206 }
 207
 208 /**
 209  * An arbitrary precision fixed point decimal.
 210  *
 211  * @see ion\Decimal\Context
 212  * @see https://amzn.github.io/ion-docs/docs/decimal.html the ION spec's decimal docs
 213  */
 214 class Decimal {
 215     /**
 216      * Create a new fixed point decimal.
 217      */
 218     public function __construct(
 219         /**
 220          * The decimal number.
 221          */
 222         public readonly string|int $number,
 223         /**
 224          * The decimal context.
 225          */
 226         public readonly ?Decimal\Context $context = null,
 227     ) {}
 228
 229     /**
 230      * Check two decimals for equality.
 231      *
 232      * @param Decimal $decimal The decimal to compare to.
 233      * @return bool Whether both decimals equal.
 234      */
 235     public function equals(Decimal $decimal) : bool {}
 236
 237     /**
 238      * Check whether the decimal is actually a big integer.
 239      * @return bool Whether the decimal is actually an integer.
 240      */
 241     public function isInt() : bool {}
 242
 243     public function __toString() : string {}
 244     /**
 245      * Get the string representation of the decimal.
 246      * @alias ion\Decimal::__toString
 247      */
 248     public function toString() : string {}
 249
 250     /**
 251      * Get the integer represention of the decimal.
 252      * @throws \ion\Exception If the decimal is actually not an integer.
 253      */
 254     public function toInt() : int {}
 255 }
 256
 257 /**
 258  * An ION Timestamp.
 259  * @see https://amzn.github.io/ion-docs/docs/spec.html#timestamp the ION sepc's timestamp definintion
 260  * @see https://php.net/date PHP's date documentation
 261  */
 262 class Timestamp extends \DateTime {
 263     /**
 264      * The timestamp's precision. See ion\Timestamp\Precision.
 265      */
 266     public readonly int $precision;
 267     /**
 268      * The timestamp's format. See ion\Timestamp\Format.
 269      */
 270     public readonly string $format;
 271
 272     /**
 273      * Create a new ION timestamp.
 274      *
 275      * @param Timestamp\Precision|int $precision The timestamp's precision.
 276      * @param Timestamp\Format|string|null $format The timestamp's format.
 277      * @param string|null $datetime The timestamp's value.
 278      * @param \DateTimeZone|null $timezone The timestamp's timezone.
 279      */
 280     public function __construct(
 281         Timestamp\Precision|int $precision,
 282         Timestamp\Format|string|null $format = null,
 283         ?string $datetime = null,
 284         ?\DateTimeZone $timezone = null,
 285     ) {}
 286
 287     public function __toString() : string {}
 288 }
 289
 290 /**
 291  * ION reader API.
 292  */
 293 interface Reader extends \RecursiveIterator {
 294     public function getType() : Type;
 295     public function hasAnnotations() : bool;
 296     public function hasAnnotation(string $annotation) : bool;
 297     public function isNull() : bool;
 298     public function isInStruct() : bool;
 299     public function getFieldName() : string;
 300     public function getFieldNameSymbol() : Symbol;
 301     public function getAnnotations() : array;
 302     public function getAnnotationSymbols() : array;
 303     public function countAnnotations() : int;
 304     public function getAnnotation(int $index) : string;
 305     public function getAnnotationSymbol(int $index) : Symbol;
 306
 307     public function readNull() : Type;
 308     public function readBool() : bool;
 309     public function readInt() : int|string;
 310     public function readFloat() : float;
 311     public function readDecimal() : Decimal;
 312     public function readTimestamp() : Timestamp;
 313     public function readSymbol() : Symbol;
 314     public function readString() : string;
 315     /** @param ref $string */
 316     public function readStringPart(&$string, int $length = 0x1000) : bool;
 317     public function readLob() : string;
 318     /** @param ref $string */
 319     public function readLobPart(&$string, int $length = 0x1000) : bool;
 320
 321     public function getPosition() : int;
 322     public function getDepth() : int;
 323
 324     public function seek(int $offset, int $length = -1) : void;
 325     /*
 326     public function getSymbolTable() : SymbolTable;
 327     public function setSymbolTable(SymbolTable $table) : void;
 328     */
 329     public function getValueOffset() : int;
 330     public function getValueLength() : int;
 331 }
 332
 333 /**
 334  * ION writer API.
 335  */
 336 interface Writer {
 337     public function writeNull() : void;
 338     public function writeTypedNull(Type $type) : void;
 339     public function writeBool(bool $value) : void;
 340     public function writeInt(int|string $value) : void;
 341     public function writeFloat(float $value) : void;
 342     public function writeDecimal(Decimal|string $value) : void;
 343     public function writeTimestamp(Timestamp|string $value) : void;
 344     public function writeSymbol(Symbol|string $value) : void;
 345     public function writeString(string $value) : void;
 346     public function writeCLob(string $value) : void;
 347     public function writeBLob(string $value) : void;
 348
 349     public function startLob(Type $type) : void;
 350     public function appendLob(string $data) : void;
 351     public function finishLob() : void;
 352
 353     public function startContainer(Type $type) : void;
 354     public function finishContainer() : void;
 355
 356     public function writeFieldName(string $name) : void;
 357
 358     public function writeAnnotation(Symbol|string ...$annotation) : void;
 359
 360     public function getDepth() : int;
 361     public function flush() : int;
 362     public function finish() : int;
 363
 364     // public function writeOne(Reader $reader) : void;
 365     // public function writeAll(Reader $reader) : void;
 366
 367     // public function getCatalog() : Catalog;
 368     // public function setCatalog(Catalog $catalog) : void;
 369
 370     // public function getSymbolTable() : Symbol\Table;
 371     // puvlic function setSymbolTable(Symbol\Table $table) : void;
 372 }
 373
 374 namespace ion\Symbol;
 375
 376 /**
 377  * The import location (referring to a shared table= of a symbol.
 378  */
 379 class ImportLocation {
 380     /**
 381      * Create a new import location.
 382      */
 383     public function __construct(
 384         /**
 385          * The name of the shared symbol table.
 386          */
 387         public readonly string $name,
 388         /**
 389          * The location (sid) of the symbol within the table.
 390          */
 391         public readonly int $location,
 392     ) {}
 393 }
 394
 395 /**
 396  * Base interface of built-in shared symbol tables.
 397  */
 398 interface Enum {
 399     /**
 400      * @return \ion\Symbol Instance of the symbol.
 401      */
 402     public function toSymbol() : \ion\Symbol;
 403
 404     /**
 405      * @return int The symbol id.
 406      */
 407     public function toSID() : int;
 408
 409     /**
 410      * @return string The symbol's textual representation.
 411      */
 412     public function toString() : string;
 413 }
 414
 415 /**
 416  * Base interface of an ION symbol table.
 417  */
 418 interface Table {
 419     /**
 420      * Get the maximum symbol ID within the symbol table.
 421      * @return int The maximum symbol ID.
 422      */
 423     public function getMaxId() : int;
 424
 425     /**
 426      * Add a symbol to the table.
 427      *
 428      * @param \ion\Symbol|string $symbol The symbol (value) to add.
 429      * @return int The symbol ID.
 430      */
 431     public function add(\ion\Symbol|string $symbol) : int;
 432
 433     /**
 434      * Find a symbol within the symbol table, including imports.
 435      *
 436      * @param string|int $id The ID or text of the symbol to find.
 437      * @return \ion\Symbol|null The symbol found, if any.
 438      */
 439     public function find(string|int $id) : ?\ion\Symbol;
 440
 441     /**
 442      * Find a symbol within **only this** symbol table, ignoring imports.
 443      *
 444      * @param string|int $id The ID or text of the symbol to find.
 445      * @return \ion\Symbol|null The symbol found, if any.
 446      */
 447     public function findLocal(string|int $id) : ?\ion\Symbol;
 448 }
 449
 450 namespace ion\Symbol\Table;
 451
 452 /**
 453  * Get the built-in PHP shared symbol table.
 454  *
 455  * @see \ion\Symbol\Table\PHP
 456  * @return \ion\Symbol\Table The builtin PHP shared symbol table.
 457  */
 458 function PHP() : \ion\Symbol\Table {}
 459
 460 /**
 461  * Get the built-in ION system shared symbol table.
 462  *
 463  * @see \ion\Symbol\Table\System
 464  * @return \ion\Symbol\Table The builtin ION system shared symbol table.
 465  */
 466 function System() : \ion\Symbol\Table {}
 467
 468 /**
 469  * The built-in ION system symbols.
 470  */
 471 enum System : string implements \ion\Symbol\Enum {
 472     case Ion                = '$ion';
 473     case Ivm_1_0            = '$ion_1_0';
 474     case IonSymbolTable     = '$ion_symbol_table';
 475     case Name               = 'name';
 476     case Version            = 'version';
 477     case Imports            = 'imports';
 478     case Symbols            = 'symbols';
 479     case MaxId              = 'max_id';
 480     case SharedSymbolTable  = '$ion_shared_symbol_table';
 481
 482     /** @alias ion\Symbol\Enum::toSymbol */
 483     public function toSymbol() : \ion\Symbol {}
 484     /** @alias ion\Symbol\Enum::toSID */
 485     public function toSID() : int {}
 486     /** @alias ion\Symbol\Enum::toString */
 487     public function toString() : string {}
 488 }
 489
 490 /**
 491  * The built-in PHP symbols.
 492  */
 493 enum PHP : string implements \ion\Symbol\Enum {
 494     case PHP            = 'PHP';
 495     case Reference      = 'R';
 496     case Backref        = 'r';
 497     case Property       = 'p';
 498     case Object         = 'o';
 499     case ClassObject    = 'c';
 500     case MagicObject    = 'O';
 501     case CustomObject   = 'C';
 502     case Enum           = 'E';
 503     case Serializable   = 'S';
 504
 505     /** @alias ion\Symbol\Enum::toSymbol */
 506     public function toSymbol() : \ion\Symbol {}
 507     /** @alias ion\Symbol\Enum::toSID */
 508     public function toSID() : int {}
 509     /** @alias ion\Symbol\Enum::toString */
 510     public function toString() : string {}
 511 }
 512
 513 /**
 514  * A local symbol table.
 515  *
 516  * @see https://amzn.github.io/ion-docs/guides/symbols-guide.html the ION spec's symbol guide
 517  * @see https://amzn.github.io/ion-docs/guides/cookbook.html#using-a-local-symbol-table the ION doc's cookbook
 518  */
 519 class Local implements \ion\Symbol\Table {
 520     /** Internal cache. */
 521     private array $imports = [];
 522     /** Internal cache. */
 523     private array $symbols = [];
 524
 525     /**
 526      * Create a local symbol table.
 527      */
 528     public function __construct() {}
 529
 530     /**
 531      * Import a symbol table.
 532      *
 533      * @param \ion\Symbol\Table $table The symbol table to import.
 534      * @return void
 535      */
 536     public function import(\ion\Symbol\Table $table) : void {}
 537
 538     /** @alias ion\Symbol\Table::getMaxId */
 539     public function getMaxId() : int {}
 540
 541     /** @alias ion\Symbol\Table::add */
 542     public function add(\ion\Symbol|string $symbol) : int {}
 543     /** @alias ion\Symbol\Table::find */
 544     public function find(string|int $id) : ?\ion\Symbol {}
 545     /** @alias ion\Symbol\Table::findLocal */
 546     public function findLocal(string|int $id) : ?\ion\Symbol {}
 547 }
 548
 549 /**
 550  * A shared symbol table.
 551  *
 552  * @see https://amzn.github.io/ion-docs/guides/symbols-guide.html the ION spec's symbol guide
 553  * @see https://amzn.github.io/ion-docs/guides/cookbook.html#using-a-shared-symbol-table the ION doc's cookbook
 554  */
 555 class Shared implements \ion\Symbol\Table {
 556     /**
 557      * Create a shared symbol table.
 558      */
 559     public function __construct(
 560         /**
 561          * The name of the shared symbol table.
 562          */
 563         public readonly string $name,
 564         /**
 565          * The version of the shared symbol table.
 566          */
 567         public readonly int $version = 1,
 568         /**
 569          * Predefined list of symbols as array of strings.
 570          */
 571         ?array $symbols = null,
 572     ) {}
 573
 574     /** Internal cache. */
 575     private array $symbols = [];
 576
 577     /** @alias ion\Symbol\Table::getMaxId */
 578     public function getMaxId() : int {}
 579
 580     /** @alias ion\Symbol\Table::add */
 581     public function add(\ion\Symbol|string $symbol) : int {}
 582     /** @alias ion\Symbol\Table::find */
 583     public function find(string|int $id) : ?\ion\Symbol {}
 584     /** @alias ion\Symbol\Table::findLocal */
 585     public function findLocal(string|int $id) : ?\ion\Symbol {}
 586 }
 587
 588 namespace ion\Decimal;
 589
 590 /**
 591  * An ion\Decimal's context.
 592  */
 593 class Context {
 594     /**
 595      * Create a new decimal context.
 596      */
 597     public function __construct(
 598         /**
 599          * Maximum digits.
 600          */
 601         public readonly int $digits,
 602         /**
 603          * Maximum exponent.
 604          */
 605         public readonly int $eMax,
 606         /**
 607          * Minimum exponent.
 608          */
 609         public readonly int $eMin,
 610         /**
 611          * Rounding mode.
 612          */
 613         public readonly Context\Rounding|int $round,
 614         /**
 615          * Whether to clamp.
 616          */
 617         public readonly bool $clamp,
 618     ) {}
 619
 620     /**
 621      * Create a context suitable for 32bit decimals.
 622      */
 623     public static function Dec32() : Context {}
 624
 625     /**
 626      * Create a context suitable for 64bit decimals.
 627      */
 628     public static function Dec64() : Context {}
 629
 630     /**
 631      * Create a context suitable for 128bit decimals.
 632      */
 633     public static function Dec128() : Context {}
 634
 635     /**
 636      * Create a context with maximum settings.
 637      * @param Context\Rounding|int $round Rounding mode.
 638      */
 639     public static function DecMax(Context\Rounding|int $round = Context\Rounding::HalfEven) : Context {}
 640 }
 641
 642 namespace ion\Decimal\Context;
 643
 644 /**
 645  * Rounding mode.
 646  */
 647 enum Rounding : int {
 648     case Ceiling    = 0;
 649     case Up         = 1;
 650     case HalfUp     = 2;
 651     case HalfEven   = 3;
 652     case HalfDown   = 4;
 653     case Down       = 5;
 654     case Floor      = 6;
 655     case Down05Up   = 7;
 656 }
 657
 658 namespace ion\Timestamp;
 659
 660 /**
 661  * Timestamp precision.
 662  */
 663 enum Precision : int {
 664     case Year           = 0x1;
 665     case Month          = 0x1|0x2;
 666     case Day            = 0x1|0x2|0x4;
 667     case Min            = 0x1|0x2|0x4|0x10;
 668     case Sec            = 0x1|0x2|0x4|0x10|0x20;
 669     case Frac           = 0x1|0x2|0x4|0x10|0x20|0x40;
 670     case MinTZ          = 0x1|0x2|0x4|0x10|0x80;
 671     case SecTZ          = 0x1|0x2|0x4|0x10|0x20|0x80;
 672     case FracTZ         = 0x1|0x2|0x4|0x10|0x20|0x40|0x80;
 673 }
 674
 675 /**
 676  * Timestamp format.
 677  */
 678 enum Format : string {
 679     case Year           = "Y\T";
 680     case Month          = "Y-m\T";
 681     case Day            = "Y-m-d\T";
 682     case Min            = "Y-m-d\TH:i";
 683     case Sec            = "Y-m-d\TH:i:s";
 684     case Frac           = "Y-m-d\TH:i:s.v";
 685     case MinTZ          = "Y-m-d\TH:iP";
 686     case SecTZ          = "Y-m-d\TH:i:sP";
 687     case FracTZ         = "Y-m-d\TH:i:s.vP";
 688 }
 689
 690 namespace ion\Reader;
 691
 692 /**
 693  * Reader options.
 694  */
 695 class Options {
 696     public function __construct(
 697         /**
 698          * ION catalog to use for symbol lookup.
 699          */
 700         public readonly ?\ion\Catalog $catalog = null,
 701         /**
 702          * Decimal context to use.
 703          */
 704         public readonly ?\ion\Decimal\Context $decimalContext = null,
 705         /**
 706          * Callback as function(\ion\Reader):void called upon local symbol table context change.
 707          */
 708         public readonly ?\Closure $onContextChange = null,
 709         /**
 710          * Whether to return otherwise hidden system values.
 711          */
 712         public readonly bool $returnSystemValues = false,
 713         /**
 714          * The maximum depth of nested containers.
 715          */
 716         public readonly int $maxContainerDepth = 10,
 717         /**
 718          * The maximum number of annotations allowed on a single value.
 719          */
 720         public readonly int $maxAnnotations = 10,
 721         /**
 722          * The maximum number of bytes of all annotations on a single value.
 723          */
 724         public readonly int $annotationBufferSize = 0x4000,
 725         /**
 726          * The maximum number of bytes of a symbol/value/chunk.
 727          */
 728         public readonly int $tempBufferSize = 0x4000,
 729         /**
 730          * Whether to skip UTF-8 validation.
 731          */
 732         public readonly bool $skipCharacterValidation = false,
 733     ) {}
 734 }
 735
 736 /**
 737  * Base implementation of ION readers.
 738  */
 739 abstract class Reader implements \ion\Reader {
 740     /**
 741      * Reader options.
 742      */
 743     public readonly ?Options $options;
 744
 745     public function hasChildren() : bool {}
 746     public function getChildren() : \ion\Reader {}
 747
 748     public function rewind() : void {}
 749     public function next() : void {}
 750     public function valid() : bool {}
 751     public function key() : mixed {}
 752     public function current() : mixed {}
 753
 754     public function getType() : \ion\Type {}
 755     public function hasAnnotations() : bool {}
 756     public function hasAnnotation(string $annotation) : bool {}
 757     public function isNull() : bool {}
 758     public function isInStruct() : bool {}
 759     public function getFieldName() : string {}
 760     public function getFieldNameSymbol() : \ion\Symbol {}
 761     public function getAnnotations() : array {}
 762     public function getAnnotationSymbols() : array {}
 763     public function countAnnotations() : int {}
 764     public function getAnnotation(int $index) : string {}
 765     public function getAnnotationSymbol(int $index) : \ion\Symbol {}
 766
 767     public function readNull() : \ion\Type {}
 768     public function readBool() : bool {}
 769     public function readInt() : int|string {}
 770     public function readFloat() : float {}
 771     public function readDecimal() : \ion\Decimal {}
 772     public function readTimestamp() : \ion\Timestamp {}
 773     public function readSymbol() : \ion\Symbol {}
 774     public function readString() : string {}
 775     /** @param ref $string */
 776     public function readStringPart(&$string, int $length = 0x1000) : bool {}
 777     public function readLob() : string {}
 778     /** @param ref $string */
 779     public function readLobPart(&$string, int $length = 0x1000) : bool {}
 780
 781     public function getPosition() : int {}
 782     public function getDepth() : int{}
 783
 784     public function seek(int $offset, int $length = -1) : void {}
 785     /*
 786     public function getSymbolTable() : SymbolTable {}
 787     public function setSymbolTable(SymbolTable $table) : void {}
 788     */
 789     public function getValueOffset() : int {}
 790     public function getValueLength() : int {}
 791 }
 792
 793 /**
 794  * ION string buffer reader API.
 795  */
 796 interface Buffer extends \ion\Reader {
 797     /**
 798      * Get the buffer read from.
 799      *
 800      * @return string The buffer read from.
 801      */
 802     public function getBuffer() : string;
 803 }
 804
 805 /**
 806  * ION stream reader API.
 807  */
 808 interface Stream extends \ion\Reader {
 809     /**
 810      * Get the stream read from.
 811      *
 812      * @return resource The stream read from.
 813      */
 814     public function getStream();
 815
 816     /**
 817      * Reset the stream read from.
 818      *
 819      * @param resource $stream The new stream to from.
 820      */
 821     public function resetStream($stream) : void;
 822
 823     /**
 824      * Reset the stream read from, limiting length to read.
 825      *
 826      * @param resource $stream The stream to read from.
 827      * @param int $length The maximum length to read from $stream.
 828      */
 829     public function resetStreamWithLength($stream, int $length) : void;
 830 }
 831
 832 namespace ion\Reader\Buffer;
 833
 834 /**
 835  * ION string buffer reader.
 836  */
 837 class Reader extends \ion\Reader\Reader implements \ion\Reader\Buffer {
 838     /**
 839      * Create a new string buffer reader.
 840      *
 841      * @param string $buffer The buffer to read from.
 842      * @param \ion\Reader\Options|null $options Reader options.
 843      */
 844     public function __construct(
 845         string $buffer,
 846         ?\ion\Reader\Options $options = null,
 847     ) {}
 848
 849     public function getBuffer() : string {}
 850 }
 851
 852 namespace ion\Reader\Stream;
 853
 854 /**
 855  * ION stream reader.
 856  */
 857 class Reader extends \ion\Reader\Reader implements \ion\Reader\Stream {
 858     /**
 859      * Create a new stream reader.
 860      *
 861      * @param resource $stream The stream to read from.
 862      * @param \ion\Reader\Options|null $options Reader options.
 863      */
 864     public function __construct(
 865         $stream,
 866         ?\ion\Reader\Options $options = null,
 867     ) {}
 868
 869     /**
 870      * Get the stream read from.
 871      *
 872      * @return resource The stream read from.
 873      */
 874     public function getStream() {}
 875
 876     /** @param resource $stream */
 877     public function resetStream($stream) : void {}
 878     /** @param resource $stream */
 879     public function resetStreamWithLength($stream, int $length) : void {}
 880 }
 881
 882 namespace ion\Writer;
 883
 884 /**
 885  * ION writer options.
 886  */
 887 class Options {
 888     /**
 889      * Create custom ION writer options.
 890      */
 891     public function __construct(
 892         /**
 893          * ION catalog to use for symbol lookup.
 894          */
 895         public readonly ?\ion\Catalog $catalog = null,
 896         /**
 897          * Decimal context to use.
 898          */
 899         public readonly ?\ion\Decimal\Context $decimalContext = null,
 900         /**
 901          * Whether to output binary ION.
 902          */
 903         public readonly bool $outputBinary = false,
 904         /**
 905          * Whether to write doubles which fit in 32 bits as floats.
 906          */
 907         public readonly bool $compactFloats = false,
 908         /**
 909          * Whether to slash-escape all non ASCII bytes.
 910          */
 911         public readonly bool $escapeNonAscii = false,
 912         /**
 913          * Whether to produce pretty-printed output.
 914          */
 915         public readonly bool $prettyPrint = false,
 916         /**
 917          * Whether to indent with tabs, when pretty-printing.
 918          */
 919         public readonly bool $indentTabs = true,
 920         /**
 921          * The number of spaces to use for indentation instead of tabs, when pretty-printing.
 922          */
 923         public readonly int $indentSize = 2,
 924         /**
 925          * Whether to immediately flush every value written.
 926          */
 927         public readonly bool $flushEveryValue = false,
 928         /**
 929          * Maximum depth of nested containers.
 930          */
 931         public readonly int $maxContainerDepth = 10,
 932         /**
 933          * The maximum number of annotations allowed on a single value.
 934          */
 935         public readonly int $maxAnnotations = 10,
 936         /**
 937          * Temporary buffer size.
 938          */
 939         public readonly int $tempBufferSize = 0x4000,
 940     ) {}
 941 }
 942
 943 /**
 944  * Base implementation of common functionality of ION writers.
 945  */
 946 abstract class Writer implements \ion\Writer {
 947     public function writeNull() : void {}
 948     public function writeTypedNull(\ion\Type $type) : void {}
 949     public function writeBool(bool $value) : void {}
 950     public function writeInt(int|string $value) : void {}
 951     public function writeFloat(float $value) : void {}
 952     public function writeDecimal(\ion\Decimal|string $value) : void {}
 953     public function writeTimestamp(\ion\Timestamp|string $value) : void {}
 954     public function writeSymbol(\ion\Symbol|string $value) : void {}
 955     public function writeString(string $value) : void {}
 956     public function writeCLob(string $value) : void {}
 957     public function writeBLob(string $value) : void {}
 958
 959     public function startLob(\ion\Type $type) : void {}
 960     public function appendLob(string $data) : void {}
 961     public function finishLob() : void {}
 962
 963     public function startContainer(\ion\Type $type) : void {}
 964     public function finishContainer() : void {}
 965
 966     public function writeFieldName(string $name) : void {}
 967
 968     public function writeAnnotation(\ion\Symbol|string ...$annotation) : void {}
 969
 970     public function getDepth() : int {}
 971     public function flush() : int {}
 972     public function finish() : int {}
 973
 974     // public function writeOne(\ion\Reader $reader) : void {}
 975     // public function writeAll(\ion\Reader $reader) : void {}
 976 }
 977
 978 /**
 979  * ION buffer writer API.
 980  */
 981 interface Buffer extends \ion\Writer {
 982     /**
 983      * Get the buffer written to.
 984      *
 985      * @reeturn string The buffer written so far.
 986      */
 987     public function getBuffer() : string;
 988
 989     /**
 990      * Reset the buffer written to.
 991      */
 992     public function resetBuffer() : void;
 993 }
 994
 995 /**
 996  * ION stream writer API.
 997  */
 998 interface Stream extends \ion\Writer {
 999     /**
1000      * Get the stream being written to.
1001      * @return resource
1002      */
1003     public function getStream();
1004 }
1005
1006 namespace ion\Writer\Buffer;
1007
1008 /**
1009  * IO buffer writer.
1010  */
1011 class Writer extends \ion\Writer\Writer implements \ion\Writer\Buffer {
1012     /**
1013      * Create a new buffer writer.
1014      *
1015      * @param \ion\Writer\Options|null $options Writer options.
1016      */
1017     public function __construct(
1018         ?\ion\Writer\Options $options = null,
1019     ) {}
1020
1021     public function getBuffer() : string {}
1022     public function resetBuffer() : void {}
1023 }
1024
1025 namespace ion\Writer\Stream;
1026
1027 /**
1028  * ION stream writer.
1029  */
1030 class Writer extends \ion\Writer\Writer implements \ion\Writer\Stream {
1031     /**
1032      * Create a new stream writer.
1033      *
1034      * @param resource $stream The stream to write to.
1035      * @param \ion\Writer\Options|null $options Writer options.
1036      */
1037     public function __construct(
1038         $stream,
1039         ?\ion\Writer\Options $options = null,
1040     ) {}
1041     /**
1042      * @return resource
1043      */
1044     public function getStream() {}
1045 }
1046
1047 namespace ion\Serializer;
1048
1049 /**
1050  * Specialization of the serializer for PHP.
1051  */
1052 class PHP implements \ion\Serializer {
1053     /**
1054      * Create a new PHP ION serializer.
1055      */
1056     public function __construct(
1057         /**
1058          * Writer options.
1059          */
1060         public readonly ?\ion\Writer\Options $writerOptions = null,
1061         /**
1062          * Whether to write the top level array as multiple ION sequences.
1063          */
1064         public readonly bool $multiSequence = false,
1065         /**
1066          * Whether to call magic __serialize() methods on objects to serialize.
1067          */
1068         public readonly bool $callMagicSerialize = true,
1069         /**
1070          * Whether and which custom serialize method to call on objects to serialize.
1071          */
1072         public readonly ?string $callCustomSerialize = null,
1073     ) {}
1074
1075     public function serialize(mixed $data) : string {}
1076 }
1077
1078 namespace ion\Unserializer;
1079
1080 /**
1081  * Specialization of the unserializer for PHP.
1082  */
1083 class PHP implements \ion\Unserializer {
1084     /**
1085      * Create a new ION PHP unserializer.
1086      */
1087     public function __construct(
1088         /**
1089          * Reader options.
1090          */
1091         public readonly ?\ion\Reader\Options $readerOptions = null,
1092         /**
1093          * Whether to continue reading multiple ION sequences after the first one.
1094          */
1095         public readonly bool $multiSequence = false,
1096         /**
1097          * Whether to call magic __unserialize() methods on objects to unserialize.
1098          */
1099         public readonly bool $callMagicUnserialize = true,
1100         /**
1101          * Whether and which custom unserialize method to call on objects to unserialize.
1102          */
1103         public readonly ?string $callCustomUnserialize = null,
1104     ){}
1105
1106     /** @param string|resource $data */
1107     public function unserialize($data) : mixed {}
1108 }