blueshoes php application framework and cms            core_storage
[ class tree: core_storage ] [ index: core_storage ] [ all elements ]

Class: Bs_ObjPersister

Source Location: /core/storage/objectpersister/Bs_ObjPersister.class.php

Class Overview

Bs_Object
   |
   --Bs_ObjPersister

A B S T R A C T [*1] Object Bs_ObjPersister.class.php


Author(s):

Version:

  • 4.3.$Revision: 1.2 $ $Date: 2003/08/09 15:17:49 $

Copyright:

  • blueshoes.org

Variables

Methods


Child classes:

Bs_ObjPersisterForFile
dependencies: Bs_ObjPersister
Bs_ObjPersisterForMySql
dependencies: Bs_ObjPersister, Bs_MySql (which requires Bs_Db)

Inherited Variables

Inherited Methods

Class: Bs_Object

Bs_Object::Bs_Object()
Bs_Object::getErrors()
Basic error handling: Get *all* errors as string array from the global Bs_Error-error stack.
Bs_Object::getLastError()
Basic error handling: Get last error string from the global Bs_Error-error stack.
Bs_Object::getLastErrors()
Basic error handling: Get last errors string array from the global Bs_Error-error stack sinc last call of getLastErrors().
Bs_Object::persist()
Persists this object by serializing it and saving it to a file with unique name.
Bs_Object::setError()
Basic error handling: Push an error string on the global Bs_Error-error stack.
Bs_Object::toHtml()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::toString()
Dumps the content of this object to a string using PHP's var_dump().
Bs_Object::unpersist()
Fetches an object that was persisted with persist()

Class Details

[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:

copyright:  blueshoes.org
pattern:  singleton: (pseudostatic)
access:  public
version:  4.3.$Revision: 1.2 $ $Date: 2003/08/09 15:17:49 $
author:  andrej arn <at blueshoes dot org>, Sam Blum <sam at blueshoes dot org>


[ Top ]


Class Variables

$Bs_Rc4Crypt =

[line 207]

reference to the global instance of Bs_Rc4Crypt.



Tags:

see:  _encrypt(), _decrypt(), var $rc4key
access:  public

Type:   object


[ Top ]

$rc4key =  'i think that a hardcoded key is much better than nothing.'

[line 199]

a key to use to crypt data that should be cryptified. i think that a hardcoded key is much much better than nothing.



Tags:

see:  _encrypt(), _decrypt(), var $Bs_Rc4Crypt

Type:   string


[ Top ]

$_objToPersist =  NULL

[line 185]

The Object we are handling for persisting/unpersisting.


Type:   object _objToPersist


[ Top ]

$_persistInfo =  NULL

[line 191]

Cleaned persit info hash based on the passed persist hints hash.



Tags:

see:  Bs_ObjPersister::getPersistInfo(), var $_persistHint

Type:   mixed


[ Top ]



Class Methods


constructor Bs_ObjPersister [line 215]

Bs_ObjPersister Bs_ObjPersister( object &$obj, [mixed $persistHints = NULL], array $_persistHint)

Constuctor.



Parameters:

object   &$obj   reference to the object you want to persist.
array   $_persistHint   a hash with the information about which object vars to persist how. pass by reference if possible.

[ Top ]

method getPersistInfo [line 241]

void getPersistInfo( )

Returns a hash with the *cleaned* persist information thst was retrieved from the persist hint hash and by analysing the target object itself.



Tags:

see:  vars $this->_persistHint, $this->_persistInfo


[ Top ]

method isReservedWord [line 566]

int isReservedWord( string $word)

The following words are explicitly reserved in MySQL and most of them are forbidden by ANSI SQL92

This function may be overwriten when used with other DB's or a more recent list of reserved words but it's a good base to decide if we have to prefix a field- (or table-) name.




Tags:

return:  0 if the word is ok, 1 if it's a discouraged word but allowed (don't use it please!!!), 2 if it's disallowed.
see:  $this->isValidName()


Parameters:

string   $word   the word you want to check

[ Top ]

method persist [line 539]

void persist( )

Persist the object that is handeled by this object.



Tags:

access:  public


Overridden in child classes as:

Bs_ObjPersisterForFile::persist()
Persist the desired object data into the db table.
Bs_ObjPersisterForMySql::persist()
Persist the desired object data into the db table.

Overrides Bs_Object::persist() (Persists this object by serializing it and saving it to a file with unique name.)

[ Top ]

method setPersisterID [line 522]

void setPersisterID( mixed &$persisterID)

Write back the persisterID to the objToPersist.



Tags:

access:  public


Parameters:

mixed   $persisterID   (should be an int, but can be a string, will be converted to int anyway)

[ Top ]

method setVarSettings [line 230]

size setVarSettings( array $persistHints)

Set the '_persistInfo hash'. See header for details.

This function will do a 'best effort'. This means the given $persistHints will be taken and 'cleaned'




Tags:

return:  of the cleaned persistHints hash, FALSE if size is == 0.
access:  public


Parameters:

array   $persistHints  

[ Top ]

method unPersist [line 547]

void unPersist( )

Unpersist the object that is handeled by this object.



Tags:

access:  public


Overridden in child classes as:

Bs_ObjPersisterForFile::unPersist()
(Get the data from db) and push it into the object.
Bs_ObjPersisterForMySql::unPersist()
(Get the data from db) and push it into the object.

[ Top ]

method _persistTrigger [line 500]

void _persistTrigger( )

Is triggered just befor we try to get the persist data from the object.



[ Top ]

method _unpersistTrigger [line 509]

void _unpersistTrigger( )

Is triggered just after we initialized the object successfully.



[ Top ]


Documentation generated on Mon, 29 Dec 2003 21:12:11 +0100 by phpDocumentor 1.2.3