YAML Data Serialization

Table of Contents

Introduction

This extension implements the » YAML Ain't Markup Language (YAML) data serialization standard. Parsing and emiting are handled by the » LibYAML library.

Installing/Configuring

Table of Contents

Requirements

This extension requires the » LibYAML C library version 0.1.0 or higher to be installed.

Installation

This » PECL extension is not bundled with PHP.

Information for installing this PECL extension may be found in the manual chapter titled Installation of PECL extensions. Additional information such as new releases, downloads, source files, maintainer information, and a CHANGELOG, can be located here: » http://code.google.com/p/php-yaml/.

A DLL for this PECL extension is currently unavailable. See also the building on Windows section.

Runtime Configuration

The behaviour of these functions is affected by settings in php.ini.

Yaml Configure Options
Name Default Changeable Changelog
yaml.decode_binary 0 PHP_INI_ALL
yaml.decode_timestamp 0 php_ini_all
yaml.output_canonical 0 php_ini_all
yaml.output_indent 2 php_ini_all
yaml.output_width 80 php_ini_all

Here's a short explanation of the configuration directives.

yaml.decode_binary boolean

Off by default, but can be set to on to cause base64 binary encoded entities which have the explicit tag "tag:yaml.org,2002:binary" to be decoded.

yaml.decode_timestamp integer

Controls the decoding of both implicit and explict "tag:yaml.org,2002:timestamp" scalars in the YAML document stream. The default setting of 0 will not apply any decoding. A setting of 1 will use strtotime to parse the timestamp value as a Unix timestamp. A setting of 2 will use date_create to parse the timestamp value as DateTime object.

yaml.output_canonical boolean

Off by default, but can be set to on to cause canonical form output.

yaml.output_indent integer

Number of spaces to indent sections. Value should be between 1 and 10.

yaml.output_width integer

Set the preferred line width. -1 means unlimited.

Resource Types

Predefined Constants

The constants below are defined by this extension, and will only be available when the extension has either been compiled into PHP or dynamically loaded at runtime.

Scalar entity styles usable by yaml_parse callback methods.
YAML_ANY_SCALAR_STYLE ( integer )
YAML_PLAIN_SCALAR_STYLE ( integer )
YAML_SINGLE_QUOTED_SCALAR_STYLE ( integer )
YAML_DOUBLE_QUOTED_SCALAR_STYLE ( integer )
YAML_LITERAL_SCALAR_STYLE ( integer )
YAML_FOLDED_SCALAR_STYLE ( integer )
Common tags usable by yaml_parse callback methods.
YAML_NULL_TAG ( string )
"tag:yaml.org,2002:null"
YAML_BOOL_TAG ( string )
"tag:yaml.org,2002:bool"
YAML_STR_TAG ( string )
"tag:yaml.org,2002:str"
YAML_INT_TAG ( string )
"tag:yaml.org,2002:int"
YAML_FLOAT_TAG ( string )
"tag:yaml.org,2002:float"
YAML_TIMESTAMP_TAG ( string )
"tag:yaml.org,2002:timestamp"
YAML_SEQ_TAG ( string )
"tag:yaml.org,2002:seq"
YAML_MAP_TAG ( string )
"tag:yaml.org,2002:map"
YAML_PHP_TAG ( string )
"!php/object"
Encoding types for yaml_emit
YAML_ANY_ENCODING ( integer )
Let the emitter choose an encoding.
YAML_UTF8_ENCODING ( integer )
Encode as UTF8.
YAML_UTF16LE_ENCODING ( integer )
Encode as UTF16LE.
YAML_UTF16BE_ENCODING ( integer )
Encode as UTF16BE.
Linebreak types for yaml_emit
YAML_ANY_BREAK ( integer )
Let emitter choose linebreak character.
YAML_CR_BREAK ( integer )
Use \r as break character (Mac style).
YAML_LN_BREAK ( integer )
Use \n as break character (Unix style).
YAML_CRLN_BREAK ( integer )
Use \r\n as break character (DOS style).

Examples

Example #1 Yaml Example

<?php
$addr = array(
    "given" => "Chris",
    "family"=> "Dumars",
    "address"=> array(
        "lines"=> "458 Walkman Dr.
        Suite #292",
        "city"=> "Royal Oak",
        "state"=> "MI",
        "postal"=> 48046,
      ),
  );
