Skip to end of metadata
Go to start of metadata

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

<ac:macro ac:name="unmigrated-inline-wiki-markup"><ac:plain-text-body><![CDATA[

Zend Framework: Zend_Yaml Component Proposal

Proposed Component Name Zend_Yaml
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Yaml
Proposers Pádraic Brady
Revision 0.10 - 26 March 2007 (wiki revision: 6)

Table of Contents

1. Overview

YAML is a machine parsable data serialisation format for storing text, numerical data, arrays and more. It was designed for use with programming languages and has excellent support in Python, Perl and Ruby. Several C implementations exist and at least one (Syck) supports a PHP extension. YAML is a commonly used format for data files as an alternative to XML or INI.

Zend_Yaml aims to implement YAML 1.1 support for the Zend Framework. In the absence of a core YAML extension for PHP, it offers YAML support in native PHP. This will include an LL(1) parser and lexer for the YAML format which drives the majority of functionality. The lexer will deconstruct a YAML string/file into parsable tokens which will allow the deserialisation of YAML data into native PHP types and vice versa. As noted in the comments, JSON is a near compatible subset of YAML however this proposal does not currently intend supporting JSON as this already has excellent support via Zend_Json and ext/json.

It is expected to support almost all of the YAML grammer, with the notable exclusion of Unicode support. This will be omitted from initial versions but will be implemented once the requirements for Unicode support (given PHP's lack of) is more thoroughly assessed. In addition, Zend_Yaml would defer to any YAML C extension support if detected. It is currently unknown whether a PHP implementation would have 100% interoperability with such an extension though differences would be relatively minor (if not negligible).

The interface to Zend_Yaml will be deliberately simple supporting the deserialisation of YAML from either a file resource or a native string. Also supporting will be the serialisation of PHP native types into the YAML format. The default return value will be in the form of an array. Similar to Zend_Json, an option to decode YAML into stdClasses will also be offered for consistency.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • Zend_Yaml must implement the YAML 1.1 specification (excluding Unicode support until a later version).
  • Zend_Yaml must support both string literal and file based loading.
  • Zend_Yaml must be capable of parsing all non-Unicode examples in the YAML 1.1 specification.
  • Zend_Yaml should be interoperable with the reference implementations for Python, Ruby and Perl.
  • Zend_Yaml may not be fully interoperable with the Syck C library or libyaml. Differences (if any) will be kept in line with other YAML parsers implemented in interpreted programming languages.

4. Dependencies on Other Framework Components

Zend_Yaml will have few dependencies on other Zend Framework classes. The only one currently noted is of course the base Exception class.

  • Zend_Exception

5. Theory of Operation

Instantiate Zend_Yaml object, pass in a string or file resource representing a YAML stream, call the decode method to deserialise the YAML into a PHP array of values. If a YAML C extension is detected this may be used to offer a performance boost.

6. Milestones / Tasks

  • Milestone 1: Implement basic YAML loading without Unicode support
  • Milestone 2: Unit Tests and class refactoring
  • Milestone 3: Debugging and Use Case testing
  • Milestone 4: Verification of all non-Unicode specification examples being parsable by Zend_Yaml
  • Milestone 5: Documentation
  • Milestone 6: Add Unicode support

7. Class Index

  • Zend_Yaml
  • Zend_Yaml_Lexer
  • Zend_Yaml_Parser
  • Zend_Yaml_Token
  • Zend_Yaml_SimpleKey
  • Zend_Yaml_Buffer
  • Zend_Yaml_Mark
  • Zend_Yaml_Exception

This is not an exhaustive list. Also included will be subclasses of Zend_Yaml_Token representing all valid lexical tokens.

8. Use Cases

UC-01

Load a YAML string directly.

A string parameter can of course come from file_get_contents(), however file streaming using fopen() and fread() is also useable.

UC-02

Load a YAML file streamed from an fopen() resource.

9. Class Skeletons

Adding class skeletons will occur some time in the near future. You can check the current code from the subversion address in the reference list to see what the classes currently look like if required.

]]></ac:plain-text-body></ac:macro>

]]></ac:plain-text-body></ac:macro>

