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