$invoice = array (
    "invoice"=> 34843,
    "date"=> "2001-01-23",
    "bill-to"=> $addr,
    "ship-to"=> $addr,
    "product"=> array(
        array(
            "sku"=> "BL394D",
            "quantity"=> 4,
            "description"=> "Basketball",
            "price"=> 450,
          ),
        array(
            "sku"=> "BL4438H",
            "quantity"=> 1,
            "description"=> "Super Hoop",
            "price"=> 2392,
          ),
      ),
    "tax"=> 251.42,
    "total"=> 4443.52,
    "comments"=> "Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.",
    );

// generate a YAML representation of the invoice
$yaml = yaml_emit($invoice);
var_dump($yaml);

// convert the YAML back into a PHP variable
$parsed = yaml_parse($yaml);

// check that roundtrip conversion produced an equivalent structure
var_dump($parsed == $invoice);
?>

The above example will output something similar to:

string(631) "---
invoice: 34843
date: "2001-01-23"
bill-to:
  given: Chris
  family: Dumars
  address:
    lines: |-
      458 Walkman Dr.
              Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
ship-to:
  given: Chris
  family: Dumars
  address:
    lines: |-
      458 Walkman Dr.
              Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
product:
- sku: BL394D
  quantity: 4
  description: Basketball
  price: 450
- sku: BL4438H
  quantity: 1
  description: Super Hoop
  price: 2392
tax: 251.420000
total: 4443.520000
comments: Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.
...
"
bool(true)

Yaml Functions

yaml_emit_file

Send the YAML representation of a value to a file

Description

bool yaml_emit_file ( string $filename , mixed $data [, int $encoding = YAML_ANY_ENCODING [, int $linebreak = YAML_ANY_BREAK ]] )

Generate a YAML representation of the provided data in the filename .

Parameters

filename

Path to the file.

data

The data being encoded. Can be any type except a resource .

encoding

Output character encoding chosen from YAML_ANY_ENCODING, YAML_UTF8_ENCODING, YAML_UTF16LE_ENCODING, YAML_UTF16BE_ENCODING. Defaults to YAML_ANY_ENCODING.

linebreak

Output linebreak style chosen from YAML_ANY_BREAK, YAML_CR_BREAK, YAML_LN_BREAK, YAML_CRLN_BREAK. Defaults to YAML_ANY_BREAK.

Return Values

Returns TRUE on success.

See Also

  • yaml_emit
  • yaml_parse

yaml_emit

Returns the YAML representation of a value

Description

string yaml_emit ( mixed $data [, int $encoding = YAML_ANY_ENCODING [, int $linebreak = YAML_ANY_BREAK ]] )

Generate a YAML representation of the provided data .

Parameters

data

The data being encoded. Can be any type except a resource .

encoding

Output character encoding chosen from YAML_ANY_ENCODING, YAML_UTF8_ENCODING, YAML_UTF16LE_ENCODING, YAML_UTF16BE_ENCODING. Defaults to YAML_ANY_ENCODING.

linebreak

Output linebreak style chosen from YAML_ANY_BREAK, YAML_CR_BREAK, YAML_LN_BREAK, YAML_CRLN_BREAK. Defaults to YAML_ANY_BREAK.

Return Values

Returns a YAML encoded string on success.

Examples

Example #1 yaml_emit example

<?php

     /* ... */

     ?>

The above example will output something similar to:

     ...

See Also

  • yaml_emit_file
  • yaml_parse

yaml_parse_file

Parse a YAML stream from a file

Description

mixed yaml_parse_file ( string $filename [, int $pos = 0 [, int &$ndocs [, array $callbacks ]]] )

Convert all or part of a YAML document stream read from a file to a PHP variable.

Parameters

filename

Path to the file.

pos

Document to extract from stream (-1 for all documents, 0 for first document, ...).

ndocs

If ndocs is provided, then it is filled with the number of documents found in stream.

callbacks

Content handlers for YAML nodes. Associative array of YAML tag => callback mappings.

Return Values

Returns the value encoded in input in appropriate PHP type. NULL is returned if the input cannot be decoded. If pos is -1 an array will be returned with one entry for each document found in the stream.

See Also

  • yaml_parse
  • yaml_parse_url
  • yaml_emit

