[line 179]
A B S T R A C T [*1] Object Bs_ObjPersister.class.php
This object is the abstract layer for persisting ojects. It holds the basic fuctions that are independant of the underlying storage. To make use of this object, you must extend it to a storage-specific object like Bs_ObjPersisterForMySql.class.php.
[*1] Abstract class (as defined by JAVA) An abstract class may contain abstract methods, that is, methods with no implementation. In this way, an abstract class can define a complete programming interface, thereby providing its subclasses with the method declarations for all of the methods necessary to implement that programming interface. However, the abstract class can leave some or all of the implementation details of those methods up to its subclasses.
Persists and unpersists (loads) the data of any object.
Ever wanted to store your object (vars) somewhere (db, whatever) and make it reloadable? Didn't feel like writing all the sql stuff? Then this is something for you.
A few things to know about this class, kinda like the manual :) o) You cannot use it by itself. Use Bs_ObjPersisterForMySql instead, or write your own storage class. flatfiles would be neat.
o) It's not easy to use it for relational things, but possible.
o) var names could conflict with reserved words, especially in the db (mysql) implementation. to avoid this, all db field names are prefixed with the value of the constant BS_OP_FIELD_PREFIX. so by default a db field name is prefix + varname. you may give your own field name in the hint array. see below.
o) This is the hash-array to tell *which* vars to persist and *how* to persist them. Set up a hash which has the form of the following sample: $_persistHints = array( 'aInt' => array('mode'=>'lonely', 'metaType'=>'integer', 'index'=>TRUE, 'name'=>'myInt'), 'bInt' => array('mode'=>'stream'), 'cInt' => array('mode'=>'no'), 'aBool' => array('mode'=>'lonely', 'metaType'=>'integer', 'index'=>FALSE), 'aString' => array('mode'=>'lonely', 'metaType'=>'string', 'index'=>TRUE), 'aArray' => array('mode'=>'stream'), 'aObj' => array('mode'=>'stream'), 'aStr' => array('mode'=>'lonely', 'metaType'=>'stream', 'index'=>TRUE), ); Use the class var name as the key of the hash. The value of the hash is another hash which can have the following key/value pairs:
----------+---------------+------------------------------------------------ KEY | VALUE | MEANING ----------+---------------+------------------------------------------------ mode | no | Don't persist this var. Useful for overwriting. | lonely | Use a table field to store the value. | stream | Serialize the data into the BS_OP_BLOB_HASH_NAME table field | | Default is mode = 'stream' ----------+---------------+------------------------------------------------ crypt | TRUE|FALSE | tells if we should decrypt/encrypt the value. | | see the appropriate vars and methods. | | NOTE: a string needs to be serialized (this is | | done for you) before in can be crypted. and | | versa. | | Default is crypt = FALSE ----------+---------------+------------------------------------------------ metaType | One of: 'boolean', 'integer', 'double', 'string', 'datetime', | 'blob' or 'stream'. | Arrays and Objects are forced to be a 'stream'! | A string is limited to 255 chars. If you need more, use blob. ----------+---------------+------------------------------------------------ index | TRUE|FALSE | Used if indexing is possible like in dbs. | | TRUE='index',FALSE='no index'(default is FALSE) | | stream types can't be indexed (always FALSE) ----------+---------------+------------------------------------------------ name | mixed (string or boolean). | NOTE: Never use 'ID' and 'internalSerializedData' (internally used) | a) Bye setting 'name' to TRUE means to use the key as field | name 'as is'. | b) Bye setting a string, you make it use the given | string as field name 'as is'. | In a) and b) YOU(!) are then responsable *NOT* use | a reserved name from the underling DB. | Default is to *try* to use the key name 'as is' BUT if the word | in in the 'Reserved Word List' it will be prefixed with | BS_OP_FIELD_PREFIX. ----------+----------------------------------------------------------------
NOTE: You can always add and modify 'stream'-type-vars in your class because no storage structure modification needs to be made. But any modifacation to fields using a column like 'lonely'-type-vars will need a storage (db table) structure modification. the implementation may do these modifications automatically itself, or may not. the mysql implementation currently is smart enough to add newly added, missing fields, but does not change existing fields where the var type has changed. so check your stuff, and maybe do the modifications manually, or make the code smarter.
Depending on the PHP-type the '_p'-var will be maped to one of are own meta typs and indexing is set: PHP-type | Meta-Type | Indexed | Comment ======================+============+=========+==================================== boolean | 'boolean' | Yes | 1:1 map ----------------------+------------+---------+------------------------------------ integer | 'integer' | Yes | 1:1 map ----------------------+------------+---------+------------------------------------ double | 'double' | Yes | 1:1 map ----------------------+------------+---------+------------------------------------ string | 'blob' | No | Cause 255 chars may not be enough. ----------------------+------------+---------+------------------------------------ resource | 'string' | Yes | A'resource' is converted to string. It can be | | | handled like a short string (e.g. 'Resource ID #345'). ----------------------+------------+---------+------------------------------------ object and array | 'stream' | No |'array' and 'object' are always converted to 'stream'. ----------------------+------------+---------+------------------------------------ unknown type and NULL| 'stream' | No | We don't know the type. So we stay on the safe side. ----------------------+------------+---------+------------------------------------ The meta-type 'stream' means that the value will be serialized.
o) $persisterID var. Even if you don't define it, your object will have a var called '$persisterID' whenever you persist or unpersist. It's the object identifier for persisting/unpersisting. The datatype is integer, it is persisted lonely with an index. In the mysql it would corespond to the ID field. Setting the $persisterID to a value >0 will give it a relation to the unterlying sorage. This means: If you unpersist, the object with ID==$persisterID will tried to be fetched. On the other hand if you persist the data of the object will try to update with the data of the current vars. If $persisterID is 0 or NULL or unset the object will try to insert it's current data and on success $persisterID will hold the id of the inserted data record.
o) for an example usage check the ecg.
o) Triggers: It's possible to have the object informed before and after it is to be persisted and/or unpersisted. The only thing you'll have to do is to define up to 2 functions in the to persist class: function persistTrigger() {...} // Is called just befor we try to get the persist data function unpersistTrigger(){...} // Is called just after we initialized the object successfully
///+"*+"*+"* Following may be obsolet --sam 21.5.01 o) before we were talking about the 'persisterID'. also we said that using this class for relational things would be hard. to make your life a bit easier, you can define a method setPersisterID($persisterID) in your class. when the data gets unpersisted, the object var $persisterID will be set automatically. but if you need to do relational things with this ID, you can create such a method and do whatever you want. if no such method exists, the $persisterID var will be set directly.
no dependencies here.
Tags: