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