tripal_db.api.inc 9.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373
  1. <?php
  2. /**
  3. * @file
  4. * Provides an application programming interface (API) to manage references to external databases
  5. *
  6. * @defgroup tripal_db_api DB Module API
  7. * @ingroup tripal_api
  8. */
  9. /**
  10. * Purpose: To retrieve a chado database object
  11. *
  12. * @param $select_values
  13. * An array meant to uniquely select a given database
  14. *
  15. * @return
  16. * Chado database object
  17. *
  18. * The database is selected using tripal_core_chado select and as such the
  19. * $select_values array parameter meant to uniquely identify the database to be
  20. * returned follows the same form as when using tripal_core_chado_select directly.
  21. *
  22. * Example Usage:
  23. * @code
  24. $select_values = array(
  25. 'name' => 'SOFP'
  26. );
  27. $db_object = tripal_db_get_db($select_values);
  28. * @endcode
  29. * The above code selects the SOFP db and returns the following object:
  30. * @code
  31. $db_object = stdClass Object (
  32. [db_id] => 49
  33. [name] => SOFP
  34. [description] =>
  35. [urlprefix] =>
  36. [url] =>
  37. );
  38. * @endcode
  39. *
  40. * @ingroup tripal_db_api
  41. */
  42. function tripal_db_get_db($select_values) {
  43. $columns = array(
  44. 'db_id',
  45. 'name',
  46. 'description',
  47. 'urlprefix',
  48. 'url'
  49. );
  50. $results = tripal_core_chado_select('db', $columns, $select_values);
  51. if (sizeof($results) == 1) {
  52. return $results[0];
  53. }
  54. elseif (empty($results)) {
  55. watchdog('tripal_cdb',
  56. 'tripal_db_get_db: No db matches criteria values:%values',
  57. array('%values' => print_r($select_values, TRUE)),
  58. WATCHDOG_WARNING
  59. );
  60. return FALSE;
  61. }
  62. else {
  63. watchdog('tripal_db',
  64. 'tripal_db_get_db: 2+ dbs match criteria values:%values',
  65. array('%values' => print_r($select_values, TRUE)),
  66. WATCHDOG_WARNING
  67. );
  68. }
  69. }
  70. /**
  71. * Purpose: To retrieve a chado db object
  72. *
  73. * @param $db_id
  74. * db.db_id
  75. * @return
  76. * Chado db object with all fields from the chado db table
  77. *
  78. * @ingroup tripal_db_api
  79. */
  80. function tripal_db_get_db_by_db_id($db_id) {
  81. $r = db_fetch_object(chado_query(
  82. "SELECT * FROM {db} WHERE db_id=%d", $db_id
  83. ));
  84. return $r;
  85. }
  86. /**
  87. * Purpose: To retrieve a chado db object
  88. *
  89. * @param $name
  90. * db.name
  91. * @return
  92. * chado db object with all fields from the chado db table
  93. *
  94. * @ingroup tripal_db_api
  95. */
  96. function tripal_db_get_db_by_name($name) {
  97. $values = array('name' => $name);
  98. $options = array('statement_name' => 'sel_db_na');
  99. $db = tripal_core_chado_select('db', array('*'), $values, $options);
  100. if (count($db) == 1) {
  101. return $db[0];
  102. }
  103. if (count($db) == 0) {
  104. return FALSE;
  105. }
  106. if (count($db) > 1) {
  107. return FALSE;
  108. }
  109. }
  110. // Purpose: To retrieve a chado db object
  111. //
  112. // @params where_options: array(
  113. // <column_name> => array(
  114. // 'type' => <type of column: INT/**STRING>,
  115. // 'value' => <the vlaue you want to filter on>,
  116. // 'exact' => <if TRUE use =; if FALSE use ~>,
  117. // )
  118. // )
  119. // @return chado db object with all fields from the chado db table
  120. //
  121. //function tripal_db_get_db ($where_options) {
  122. /**
  123. * Purpose: Create an options array to be used in a form element
  124. * which provides a list of all chado dbs
  125. *
  126. * @return
  127. * An array(db_id => name) for each db in the chado db table
  128. *
  129. * @ingroup tripal_db_api
  130. */
  131. function tripal_db_get_db_options() {
  132. $result = chado_query(
  133. "SELECT db_id, name FROM {db}"
  134. );
  135. $options = array();
  136. while ( $r = db_fetch_object($result) ) {
  137. $options[$r->db_id] = $r->name;
  138. }
  139. return $options;
  140. }
  141. // Purpose: To retrieve a chado dbxref object
  142. //
  143. // @param where_options: array(
  144. // <column_name> => array(
  145. // 'type' => <type of column: INT/**STRING>,
  146. // 'value' => <the vlaue you want to filter on>,
  147. // 'exact' => <if TRUE use =; if FALSE use ~>,
  148. // )
  149. // )
  150. // @return chado dbxref object with all fields from the chado dbxref table
  151. //
  152. //function tripal_db_get_dbxref ($where_options) {
  153. /**
  154. * Purpose: To retrieve a chado database reference object
  155. *
  156. * @param $select_values
  157. * An array meant to uniquely select a given database reference
  158. *
  159. * @return
  160. * Chado database reference object
  161. *
  162. * The database reference is selected using tripal_core_chado select and as such the
  163. * $select_values array parameter meant to uniquely identify the database reference to be
  164. * returned follows the same form as when using tripal_core_chado_select directly.
  165. *
  166. * Example Usage:
  167. * @code
  168. $select_values = array(
  169. 'accession' => 'synonym',
  170. 'db_id' => array(
  171. 'name' => 'SOFP'
  172. )
  173. );
  174. $dbxref_object = tripal_db_get_dbxref($select_values);
  175. * @endcode
  176. * The above code selects the synonym database reference and returns the following object:
  177. * @code
  178. $dbxref_object = stdClass Object (
  179. [dbxref_id] => 2581
  180. [accession] => synonym
  181. [description] =>
  182. [version] =>
  183. [db_db_id] => 49
  184. [db_name] => SOFP
  185. [db_description] =>
  186. [db_urlprefix] =>
  187. [db_url] =>
  188. );
  189. * @endcode
  190. *
  191. * @ingroup tripal_db_api
  192. */
  193. function tripal_db_get_dbxref($select_values) {
  194. $columns = array(
  195. 'dbxref_id',
  196. 'db_id',
  197. 'accession',
  198. 'description',
  199. 'version'
  200. );
  201. $results = tripal_core_chado_select('dbxref', $columns, $select_values);
  202. if (sizeof($results) == 1) {
  203. $dbxref = tripal_db_add_db_to_object(array('db_id' => $results[0]->db_id), $results[0], array());
  204. unset($dbxref->db_id);
  205. return $dbxref;
  206. }
  207. elseif (empty($results)) {
  208. watchdog('tripal_db',
  209. 'tripal_db_get_dbxref: No dbxref matches criteria values:%values',
  210. array('%values' => print_r($select_values, TRUE)),
  211. WATCHDOG_WARNING
  212. );
  213. return FALSE;
  214. }
  215. else {
  216. watchdog('tripal_db',
  217. 'tripal_db_get_dbxref: 2+ dbxrefs match criteria values:%values',
  218. array('%values' => print_r($select_values, TRUE)),
  219. WATCHDOG_WARNING
  220. );
  221. }
  222. }
  223. /**
  224. * Purpose: To retrieve a chado dbxref object with a given accession
  225. *
  226. * @param $accession
  227. * dbxref.accession
  228. * @param $db_id
  229. * dbxref.db_id
  230. * @return
  231. * chado dbxref object with all fields from the chado dbxref table
  232. *
  233. * @ingroup tripal_db_api
  234. */
  235. function tripal_db_get_dbxref_by_accession($accession, $db_id=0) {
  236. if (!empty($db_id)) {
  237. $r = db_fetch_object(chado_query(
  238. "SELECT * FROM {dbxref} WHERE accession='%s' AND db_id=%d",
  239. $accession, $db_id
  240. ));
  241. }
  242. else {
  243. $r = db_fetch_object(chado_query(
  244. "SELECT * FROM {dbxref} WHERE accession='%s'",
  245. $accession
  246. ));
  247. }
  248. return $r;
  249. }
  250. /**
  251. * Adds a new database to the Chado DB table and returns the DB object.
  252. *
  253. * @param $dbname
  254. * The name of the database. This name is usually used as the prefix for
  255. * CV term accessions
  256. * @param $description
  257. * Optional. A description of the database. By default no description is required.
  258. * @param $url
  259. * Optional. The URL for the database
  260. * @param $urlprefix
  261. * Optional. The URL that is to be used as a prefix when constructing a link to
  262. * a database term
  263. * @param $update
  264. * Optional. Set this to '1' to force an update of the database if it
  265. * already exists. The default is to not update. If the database exists
  266. * then nothing is added.
  267. *
  268. * @return
  269. * An object populated with fields from the newly added database. If the
  270. * database already exists it returns the values in the current entry.
  271. *
  272. * @ingroup tripal_db_api
  273. */
  274. function tripal_db_add_db($dbname, $description = '', $url = '',
  275. $urlprefix = '', $update = 0) {
  276. // build the values array for inserting/updating
  277. $ins_values = array(
  278. 'name' => $dbname,
  279. 'description' => $description,
  280. 'url' => $url,
  281. 'urlprefix' => $urlprefix
  282. );
  283. // get the database record if it already exists
  284. $sel_values = array('name' => $dbname);
  285. $sel_options = array('statement_name' => 'sel_db_na');
  286. $result = tripal_core_chado_select('db', array('*'), $sel_values, $sel_options);
  287. // if it does not exists then add it
  288. if (count($result) == 0) {
  289. $ins_options = array('statement_name' => 'ins_db_nadeurur');
  290. $success = tripal_core_chado_insert('db', $ins_values, $ins_options);
  291. if (!$success) {
  292. watchdog('tripal_db', "Cannot create db '$dbname'.", NULL, WATCHDOG_WARNING);
  293. return 0;
  294. }
  295. $result = tripal_core_chado_select('db', array('*'), $sel_values, $sel_options);
  296. }
  297. // if it exists and update is enabled the do the update
  298. elseif ($update) {
  299. $upd_options = array('statement_name' => 'upd_db_nadeurur');
  300. $success = tripal_core_chado_update('db', $sel_values, $ins_values, $upd_options);
  301. if (!$success) {
  302. watchdog('tripal_db', "Cannot update db '$dbname'.", NULL, WATCHDOG_WARNING);
  303. return 0;
  304. }
  305. $result = tripal_core_chado_select('db', array('*'), $sel_values, $sel_options);
  306. }
  307. // return the database object
  308. return $result[0];
  309. }
  310. /**
  311. *
  312. * @ingroup tripal_db_api
  313. */
  314. function tripal_db_add_dbxref($db_id, $accession, $version = '', $description = '') {
  315. $ins_values = array(
  316. 'db_id' => $db_id,
  317. 'accession' => $accession,
  318. 'version' => $version,
  319. 'description' => $description
  320. );
  321. // check to see if the dbxref exists
  322. $sel_values = array(
  323. 'db_id' => $db_id,
  324. 'accession' => $accession,
  325. );
  326. $sel_options = array('statement_name' => 'sel_dbxref_dbacve', 'is_duplicate' => 1);
  327. $result = tripal_core_chado_select('dbxref', array('*'), $sel_values, $sel_options);
  328. // if it doesn't already exist then add it
  329. if (!$result) {
  330. $ins_options = array('statement_name' => 'ins_dbxref_dbacvede');
  331. $success = tripal_core_chado_insert('dbxref', $ins_values, $ins_options);
  332. if (!$success) {
  333. watchdog('tripal_cv', "Failed to insert the dbxref record $accession", NULL, WATCHDOG_WARNING);
  334. return 0;
  335. }
  336. $result = tripal_core_chado_select('dbxref', array('*'), $sel_values, $sel_options);
  337. }
  338. return $result[0];
  339. }