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

Proposed Component Name Zend_Db_Gateway
Developer Notes http://framework.zend.com/wiki/display/ZFDEV/Zend_Db_Gateway
Proposers My E-mail Address
Revision 1.1 - 22 January 2008: Proposal created. (wiki revision: 11)

Table of Contents

1. Overview

Zend_Db_Gateway is an interface abstraction for creating Zend_Db_Table oriented queries.

2. References

  • Zend_Db_Select
  • Zend_Db_Table

3. Component Requirements, Constraints, and Acceptance Criteria

Current Zend_Db_Table implementation provides a limited interface for database data retrieval. In most real world scenarios, queries often require several tables to be joined, as related data is split for normalization's sake, and also for specific columns to be retrieved (creating 'views'). This component provides an interface to creating complicated queries - reducing the overhead of writing them by hand, relies on Zend_Db_Table reference maps to define table relationships and abstracts explicit table names.

  • This component will provide an interface for query composition.
  • This component will allow the creation of 'views' (partial column retrieval).
  • This component will abstract table names so they shall not be declared explicitly.
  • This component will use Zend_Db_Table reference maps for defining table relationships.
  • This component will not be coupled to Zend_Db_Table, despite borrowing design features from it.
  • This component will use Zend_Db_Select as a lower-level query composition tool.

4. Dependencies on Other Framework Components

  • Zend_Db_Select
  • Zend_Db_Adapter_Abstract

5. Theory of Operation

The class provides a base interface for composing cross table queries (joins) that is intended to be abstracted further into meaningful method names by extending classes. The extending methods can than be used be reused to create different query composition combinations.

When instantiated, this component is provided with a instance of Zend_Db_Adapter, a table name for which this instance will act as gateway, and an optional reference map.

Class API methods share a single Zend_Db_Select object (class member), which can be reset (full/partial) on demand.

Query process begins with an initialization method or alternatively a Zend_Db_Select instance may be provided with pre-configured query options.

Table names are fetched from their corresponding table classes, and then cached for the lifetime of the object.

6. Milestones / Tasks

  • Milestone 1: [DONE] Submit proposal
  • Milestone 2: [DONE] Provide documented working prototype and use cases
  • Milestone 3: Re-design based on provided community feedback
  • Milestone 4: Provide unit tests.
  • Milestone 5: Proposal accepted into incubator.

7. Class Index

  • Zend_Db_Gateway

8. Use Cases

UC 01

Files is a file management class for a web application - it allows users to upload files, organize files by folders, share files to other users and to have a basic versioning mechanism.
Apart from the file itself, all relevant data is stored in the database in four distinct tables:

user_files: Contains file details, including hash, title, description and an ID of the uploading user (owner).

user_folders: Contains file folders details. File folders have names, a unique numeric ID and a parent ID for creating a tree-like hierarchy.

users_to_files: Provides many-to-many relationship between files and users.

user_file_versions: Is similar to user_files and contains different versions of specific files from user_files.

Building views from data retrieved from all four tables is done in the following manner:

First, extending the Gateway class and creating meaningful and reusable query composition methods:

Views can then be easily created from a Zend_Db_Table extending class: (easy compared to manual query composition)

9. Class Skeletons

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

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

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

10 Comments

