Skip to end of metadata
Go to start of metadata
You are viewing an old version of this page. View the current version. Compare with Current  |   View Page History

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

Zend Framework: Zend_Uri Component Proposal

Proposed Component Name Zend_Uri
Developer Notes
Proposers Shahar Evron
Zend Liaison TBD
Revision 0.1 - 26 July 2010: Initial Draft. (wiki revision: 3)

Table of Contents

1. Overview

Zend_Uri is the Zend Framework component responsible for representing URIs (Uniform Resource Identifiers) as objects.

In Zend Framework 1.x and before, Zend_Uri was mostly used for representation and validation of URIs of specific schemes, and the only scheme implemented was of HTTP URIs. In addition, Zend_Uri 1.0 was not capable of representing partial or relative URIs, and URIs of arbitrary schemes, and did not provide tools for resolving, encoding and normalizing URIs.

This proposal describes a set of changes and improvements (effectively a complete rewrite) to Zend_Uri for Zend Framework 2.0, that will address the deficiencies mentioned above.

2. References

3. Component Requirements, Constraints, and Acceptance Criteria

  • Zend\Uri will allow representation of generic URIs as objects
  • Zend\Uri will allow programmatic composition of URIs using getter/setter methods to various URI parts
  • Zend\Uri will allow creation of URI objects through string parsing
  • Zend\Uri will allow representation of partial and relative URIs
  • Zend\Uri will closely follow RFC-3986 definitions for URI syntax
  • Zend\Uri will always produce RFC-3986 compliant URIs when converting URI objects back to a string
  • Zend\Uri will attempt to be flexible when parsing string URIs and accept invalid URIs or URI parts if these can be encoded into a syntactically valid URI
  • Zend\Uri will provide subclasses for representation of scheme-specific URIs
  • Zend\Uri will allow users to easily create their own scheme-specific classes
  • Zend\Uri scheme subclasses may enforce additional validation rules on URIs
  • Zend\Uri scheme subclasses may provide additional protocol or scheme specific APIs
  • Zend\Uri will allow automatic string-to-object conversion using the factory pattern
  • Zend\Uri will provide API for resolving relative URIs
  • Zend\Uri will provide API for normalizing URI strings
  • Zend\Uri will provide API for converting absolute URIs into relative URIs based on a shared absolute base URI
  • Zend\Uri will provide generic methods for validating and encoding different URI parts
  • Zend\Uri will not provide an interface for strict validation or encoding of URI strings.
    • These operations should be provided by Zend\Validate and Zend\Filter classes that may internally rely on Zend\Uri encoding and validation methods.

4. Dependencies on Other Framework Components

  • Zend\Validate\Hostname
  • Zend\Validate\Ip
  • Zend\Exception

5. Theory of Operation


The Zend\Uri component will provide a concrete class (Zend\Uri\Uri) implementing RFC-3986 compatible Generic URI Syntax parsing, composition, resolution, validation encoding and normalization of URIs. This class will be concrete and could be used to represent any comliant URI, including scheme specific URIs and partial or relative URIs.

In addition, Zend\Uri will provide a set of subclasses of Zend\Uri\Uri (initially Zend\Uri\Http, Zend\Uri\File, Zend\Uri\Mailto) that will only be capable of representing URIs of specific schemes, and will enforce additional validation rules in addition to those defined by the Generic Syntax RFC. These subclasses may still be able to represent partial or relative URIs, as long as they comply with any rules imposed by the scheme.

Parsing and Recomposition

URI parsing and composition will be done following the parsing and composition rules defined in the RFC. The aim is to be relatively lax when parsing string URIs and setting different URI parts using accessor methods, and accept input as long as it can eventually be encoded into a valid URI when the object is converted back to a string.

For example, the URI

will be accepted by the parser despite the fact that it's path component (C:/Program Files/Zend) contains an invalid space character. When the URI is composed back into a string and is normalized, it will be represented as
, which is a valid and RFC-compliant URI.

Zend\Uri will refuse to parse a string or accept a part set through one of the mutator methods only if the input can never be unambigously converted into a valid URI part.

For example, the following will not be allowed:

Since the scheme of a URI may never contain spaces and the URI syntax rules do not define a mean to represent a space character in the scheme part.

In contrast, the following will be allowed:

Since although the '#' sign may not be used literally in the query part of a URI, it can be encoded as '%23' when the URI is composed.

Relative URI Resolution
Automatic Scheme-specific Class Selection

6. Milestones / Tasks

Describe some intermediate state of this component in terms of design notes, additional material added to this page, and / code. Note any significant dependencies here, such as, "Milestone #3 can not be completed until feature Foo has been added to ZF component XYZ." Milestones will be required for acceptance of future proposals. They are not hard, and many times you will only need to think of the first three below.

  • Milestone 1: design notes will be published here
  • Milestone 2: Working prototype checked into the incubator supporting use cases #1, #2, ...
  • Milestone 3: Working prototype checked into the incubator supporting use cases #3 and #4.
  • Milestone 4: Unit tests exist, work, and are checked into SVN.
  • Milestone 5: Initial documentation exists.

If a milestone is already done, begin the description with "[DONE]", like this:

  • Milestone #: [DONE] Unit tests ...

7. Class Index

  • Zend_Magic_Exception
  • Zend_Magic (factory class)
  • Zend_Magic_MindProbe
  • Zend_Magic_MindProbe_Intent
  • Zend_Magic_Action
  • Zend_Magic_CodeGen

8. Use Cases


... (see good use cases book)

9. Class Skeletons


Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.