yaml_parse_url

Parse a Yaml stream from a URL

Description

mixed yaml_parse_url ( string $url [, int $pos = 0 [, int &$ndocs [, array $callbacks ]]] )

Convert all or part of a YAML document stream read from a URL to a PHP variable.

Parameters

url

url should be of the form "scheme://...". PHP will search for a protocol handler (also known as a wrapper) for that scheme. If no wrappers for that protocol are registered, PHP will emit a notice to help you track potential problems in your script and then continue as though filename specifies a regular file.

pos

Document to extract from stream (-1 for all documents, 0 for first document, ...).

ndocs

If ndocs is provided, then it is filled with the number of documents found in stream.

callbacks

Content handlers for YAML nodes. Associative array of YAML tag => callback mappings.

Return Values

Returns the value encoded in input in appropriate PHP type. NULL is returned if the input cannot be decoded. If pos is -1 an array will be returned with one entry for each document found in the stream.

See Also

  • yaml_parse
  • yaml_parse_file
  • yaml_emit

yaml_parse

Parse a YAML stream

Description

mixed yaml_parse ( string $input [, int $pos = 0 [, int &$ndocs [, array $callbacks ]]] )

Convert all or part of a YAML document stream to a PHP variable.

Parameters

input

The string to parse as a YAML document stream.

pos

Document to extract from stream (-1 for all documents, 0 for first document, ...).

ndocs

If ndocs is provided, then it is filled with the number of documents found in stream.

callbacks

Content handlers for YAML nodes. Associative array of YAML tag => callback mappings.

Return Values

Returns the value encoded in input in appropriate PHP type. NULL is returned if the input cannot be decoded. If pos is -1 an array will be returned with one entry for each document found in the stream.

Examples

Example #1 yaml_parse example

<?php
$yaml = <<<EOD
---
invoice: 34843
date: "2001-01-23"
bill-to: &id001
  given: Chris
  family: Dumars
  address:
    lines: |-
      458 Walkman Dr.
              Suite #292
    city: Royal Oak
    state: MI
    postal: 48046
ship-to: *id001
product:
- sku: BL394D
  quantity: 4
  description: Basketball
  price: 450
- sku: BL4438H
  quantity: 1
  description: Super Hoop
  price: 2392
tax: 251.420000
total: 4443.520000
comments: Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338.
...
EOD;

$parsed = yaml_parse($yaml);
var_dump($parsed);
?>

The above example will output something similar to:

array(8) {
  ["invoice"]=>
  int(34843)
  ["date"]=>
  string(10) "2001-01-23"
  ["bill-to"]=>
  &array(3) {
    ["given"]=>
    string(5) "Chris"
    ["family"]=>
    string(6) "Dumars"
    ["address"]=>
    array(4) {
      ["lines"]=>
      string(34) "458 Walkman Dr.
        Suite #292"
      ["city"]=>
      string(9) "Royal Oak"
      ["state"]=>
      string(2) "MI"
      ["postal"]=>
      int(48046)
    }
  }
  ["ship-to"]=>
  &array(3) {
    ["given"]=>
    string(5) "Chris"
    ["family"]=>
    string(6) "Dumars"
    ["address"]=>
    array(4) {
      ["lines"]=>
      string(34) "458 Walkman Dr.
        Suite #292"
      ["city"]=>
      string(9) "Royal Oak"
      ["state"]=>
      string(2) "MI"
      ["postal"]=>
      int(48046)
    }
  }
  ["product"]=>
  array(2) {
    [0]=>
    array(4) {
      ["sku"]=>
      string(6) "BL394D"
      ["quantity"]=>
      int(4)
      ["description"]=>
      string(10) "Basketball"
      ["price"]=>
      int(450)
    }
    [1]=>
    array(4) {
      ["sku"]=>
      string(7) "BL4438H"
      ["quantity"]=>
      int(1)
      ["description"]=>
      string(10) "Super Hoop"
      ["price"]=>
      int(2392)
    }
  }
  ["tax"]=>
  float(251.42)
  ["total"]=>
  float(4443.52)
  ["comments"]=>
  string(68) "Late afternoon is best. Backup contact is Nancy Billsmer @ 338-4338."
}

See Also

  • yaml_parse_file
  • yaml_parse_url
  • yaml_emit

Table of Contents