comments.show.hide

  1. Jan 22, 2008

    Simon Mundy

    <p>Hi Eran</p>

    <p>This makes the idea much clearer to me, and I can see the really benefits. One thing that did come to mind was that perhaps rather than creating a whole new Gateway component another option could be building upon the existing Zend_Db_Table_Select object.</p>

    <p>For example, many of the 'order', 'with' and 'by' methods in your business models could just as easily reference data from within the Zend_Db_Table definitions, in a similar way to the existing structure. We could build upon those and make the table-specific select() object work a bit harder.</p>

    <p>E.g. Using your existing UC Table as a starting point:-</p>
    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    public function getShared($id = null)
    {
    $gateway = $this -> gateway();
    $gateway -> getAll() -> byUserShares() -> withVersions() -> orderByVersion();
    if($this -> isValidId($id))

    Unknown macro: { $gateway -> byUser($id); }


    return $gateway -> query();
    }
    ]]></ac:plain-text-body></ac:macro>

    <p>could be expressed as</p>

    <ac:macro ac:name="code"><ac:plain-text-body><![CDATA[
    // The class configuration data defines all behaviours/business rules
    protected $_orderRules = array(
    'Version' => array(array('created DESC', 'UserFileVersions'));
    );
    ...etc...

    public function getShared($id = null)
    {
    // This shows a magic method similar to existing Zend_Db_Row syntax
    // except rules can also be chained. So 'withUserSharesByVersions()'
    // expands to 'withUserShares()' and 'byVersions()'
    // which then resolve to 'withRule('UserShares')' and 'byRule('Versions')'
    // The order statement resolves to 'orderRule('Version')'
    $select = $this->select()
    ->withUserSharesByVersions()
    ->orderByVersion()
    if ($id !== null)

    Unknown macro: { $select->byUser($id); }

    return $this->fetchAll($select);
    }
    ]]></ac:plain-text-body></ac:macro>

    <p>I don't mean to run over your idea but I'd like to see if there's any opportunities to use existing and closely-matching code.</p>

    1. Jan 23, 2008

      Eran Galperin

      <p>Your approach is indeed similar to what is currently used by the Zend_Db_Table for table relationship management. I see no problem adding a magic method that can automatically inflect calls to the basic 'with' and 'by' methods, as the end result is the same after all. You can also see that the syntax is very similar to my fluent interface version - it is just a matter of personal preference.</p>

      <p>Personally, when writing code I rely much on the auto-complete feature of my IDE (Zend Studio) to expedite and automate code generation which can not be done with magical methods, forcing me to have the documentation at hand when using such methods as I have a pretty bad memory. Also, in the spirit of performance, I tend to rely less on magical methods when the benefit is not obvious.</p>

      <p>I see no problem offering both approaches and giving the developer options when choosing his implementation.</p>

  2. Jun 20, 2008

    Wil Sinclair

    <p>Eran, are you still actively driving this proposal?</p>

    <p>,Wil</p>

  3. Jun 20, 2008

    Eran Galperin

    <p>I might be if I knew that the proposals are again being considered. Since I submitted it half a year ago I made several changes based on accumulated experience, so I'd need to update the proposal to support it. Are you guys pushing proposals currently?</p>

    1. Jun 20, 2008

      Wil Sinclair

      <p>We have been reviewing them since the new proposal process was rolled out. Currently, our queue is empty (some of the proposals that have a recommendation haven't been updated by their Zend Liaisons yet). But to be clear, it is largely the author's responsibility to push the proposal; your liaison takes responsibility only after you've moved the document through 'Ready for Review' to 'Ready for Recommendation', where it is picked up by the Zend team. Please refer to this doc for a full rundown of the new proposal process: <a class="external-link" href="http://framework.zend.com/wiki/display/ZFPROP/Proposal+Process">http://framework.zend.com/wiki/display/ZFPROP/Proposal+Process</a>.</p>

      <p>,Wil</p>

      1. Jun 20, 2008

        Eran Galperin

        <p>I'm aware of the proposal process. I tagged it back then (6 months ago) as ready for review but haven't seen any progress... this is why I am asking.</p>

        1. Jun 20, 2008

          Wil Sinclair

          <p>OK, so if it's ready for review, go ahead and move it to the 'Ready for Review' section. It wouldn't hurt to announce it on the list, even if you have done that before. You'll get more community comments in that section, especially if you announce on the list.</p>

          <p>,Wil</p>

          1. Jun 20, 2008

            Eran Galperin

            <p>Thanks, I will update the proposal and announce it on the list.</p>

  4. Dec 15, 2008

    Lars Strojny

    <p>Any reason this could not be become part of Zend_Db_Table?</p>

  5. Feb 05, 2011

    Dolf Schimmel (Freeaqingme)

    <p>Archiving this proposal, feel free to recover it when you want to work on it again. For more details see <a href="http://framework.zend.com/wiki/display/ZFDEV/Archiving+of+abandoned+proposals+(Feb+5+2011)">this email</a>.</p>