What are DAO objects?

DAO stands for Data Access Objects. Those are objects which you use mostly - players, accounts, groups, objects lists. They use database resource to fetch/store data and provides you programming interface to access that data without using additional langauges like SQL, or XML.

Why this way?

PHP is a PHP. When you write a code in PHP each element has a meaning. While using SQL you have to use database queries. In code they are simply a strings which doesn't represent any particular data for programming enviroment. DAO objects wraps database operations in objective aspect, so "dead" string queries becomes a fully functional objects which you can control more strictly, allows you to assign relations and automate some parts.

Loading data

First way of using DAO objects is loading data from database. Each row has integer primary key which means it is unique value that identifies that row in it's table. For accounts it is account number, for players, groups, guilds etc. it is ID. This is the most reliable way of identyfing database resources - whenever you can load object by it's ID - do that instead of operating on other identifiers (like name).

To load record you can use either load() method, or load it on object initialisation by passing ID as constructor parameter.

When object is already loaded you still can call load() method to re-load new record into object. Old data won't be changed in database unless you will save it. However it is higly recommended to make sure about what you are doing in such cases - you should watch variable references as object instance won't change so the same instance will now point to another record in database. At all it is strongly unrecommended unless you really know what you are doing.

1. <?php
2.  
3. // to not repeat all that stuff
4. include('quickstart.php');
5.  
6. // creates new account object
7. $account = new OTS_Account();
8.  
9. // loads account with ID (account number) 111111
10. $account->load(111111);
11.  
12. // alternative way - shorter
13. $account2 = new OTS_Account(111111);
14.  
15. // WARNING! This one won't work!
16. //$account2 = new OTS_Account('111111');
17. // '111111' is a string! not integer
18.  
19. // shows results of loading account
20. echo '111111 e-mail address: ', $account->getEMail();
21.  
22. ?>

Loading by name

It is also possible to load records by their name identifiers (for accounts e-mail address is used in such case). This way is less reliable since it is possible to change name identifier of nearly all records while IDs are always same, but string identifiers are more friendly for people, for example for loading players by their names. To load record by it's name you have to use find() method. It is also possible to do that automaticly on object initialisation by passing string parameter to constructor.

1. <?php
2.  
3. // to not repeat all that stuff
4. include('quickstart.php');
5.  
6. // creates new player object
7. $player = new OTS_Player();
8.  
9. // loads player
10. $player->find('Wrzasq');
11.  
12. // this does the same
13. $player2 = new OTS_Player('Wrzasq');
14.  
15. // checks if player exists
16. if( $player->isLoaded() )
17. {
18.     // prints character info
19.     echo 'Player \'' . $player->getName() . '\' has ' . $player->getLevel() . ' level.', "\n";
20.  
21.     // example of retriving associated objects
22.     echo 'Player \'' . $player->getName() . '\' is member of ' . $player->getGroup()->getName() . ' group.', "\n";
23. }
24. else
25. {
26.     echo 'Player does not exists.', "\n";
27. }
28.  
29. ?>

Saving data

On the other hand you can save objects to database using save() method. If you work on loaded object calling save() will effect in updating row in database. If you created empty object, calling save() will create new row in database. Usualy objects after creating have some default field values, but remember that some resources needs another in order to be saved, for example to save player you first have to assign it to an account.

Deleting

You can also delete data. To achive this use delete() method - with caution of course. Good information is, that this operation is (during same script execution and under some other conditions) recoverable. This method only deletes data from database and resets object key ID but doesn't reset entire object so it is still stored in memory. Calling save() method will then insert data back into database.

1. <?php
2.  
3. // to not repeat all that stuff
4. include('quickstart.php');
5.  
6. // creates new player object
7. $player = new OTS_Player('Wrzasq');
8.  
9. // deletes player
10. $player->delete();
11.  
12. // as player was deleted this will insert new row into database but all data will be restored
13. $player->save();
14.  
15. ?>

However there is important thing - it will be same data, but not the same record! Old player will be deleted and new player will be inserted. It will be only a copy and it will have different ID, so if anything was pointing to old player's ID, it won't find it after that.

Custom fields

POT was created for basic SVN database structure. However you can access custom fields with POT. You do that with getCustomField() and setCustomField() methods of DAO objects.

While accessing custom fields you have to remember about using proper PHP types of passed values. POT doesn't know anything about those fields so it uses value type to check the way it should serve it for a query. Don't worry about safety - it doesn't create any hole for SQL injections. But you must remember, that 1 (integer) is not same as '1' (string), or 1.0 (float). POT will quote strings to fit SQL query and to prevent from SQL injections so make sure you cast your values to type that represents field type to prevent (mainly) from quoting numeric fields.

You should use those methods only to access custom fields that are not accessible throught standard POT API. Those methods executes SQL query each time you call them so it would be a huge effectivity loss to access standard fields with getCustomField()/setCustomField().

Also it is important that in difference to fields accessible with standard setters, you can't set custom field value on not loaded/saved object. You must either load object from database, or save standard record before using custom fields as they need record primary key assigned to object for queries. Here is an example:

1. <?php
2.  
3. // to not repeat all that stuff
4. include('quickstart.php');
5.  
6. // creates new OTS_Player object
7. $player = new OTS_Player();
8.  
9. // sets basic fields
10. $player->setName('Wrzasq');
11. $player->setSex(POT::SEX_MALE);
12. $player->setVocation(POT::VOCATION_KNIGHT);
13. /* etc... */
14.  
15. /*
16. this is bad! we can't call this now as we dont have object ID assinged yet
17.  
18. $player->setCustomField('my_field', 2);
19.  
20. must save before that to get automatic ID:
21. */
22. $player->save();
23.  
24. // now we can call that:
25. // 2 won't be quoted - it's integer
26. $player->setCustomField('my_field', 2);
27. // 3 will be quoted - '3' is a string!
28. $player->setCustomField('another_field', '3');
29.  
30. ?>