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_Json_Jsonable Component Proposal

Proposed Component Name Zend_Json_Jsonable
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Json_Jsonable
Proposers Jurriën Stutterheim
Zend Liaison Matthew Weier O'Phinney
Revision 1.0 - 21 August 2008: Initial Draft. (wiki revision: 10)

Table of Contents

1. Overview

Zend_Json_Jsonable is a simple interface that provides a toJson method. This allows for a more fine-grained control over how objects serialize to JSON.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • This component will provide an interface that allows more control over serializing objects to JSON
  • This component will be supported by Zend_Json's encode facilities
  • This component will not be supported by PHP's native json_encode() function (yet ).

4. Dependencies on Other Framework Components

  • Zend_Json

5. Theory of Operation

Currently object support for JSON encoding is very limited – only public attributes can be serialized. The Zend_Json_Jsonable is designed to work around this limitation. The __toJson() method that's provided with this interface can be used by Zend_Json's encode methods to retrieve a custom set of data from the object.

A question for this proposal

  • Should the __toJson() method be prefixed with __?

6. Milestones / Tasks

  • Milestone 1: [DONE] Initial proposal
  • Milestone 2: Receive and process comments
  • Milestone 3: Component is incubated
  • Milestone 4: Zend_Json is updated to support this interface
  • Milestone 5: Documentation is available.
  • Milestone 6: Component is included in the core.

7. Class Index

  • Zend_Json_Jsonable

8. Use Cases

UC-01: Zend_Paginator and ContextSwitch

9. Class Skeletons

]]></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. Sep 04, 2008

    <p>Jurrien – we're thinking two different interfaces at this point: Zend_Json_JsonSerializable and Zend_Json_JsonConfigurable. These would expose toJson() and fromJson(), respectively. This better qualifies what each does.</p>

    1. Sep 23, 2008

      <p>I have no objections against adding an interface for fromJson(). Not sure about the naming sugestions (they're pretty long), but I can't really think of much better alternatives (keeping namespaces in mind).</p>

  2. Sep 24, 2008

    <p>i have objections against the naming and/or functionality. toJson() returns an array and will be processed in Zend_Json::encode only. calling $object->toJson() will not return json. this is weird from a programmers perspective.</p>

    <p>Of course its nice to have a marker for Zend_Json::encode to know which objects it can serialize and which it cannot, but why go common serialization the PHP way of doing it with __sleep()?</p>

    <p>In my opinion you have a function toJson() and it uses Zend_Json::encode to return real json, or you have a function toArray() and a specific interface Zend_Array_Serializable and Zend_Json checks for this interface and uses the returning array to convert it to json.</p>

    <p>For example: Zend_Config already has toArray() why not refactor the whole thing into a general interface have Zend_Config implement it. Add another interface with toJson() have Zend_Config implement it. Move both functions toArray() and toJson() into an abstract class Zend_Config_Abstract that has toArray() and toJson(), with toJson() calling Zend_Json::encode($this->toArray()). Then this could be a best practice implementation. </p>

    <p>Additionally: Change Zend_Json to check for the toArray() interface and convert it, and check for the toJson() interface and just return the output of this function (since it sbould already be jsoned).</p>

    1. Oct 14, 2008

      <p>Um... toJson() <strong>will</strong> return JSON; where did you get the idea otherwise?</p>

      <p>Regarding using toJson() over __sleep(): an object may need to be serializable in a number of ways: to an array, to JSON, to XML, etc; using __sleep() would negate the ability to use multiple serialization formats.</p>

      <p>I think your last idea of using the toArray() interface is a good one.</p>

  3. Oct 20, 2008

    <ac:macro ac:name="note"><ac:parameter ac:name="title">Zend Rejection</ac:parameter><ac:rich-text-body>
    <p>The Zend team is rejecting this proposal at this time.</p>

    <p>Our primary concern is how a class can define serialization in different formats. In the past, we've had asXml, renderXml, asXML, toXML, and the now standard toXml as methods all performing the same functionality. The proposal as stated would have defined an interface to which a class could subscribe. </p>

    <p>Interfaces have their place. However, with serialization, a particular object may need to subscribe to multiple interfaces, leading to unwieldy class definitions. Additionally, there is some debate as to whether it's the role of the object or the consumer to serialize; there are cases where the object may need to export a subset of data, and other cases where the consumer just needs to serialize the object any way it can.</p>

    <p>We have decided that duck typing makes most sense for these operations. This allows the consumer to introspect the object's capabilities if desired, and decide how serialization should proceed. This prevents cumbersome class declarations; it's also closer to the "PHP way". However, we feel we need to standardize the format of how de/serialization methods should be named so that there is consistency within the framework; these standards should be captured in the ZF coding standards document.</p>

    <p>As it stands, the current conventions are:</p>

    <ul>
    <li>to<format>(): serialize to the given format. Examples: toJson(), toXml(), toArray()</li>
    <li>from<format>(): deserialize or load object state from the given format. Examples: fromXml(), fromJson(), fromArray()</li>
    </ul>

    <p>Additionally, for standard serialization, PHP already defines two magic methods:</p>

    <ul>
    <li>__sleep(): used to serialize the object when passed to serialize(); should return false if not serializeable, or an array to serialize.</li>
    <li>__toString(): for basic string representation; should always return a string</li>
    </ul>

    <p>If a consumer class wants to see if a class adheres to these conventions, we recommend simply using method_exists(). If a failure is expected if the method does not exist, you may simply call the method and depend on PHP's error handling mechanism to throw an E_FATAL when the method is not found, or explicitly check for the method using method_exists() and throw an exception when missing (or skip processing, if desired).</p>

    <p>We invite the author to assist in updating the coding standards to reflect this direction.</p></ac:rich-text-body></ac:macro>