git.m6w6.name Git - awesomized/ext-ion/blob - docs/v0.1/ion/: Tutorial/:1. Getting started.html

   1 <!doctype html>
   2 <html>
   3         <head>
   4                 <meta charset="utf-8">
   5                 <title>
   6                                                         ★1. Getting started -
   7                                                 mdref
   8                 </title>
   9                 <meta property="og:title" content="ion/: Tutorial/:1. Getting started">
  10                 <meta name="viewport" content="width=1200, initial-scale=0.5">
  11                                         <base href="/ext-ion/v0.1/">
  12                         <meta http-equiv="Content-Location" content="/ext-ion/v0.1/ion/: Tutorial/:1. Getting started">
  13                         <link rel="stylesheet" href="index.css">
  14
  15                 <link rel="shortcut icon" href="/ext-ion/v0.1/favicon.ico">
  16         </head>
  17         <body>
  18                 <div class="page">
  19
  20 <div class="sidebar">
  21
  22         <div class="edit">
  23                 <a href="https://github.com/awesomized/ext-ion/edit/master/ion.stub.php">Edit</a>
  24         </div>
  25
  26
  27         <ul>
  28                 <li>&lsh; <a href="./">Home</a>
  29
  30                         <ul>
  31                                 <li>
  32
  33                                         &uarr; <a href="./ion">
  34                                                         ion
  35                                                 </a>
  36                                                 <ul>
  37                                                         <li>
  38
  39                                         &uarr; <a href="./ion/: Tutorial">
  40                                                         ★ Tutorial
  41                                                 </a>
  42                                                 <ul>
  43                                                         <li>
  44
  45                                                         &circlearrowright; <strong><a href="./ion/: Tutorial/:1. Getting started">★1. Getting started</a></strong>
  46
  47
  48
  49                                                 </ul>
  50
  51                                                 <li>&ldsh; <a href="./ion/: Tutorial/:2. What is ion">★2. What is ion</a></li>
  52
  53                                                 <li>&ldsh; <a href="./ion/: Tutorial/:3. Standard Datatypes">★3. Standard Datatypes</a></li>
  54
  55                                                 <li>&ldsh; <a href="./ion/: Tutorial/:4. Special Datatypes">★4. Special Datatypes</a></li>
  56
  57                                                 <li>&ldsh; <a href="./ion/: Tutorial/:5. Symbols, Tables and Catalogs">★5. Symbols, Tables and Catalogs</a></li>
  58
  59                                         </ul>
  60
  61                                 </li>
  62                         </ul>
  63
  64                 </li>
  65         </ul>
  66 </div>
  67                                         <meta charset="utf-8"><h1>
  68 <a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#">#</a>Getting started</h1><p>The PHP extension for Ion requires <strong>PHP version 8.1</strong> or greater, see the <a href="ion/:%20Tutorial/:1.%20Getting%20started#Install">Install</a> section.</p><h2 id="Why.Ion.">Why Ion?<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Why.Ion.">#</a>
  69 </h2><ul>
  70 <li>Ion provides <strong><a href="ion/:%20Tutorial/:1.%20Getting%20started#Dual-format.interoperability">dual-format interoperability</a></strong>, which enables users to take advantage of the ease of use of the text format while capitalizing on the efficiency of the binary format. The text form is easy to prototype, test, and debug, while the binary format saves space and parsing effort.</li>
  71 <li>Ion’s <strong><a href="ion/:%20Tutorial/:1.%20Getting%20started#Rich.type.system">rich type system</a></strong> <em>extends</em> JSON’s, adding support for types that make Ion suitable for a wider variety of uses, including precision-sensitive applications and portability across languages and runtimes.</li>
  72 <li>Ion is a <strong><a href="ion/:%20Tutorial/:1.%20Getting%20started#Self-describing">self-describing</a></strong> format, giving its readers and writers the flexibility to exchange Ion data without needing to agree on a schema in advance. Ion’s “open-content” supports discovery, deep component chaining, and schema evolution.</li>
  73 <li>Because most data is read more often than it is written, Ion defines a <strong><a href="ion/:%20Tutorial/:1.%20Getting%20started#Read-optimized.binary.format">read-optimized binary format</a></strong>.</li>
  74 </ul><h3 id="Dual-format.interoperability">Dual-format interoperability<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Dual-format.interoperability">#</a>
  75 </h3><p>Applications can seamlessly consume Ion data in either its text or binary forms without loss of data fidelity. While the expectation is that most Ion data is in binary form, the text form promotes human readability, simplifying discovery and diagnosis.</p><p>Notably, the text format is a superset of JSON, making all JSON data valid Ion data. You probably already know how to read and author Ion.</p><h4 id="Ease.of.use">Ease of use<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Ease.of.use">#</a>
  76 </h4><p>Like JSON, Ion’s text format is concise and clearly legible. It is intelligible to humans and may be edited using familiar tools like a text editor. This makes Ion well-suited to rapid prototyping: developers can quickly mock up the their data in text Ion, knowing that their application will ultimately seamlessly process the more efficient binary Ion format. Once the application is up and running, the users can debug it by intercepting the binary Ion data and converting it to text Ion with full fidelity. After analysis, hand-edited records can be re-inserted into a processing pipeline as needed to support debugging and prototyping.</p><p>Text-only formats are more expensive to parse, which is why Ion offers the option of the length-prefixed binary format. This binary format supports rapid skip-scanning of data to materialize only key values within Ion streams.</p><h4 id="Seamless.transcoding">Seamless transcoding<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Seamless.transcoding">#</a>
  77 </h4><p>Ion’s interoperable formats avoid the kinds of semantic mismatches encountered when attempting to mix and match separate text and binary formats.</p><p>Standalone binary formats such as <a href="http://cbor.io/">CBOR</a> sacrifice human-readability in favor of an encoding that is more compact and efficient to parse. Although CBOR is based on JSON, transcoding between the two is not always straightforward because CBOR’s more expressive types do not necessarily map cleanly to JSON types. For example, CBOR’s <code>bignum</code> must be base-64 encoded and represented as a JSON <code>string</code> in order to avoid numeric overflow when read by a JSON parser, while a CBOR <code>map</code> may be directly converted to a JSON <code>object</code> only if all its keys are UTF-8 strings.</p><h3 id="Rich.type.system">Rich type system<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Rich.type.system">#</a>
  78 </h3><p>Ion’s type system is a superset of JSON’s: in addition to strings, booleans, arrays (lists), objects (structs), and nulls, Ion adds support for arbitrary-precision timestamps, embedded binary values (blobs and clobs), and symbolic expressions. Ion also expands JSON’s <code>number</code> specification by defining distinct types for arbitrary-size integers, IEEE-754 binary floating point numbers, and infinite-precision decimals. Decimals are particularly useful for precision-sensitive applications such as financial transaction record-keeping. JSON’s <code>number</code> type is underspecified; in practice, many implementations represent all JSON numbers as fixed-precision base-2 floats, which are subject to rounding errors and other loss of precision.</p><h4 id="Timestamps">Timestamps<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Timestamps">#</a>
  79 </h4><p>Ion <a href="ion/:%20Tutorial/:4.%20Special%20Datatypes#Timestamps">timestamps</a> are W3C-compliant representations of calendar dates and time, supporting variable precision including year, month, day, hours, minutes, seconds, and fractional seconds. Ion timestamps may optionally encode a time zone offset.</p><p>By defining timestamps as a distinct type, Ion eliminated the ambiguity involved with representing dates as strings, as the semantics are clearly defined. Unlike a number, which counts from some “epoch”, arbitrary precision timestamps also allow applications to represent deliberate ambiguity.</p><h4 id="Blobs.and.Clobs">Blobs and Clobs<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Blobs.and.Clobs">#</a>
  80 </h4><p>Ion’s <a href="ion/:%20Tutorial/:4.%20Special%20Datatypes#BLob"><code>blob</code></a> and <a href="ion/:%20Tutorial/:4.%20Special%20Datatypes#CLob"><code>clob</code></a> types allow applications to tunnel binary data through Ion. This allows such applications to transmit opaque binary payloads (e.g. media, code, and non-UTF-8 text) in Ion without the need to apply additional processing to the payloads to make them conform to a different Ion type.</p><p>For example, a <code>blob</code> could be used to transmit a bitmap image, while a <code>clob</code> could be used to transmit Shift JIS text or an XML payload.</p><h4 id="Symbolic.expressions">Symbolic expressions<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Symbolic.expressions">#</a>
  81 </h4><p>The Ion specification defines a distinct syntax for <a href="ion/:%20Tutorial/:4.%20Special%20Datatypes#S-Expressions">symbolic expression</a>s (<em>S-expressions</em>), but does not define how they should be processed. This allows applications to use S-expressions to convey domain-specific semantics in a first-<em>class</em> Ion type.</p><p>Formats that lack S-expressions as a first-<em>class</em> type are often left to choose between two imperfect options: adding a pre-processor (e.g. <a href="http://jsonnet.org/">Jsonnet</a> on top of JSON) to work around the inability to represent expressions as data, or tunneling domain-specific language text as opaque strings or binary payloads.</p><h4 id="Annotations">Annotations<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Annotations">#</a>
  82 </h4><p>The Ion specification provides a formal mechanism for applications to annotate any Ion value without the need to enclose the value in a container. These <em>annotations</em> are not interpreted by Ion readers and may be used, for example, to add type information to a <code>struct</code>, time units to an <code><a href="https://php.net/manual/en/language.types.integer">integer</a></code> or decimal value, or a description of the contents of a blob value.</p><h3 id="Self-describing">Self-describing<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Self-describing">#</a>
  83 </h3><p>Like JSON and CBOR, Ion is a <em>self</em>-describing format, meaning that it does not require external metadata (i.e. a schema) in order to interpret the structural characteristics of data denoted by the format. Notably, Ion payloads are free from build-time binding that inhibits independent innovation and evolution across service boundaries. This provides greater flexibility over schema-based formats such as <a href="https://developers.google.com/protocol-buffers/">protocol buffers</a>, <a href="http://thrift.apache.org/">Thrift</a>, and <a href="https://avro.apache.org/">Avro</a>, as data may be sparsely encoded and the implicit schema may be changed without explicit renegotiation of the schema among all consumers. These benefits come at the cost of a less compact encoding, but in our experience the positive impact on agility has been more valuable than an efficient but brittle contract.</p><h3 id="Read-optimized.binary.format">Read-optimized binary format<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Read-optimized.binary.format">#</a>
  84 </h3><p>Ion’s binary format is optimized according to the following principles:</p><ul>
  85 <li>Most data is read far more often than it is written. Generally, with the exception of logs, any data which is written is read at least once. Read multipliers are common in processing pipelines, workflows, and shared data marts.</li>
  86 <li>Many reads are shallow or sparse, meaning that the application is focused on only a subset of the values in the stream, and that it can quickly determine if full materialization of a value is required.</li>
  87 </ul><p>In the spirit of these principles, the Ion specification includes features that make Ion’s binary encoding more efficient to read than other schema-free formats. These features include length-prefixing of binary values and Ion’s use of symbol tables.</p><h4 id="Length-prefixing">Length-prefixing<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Length-prefixing">#</a>
  88 </h4><p>Because most reads are sparse, binary Ion invests some encoding space to length-prefix each value in a stream. This makes seeking to the next relevant value for a particular application inexpensive, and enables efficient skip-scanning of data. This allows applications to cherry-pick only the relevant values from the stream for deeper parsing, and to economize parsing of irrelevant values.</p><h4 id="Symbol.tables">Symbol tables<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Symbol.tables">#</a>
  89 </h4><p>In binary Ion, common text tokens such as struct field names are automatically stored in a symbol table. This allows these tokens to be efficiently encoded as table offsets instead of repeated copies of the same text. As a further space optimization, symbol tables can be pre-shared between producer and consumer so that only the table name and version are included in the payload, eliminating the overhead involved with repeatedly defining the same symbols across multiple pieces of Ion data.</p><h2 id="Install">Install<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Install">#</a>
  90 </h2><p>You can get started installing ext-ion the usual ways:</p><h3 id="PECL">PECL<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#PECL">#</a>
  91 </h3><p><code>pecl install ion</code></p><h3 id="Trinity">Trinity<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Trinity">#</a>
  92 </h3><pre><code><span style="color: inherit" class="html">
  93 ./configure<br>make #-j$(nproc)<br>sudo make install #INSTALL=install<br></span>
  94 </code></pre><h3 id="PHARext">PHARext<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#PHARext">#</a>
  95 </h3><p>See <a href="https://pharext.org">https://pharext.org</a> and <a href="https://replicator.pharext.org/?ion">https://replicator.pharext.org/?ion</a></p><h4 id="Quick:">Quick:<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Quick:">#</a>
  96 </h4><pre><code><span style="color: inherit" class="html">
  97 curl -sSO https://replicator.pharext.org/phars/ion/ion-0.1.0.ext.phar<br>php ./ion-0.1.0.ext.phar --sudo --ini &lt;path/to/pecl.ini&gt;<br></span>
  98 </code></pre><h4 id="Verified:">Verified:<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Verified:">#</a>
  99 </h4><pre><code><span style="color: inherit" class="html">
 100 # download phar, signature and public key<br>curl -sSO https://replicator.pharext.org/replicator.pub<br>curl -sSO https://replicator.pharext.org/phars/ion/ion-0.1.0.ext.phar<br>curl -sSO https://replicator.pharext.org/sigs/ion/ion-0.1.0.ext.phar.sig<br><br># verify signature against public key<br>openssl dgst \<br>  -verify    replicator.pub \<br>  -signature ion-0.1.0.ext.phar.sig \<br>             ion-0.1.0.ext.phar<br><br># install verified extension<br>php ./ion-0.1.0.ext.phar --sudo --ini &lt;path/to/pecl.ini&gt;<br><br></span>
 101 </code></pre><h2 id="Check">Check<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Check">#</a>
 102 </h2><p><code>php -m | grep ^ion</code> should show: <code>ion</code>.</p><hr><h2 id="Next.up">Next up<a class="permalink" href="ion/:%20Tutorial/:1.%20Getting%20started#Next.up">#</a>
 103 </h2><ul>
 104 <li>
 105 <a href="ion/:%20Tutorial/:2.%20What%20is%20ion">What is ion?</a>
 106 </li>
 107 </ul>
 108                         <div class="comments">
 109                                                                                 <style>.giscus-frame {min-height: 16em;}</style>
 110         <script>
 111                 function giscus_load(button) {
 112                         let script = document.createElement("script");
 113                                                 script.setAttribute("data-repo", 'awesomized/ext-ion');
 114                                                 script.setAttribute("data-category", 'Comments on Docs');
 115                                                 script.setAttribute("data-repo-id", 'R_kgDOGfXEXw');
 116                                                 script.setAttribute("data-category-id", 'DIC_kwDOGfXEX84CBHuf');
 117                                                 script.setAttribute("data-mapping", 'og:title');
 118                                                 script.setAttribute("data-input-position", 'bottom');
 119                                                 script.setAttribute("data-reactions-enabled", false);
 120                                                 script.setAttribute("data-theme", 'light');
 121                                                 script.setAttribute("data-lang", 'en');
 122
 123                         script.src = "//giscus.app/client.js";
 124                         button.parentNode.replaceChild(script, button);
 125                 }
 126         </script>
 127         <button class="activator" onclick="giscus_load(this)">Show Comments from Github Discussions</button>
 128
 129                         </div>
 130
 131                         <footer>
 132
 133 <ul>
 134         <li><a href="https://github.com/m6w6/mdref">mdref-v3.0
 135 </a></li>
 136         <li><a href="LICENSE">&copy; 2013-2022          All rights reserved.</a></li>
 137         <li>
 138 </li>
 139 </ul>
 140
 141                         </footer>
 142
 143                         <script src="index.js" defer></script>
 144
 145                 </div>
 146         </body>
 147 </html>