Author: Derick Rethans
Date: 2007-01-25 16:52:42 +0100 (Thu, 25 Jan 2007)
New Revision: 4579

Log:
- Document on how to implement structs.

Modified:
   docs/guidelines/implementation.txt

Modified: docs/guidelines/implementation.txt
===================================================================
--- docs/guidelines/implementation.txt  2007-01-25 15:44:09 UTC (rev 4578)
+++ docs/guidelines/implementation.txt  2007-01-25 15:52:42 UTC (rev 4579)
@@ -815,6 +815,61 @@
         }
     }
 
+Structs
+-------
+
+Complex arrays are not used in the eZ Components. In many cases we prefer
+to use a very lightweight class with a few methods that can be more
+conveniently used compared to simple arrays. THis is because we can 
+control which "keys" are available in those classes. Those light weigth
+classes are called "structs" and can be found in the "structs/" directory
+which is a sub-directory of "src/". 
+
+Layout
+~~~~~~
+
+Each struct class extends from ezcBaseStruct::
+
+    class ezcBaseRepositoryDirectory extends ezcBaseStruct
+
+And defines a public property (including documentation) for each
+element in the "array"::
+
+    /**
+     * The type of repository. Either "ezc" or "external".
+     *
+     * @var string
+     */
+    public $type;
+
+The constructor of the class accepts all the allowed elements as parameters,
+sets default values, and assigns the values to the class' properties::
+
+    /**
+     * Constructs a new ezcMailAddress with the mail address $email and the
+     * optional name $name.
+     *
+     * @param string $email
+     * @param string $name
+     */
+    public function __construct( $email, $name = '', $charset = 'us-ascii' )
+    {
+        $this->name = $name;
+        $this->email = $email;
+        $this->charset = $charset;
+    }
+
+A __set_state() method is not required, but recommended. The __set_state()
+method can be used to create an object of this class from a serialized
+PHP variable. The method's implementation looks like::
+
+    static public function __set_state( array $array )
+    {
+        return new ezcMailAddress( $array['email'], $array['name'] );
+    }
+
+See also `Documenting \_\_set\_state`_ on how to document this method.
+
 Dealing with Files
 ==================
 

-- 
svn-components mailing list
svn-components@lists.ez.no
http://lists.ez.no/mailman/listinfo/svn-components

Reply via email to