Labels:
None
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.
  1. Mar 22, 2007

    <p>Is there a benefit to somehow combining the this with Zend_Json, since the two only differ in a very minor way (a ' ' required after ':' and ',' in YAML)?</p>

    1. Mar 22, 2007

      <p>I meant to say, since JSON is a subset of YAML, differing only in a very minor way.</p>

      1. Mar 22, 2007

        <p>I don't think there's a benefit really. JSON (with tweaks) is valid YAML, but the needs of a JSON parser are a lot simpler since it's a limited subset. YAML , esp. 1.1, is more complex and it's PHP parser would be a lot longer and likely slower - add in Unicode support, and full grammer support and it will be a monstrosity <ac:emoticon ac:name="wink" />. Integrating the two would only degrade the framework's JSON support from a performance perspective I believe. Since JSON is by far the more popular format as it's a powerful AJAX data form, I think it's better off in it's smaller faster package.</p>

        <p>Obviously my opinion is pure speculation based on the estimated class size and method count of the YAML classes being a key performance factor. I could be completely wrong and it might parse JSON just as efficiently as Zend_Json. If it does it might be interesting to keep Zend_Yaml JSON compatible (PHP quirks included, assuming ext/json retains them and Zend_Json adopts them) as an option though I suspect users would prefer the more specific naming of Zend_Json, and the leaner package it forms.</p>

      2. May 13, 2007

        <p>I don't see the benefit either.</p>

        <p>Even though related, they are both used independently.</p>

        <p>I'd also love to see this in ZF.</p>

  2. Apr 05, 2007

    <p>Great proposal. I would it in the Zend Framework!</p>

  3. Jul 13, 2007

    <p>Now that the Syck Yaml parser extension is in PECL (although in beta) and can both read and write YAML, I suggest Zend_Yaml will be implemented in a similar manner to Zend_Json: with a user-space implementation that is used only if the Syck extension is not loaded.</p>

    <p>This can have a tremendous positive effect on performance in places where the native implementation can be used.</p>

  4. Sep 14, 2007

    <p>Why we need new Zend_Yaml and then $yaml->decode and not just Zend_Yaml::decode? It there some state stored in the object? </p>

  5. Feb 04, 2008

    <p>In an effort to streamline what I'm proposing for the ZF, I'm deleting this proposal. From emails I've either directly received, been quietly informed of, or had to read on a public mailing list, it's either been reviewed by the Zend team since November, or it's not been reviewed yet. Unless Zend Technologies have time travel, one is wrong and without clarification I'm going to assume the November review was correct.</p>

    <p>In any case, the initial review in November which I received (I can forward to the curious) was fairly clear. I was told there were issues raised concerning performance and the lack of YAML 1.1 compliance in ext/syck by the Zend team and on that basis the proposal should wait for another extension (perhaps for libyaml currently in early development) or ext/syck to reach YAML 1.1 which may not happen. I counter proposed a lighter parser since a full parser was effectively not worth my effort with ext/syck in circulation on PECL but received no response then or since. If at some point the counter-proposal is replied to I'm happy to reinstate the Zend_Yaml proposal for implementation. Since libyaml is in early development, a new PHP extension is unlikely in the near term.</p>

    <p>So from my perspective, the proposal has been effectively turned down for the moment. This doesn't seem to be known by many people and there's continual queries as to to its status and whether I'm somehow holding it up. Deleting the proposal at a minimum leaves some room for other proposals which require Yaml, but are being informed they should wait for Zend_Yaml (which since it's been disapproved doesn't make much sense). The latest of these just deleted was Zend_Translate_Yaml by Thomas.</p>

  6. Apr 04, 2009

    <p>Greetings All,</p>

    <p>Alternatively, I've created an implementation of Zend_Config_Yml that might suffice for your needs. Care to take a look?</p>

    <p><a class="external-link" href="http://www.emanaton.com/code/php/zendconfigyml">http://www.emanaton.com/code/php/zendconfigyml</a></p>

    <p>Regards,</p>

    <p>Sean P. O. MacCath-Moran<br />
    www.emanaton.com</p>