Documentation for PHP ORMapper. version 2.0

Size: px

Start display at page:

Download "Documentation for PHP ORMapper. version 2.0"

Clifton Small
6 years ago
Views:

1 Documentation for PHP ORMapper version 2.0

2 Table of Contents Licensing...3 Requirements and installation...4 The Author...4 The Classes...5 Code examples...7

3 Licensing This project is released under the GNU GPL. Anyone who wants to, can use, modify, distribute or sell this code for free (as in free speech, not free beer). For more information on the GNU GPL and what it means, please visit The documentation itself is released under the GNU FDL (

4 Requirements and installation When I developed the PHP ORMapper I used PHP version 5.2.4, MySQL version a. As for the installation, no extra installation is required. Simply just unzip the package to the desired location, and start using it. The Author If you experience any misbehavior, or faults, with the code please contact me and I will see if I can correct it. If you modify it, and make it better be kind to send a copy to me. Björn Wikström bjorn.wikstrom@gmail.com

5 The Classes Most important one: ORMapper The ORMapper class is the heart of the project, of course. final static $MYSQL A constant for defining MySQL as DBMS. final static $MSSQL A constant defining Microsoft SQL Server AS DBMS. final static $PGSQL A constant defining PostgreeSQL as DBMS. ORMapper(constant DBMS, string host, string database, string user, string password) throws ORMapperException The constructor of the class ORMapper takes several arguments which are all required. For specifing a specific port to connect to, change the host to contain both the host and the port, separated by a colon. I.e.: $orm = new ORMapper(ORMapper::MYSQL, localhost:4412, mydb, myusr, MyPwd ); ORMapper(object pdoinstance)throws ORMapperException The constructor can also take only one argument, an instance of the PDO class. object find(type class, mixed var) throws RecordNotFoundException The method find() retrieves a single object of the type specified as the first parameter (Note: not an instance of the class/an object but the class type itself!), using the second parameter as primary key value. void save(object o) throws ORMapperException The method save() saves the specified object to the database. If the object is of a unrecognized type an exception is thrown. void query(type class [, string query]) throws ORMapperException The method query() takes a type as first parameter as the function find and, if a query is specified retrives all records of the type specified matching the query. If no query is specified, all records matching the type is retrived. The method uses parameterized syntax, like prepared statements. The query should look like this: WHERE parameter=:key AND param2=:key2 Note that you shouldn't use SQL keywords like SELECT * FROM or equal. The query() method only handles selections, and specifying the table is not necessary since the type class is specified as a parameter.

6 MappedList execute(array valuepairs) throws ORMapperException The method execute() executes the query() from earlier, returning an instance of the MappedList class filled with objects of the specified type from query(). The method takes an array as a parameter, which should contain the values for the prepared statement as well as the key parameters. A matching call from the query above should be as this: $mappedlist = $orm >execute(array( param => Value1, param2 => Value2 )); void loadrelations(object o) Explicit load of the relations to the object, which must be of the type Recordable and implement at least one of the relationship interfaces. void remove(object o) throws ORMapperException The method remove() removes the specified object from the database. object getpdoinstance() The method returns the underlaying instance of the PDO class. Interface Recordable All classes that should be mapped to a database, should implement the interface Recordable. If they don't, the ORMapper class will reject them when trying to map them to the database. The interface only demands that two methods should be implemented in the child class the getpk() method and the gettablebinding() method. The getpk() method shall return the primary key field of the table. The gettablebindning() method shall return the table name which the instances of the class should be mapped against. Interface OneToMany This is a relationship interface, to mark which classes that will/can be mapped against other classes. The OneToMany interface demands three methods of the implementing class. The getrelatives() method that maps to a class of the type ManyToOne. The method returns a MappedList of instances of that ManyToOne class. The method setrelatives(mappedlist m) which is used when adding related instances to that list. The method getonetomanytype, which should return the type of the mapped class. See the code examples for more information. Interface ManyToOne The same as above, but the other way around. The classes that implements this interface must declare the methods getparent(), setparent(object o) and getmanytoonetype(). The method getparent() should return the One in the relationship, the method setparent(object o) sets the same object and the method getmanytoonetype() should return the type of the related instances. Interface OneToOne The interface OneToOne marks a class with a one to one relationship, using the methods getrelative(), setrelative(object o) and getonetoonetype().

7 Class Record As with the interface Recordable, all classes should extend the class Record otherwise the classes will not be mapped to the database. The Record class only has one method, the tostring() method. You should not override this method unless you are sure on what you are doing. Class MappedList The class MappedList is used as a queue (first in, first out), when retrieving records from the database. void add(object o) Adds the object to the queue. object get(integer index) Retrieves the object at specified position, but keeps it in the queue as well. boolean hasnext() object next() Returns true if there are objects in the queue, false if it is empty. throws MappedListException Returns the next object in line in the queue, and removes it from the queue. Throws an exception if the list is empty. integer size() Returns the size of the queue. array getarray() Returns the queue as an array.

8 Code examples A Recordable Class (MyUser.php) require_once( Recordable.php ); class MyUser extends Record implements Recordable { private $id; private $username; private $ ; public function getid() { return $this >id; public function setid($id) { $this >id = $id; public function getusername() { return $this >username; public function setusername($username) { $this >username = $username; public function get () { return $this > ; public function set ($ ) { $this > = $ ; public function getpk() { return id ; public function gettablebinding() { return Users ; The class that we will be working with in the examples, a simple User class which will be mapped against the table 'Users'. The last two methods are necessary for the bindings to work, and the setters/getters are necessary for the information flow. The name of the setters and getters should be the same as the fields in the table 'Users', using a naming convention similar to the JavaBean naming rules. The database table The table in our database should look like this to match the class: CREATE TABLE Users ( ); id INT NOT NULL AUTO_INCREMENT, username VARCHAR(50) NOT NULL, VARCHAR(50) NOT NULL, PRIMARY KEY(id)

9 Connecting to a database: try { $orm = new ORMapper(ORMapper::MYSQL, localhost, db, username, password ); catch(ormapperexception $e) { die($e >getmessage()); Saving a new user to the database: require_once( MyUser.php ); try { $orm = new ORMapper(ORMapper::MYSQL, localhost, db, username, password ); $u = new MyUser(); $u >setusername( Bob ); $u >set ( bob@myco.com ); $orm >save($u); catch(ormapperexception $e) { die($e >getmessage()); Retrieve a user from the database, using find(): require_once( MyUser.php ); try { $orm = new ORMapper(ORMapper::MYSQL, localhost, db, username, password ); $u = $orm >find(myuser, 1);/* Using the primary key (id) to retrieve the user */... catch(ormapperexception $e) { die($e >getmessage()); catch(recordnotfoundexception $e) { echo No user with id number 1 was found. ;

10 Retrieve all users from the database: require_once( MyUser.php ); try { $orm = new ORMapper(ORMapper::MYSQL, localhost, db, username, password ); $orm >query(myuser); /* Alternatively: */ $orm >query(myuser, ALL ); $mlist = $orm >execute() while($mlist >hasnext()) { $currentuser = $mlist >next(); echo Username:. $currentuser >getusername(); echo <br /> ; echo E mail:. $currentuser >get (); echo <br /> ; catch(... Retrieve users with criteria: require_once( MyUser.php ); try { $orm = new ORMapper(ORMapper::MYSQL, localhost, db, username, password ); $orm >query(myuser, WHERE username=:uname AND =:mail ORDER BY id ); $mlist = $orm >execute(array( :uname => Bob, :mail => bob@myco.com ));... Remove a user from the database: require_once( MyUser.php ); try { $orm = new ORMapper(ORMapper::MYSQL, localhost, db, username, password ); $u = $orm >find(myuser, 1); $orm >remove($u); catch(...

11 Relationships class Fruit extends Record implements Recordable, ManyToOne { private $id; private $type; private $color; private $fruitbowl; function construct($type =, $color = ) { $this >type = $type; $this >color = $color; public function setid($id) { $this >id = $id; public function getid() { return $this >id; public function settype($type) { $this >type = $type; public function gettype() { return $this >type; public function setcolor($color) { $this >color = $color; public function getcolor() { return $this >color; public function getpk() { return id ; public function gettablebindning() { return Fruits ; public function setparent($parent) { $this >fruitbowl = $parent; public function getparent() { return $this >fruitbowl; public function getmanytoonetype() { return Fruitbowl; class Fruitbowl extends Record implements Recordable, OneToMany { private $id; private $manufacturer; private $fruits; public function setid($id) { $this >id = $id; public function getid() { return $this >id; public function setmanufacturer($mf) { $this >manufacturer = $mf; public function getmanufacturer() { return $this >manufacturer; public function getpk() { return id ; public function gettablebinding() { return Fruitbowls ; public function setrelatives($fruits) { $this >fruits = $fruits; public function getrelatives() { return $this >fruits; public function getonetomanytype() { return Fruit;

12 $orm = new ORMapper(ORMapper::MYSQL, localhost, database, username, password ); $bowl = new Fruitbowl(); $list = new MappedList(); $f = new Fruit(); $f >settype( banana ); $f >setcolor( yellow ); $list >add($f); $f = new Fruit( apple, red ); $list >add($f); $bowl >setmanufacturer( Kosta Boda ) $bowl >setrelatives($list); $orm >save($bowl); $orm >query(fruit, WHERE type=:t ); $list = $orm >execute(array( :t => apple )); while($list >hasnext()) { $currentfruit = $list >next(); echo This fruit is a/an. $currentfruit >gettype(); echo and is in a bowl from. $currentfruit >getparent() >getmanufacturer()

Using PHP with MYSQL

Using PHP with MYSQL PHP & MYSQL So far you've learned the theory behind relational databases and worked directly with MySQL through the mysql command-line tool. Now it's time to get your PHP scripts talking