tripal_db.api.inc 15 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498
  1. <?php
  2. /**
  3. * @file
  4. * Provides an application programming interface (API) to manage references to
  5. * external databases
  6. */
  7. /**
  8. * @defgroup tripal_db_api Database Reference API
  9. * @ingroup tripal_api
  10. * @{
  11. * Provides an application programming interface (API) to manage references to external databases
  12. * @}
  13. */
  14. /**
  15. * Retrieves a chado db object
  16. *
  17. * Example Usage:
  18. * @code
  19. $select_values = array(
  20. 'name' => 'SOFP'
  21. );
  22. $db_object = tripal_db_get_db($select_values);
  23. * @endcode
  24. * The above code selects the SOFP db and returns the following object:
  25. * @code
  26. $db_object = stdClass Object (
  27. [db_id] => 49
  28. [name] => SOFP
  29. [description] =>
  30. [urlprefix] =>
  31. [url] =>
  32. );
  33. * @endcode
  34. *
  35. * @param $identifier
  36. * An array with the key stating what the identifier is. Supported keys (only on of the
  37. * following unique keys is required):
  38. * - db_id: the chado cv.cv_id primary key
  39. * - name: the chado cv.name field (assume unique)
  40. * @param $options
  41. * An array of options. Supported keys include:
  42. * - Any keys supported by chado_generate_var(). See that function definition for
  43. * additional details.
  44. *
  45. * NOTE: the $identifier parameter can really be any array similar to $values passed into
  46. * chado_select_record(). It should fully specify the db record to be returned.
  47. *
  48. * @return
  49. * If unique values were passed in as an identifier then an object describing the cv
  50. * will be returned (will be a chado variable from chado_generate_var()). Otherwise,
  51. * an array of objects will be returned.
  52. *
  53. * @ingroup tripal_db_api
  54. */
  55. function chado_get_db($identifiers, $options = array()) {
  56. // Error Checking of parameters
  57. if (!is_array($identifiers)) {
  58. tripal_report_error(
  59. 'tripal_db_api',
  60. TRIPAL_ERROR,
  61. "chado_get_db: The identifier passed in is expected to be an array with the key
  62. matching a column name in the db table (ie: db_id or name). You passed in %identifier.",
  63. array(
  64. '%identifier'=> print_r($identifiers, TRUE)
  65. )
  66. );
  67. }
  68. elseif (empty($identifiers)) {
  69. tripal_report_error(
  70. 'tripal_db_api',
  71. TRIPAL_ERROR,
  72. "chado_get_db: You did not pass in anything to identify the db you want. The identifier
  73. is expected to be an array with the key matching a column name in the db table
  74. (ie: db_id or name). You passed in %identifier.",
  75. array(
  76. '%identifier'=> print_r($identifiers, TRUE)
  77. )
  78. );
  79. }
  80. // Try to get the db
  81. $db = chado_generate_var(
  82. 'db',
  83. $identifiers,
  84. $options
  85. );
  86. // Ensure the db is singular. If it's an array then it is not singular
  87. if (is_array($db)) {
  88. tripal_report_error(
  89. 'tripal_db_api',
  90. TRIPAL_ERROR,
  91. "chado_get_db: The identifiers you passed in were not unique. You passed in %identifier.",
  92. array(
  93. '%identifier'=> print_r($identifiers, TRUE)
  94. )
  95. );
  96. }
  97. // Report an error if $db is FALSE since then chado_generate_var has failed
  98. elseif ($db === FALSE) {
  99. tripal_report_error(
  100. 'tripal_db_api',
  101. TRIPAL_ERROR,
  102. "chado_get_db: chado_generate_var() failed to return a db based on the identifiers
  103. you passed in. You should check that your identifiers are correct, as well as, look
  104. for a chado_generate_var error for additional clues. You passed in %identifier.",
  105. array(
  106. '%identifier'=> print_r($identifiers, TRUE)
  107. )
  108. );
  109. }
  110. // Else, as far we know, everything is fine so give them their db :)
  111. else {
  112. return $db;
  113. }
  114. }
  115. /**
  116. * Create an options array to be used in a form element
  117. * which provides a list of all chado dbs
  118. *
  119. * @return
  120. * An array(db_id => name) for each db in the chado db table
  121. *
  122. * @ingroup tripal_db_api
  123. */
  124. function db_get_select_options() {
  125. $result = chado_query("SELECT db_id, name FROM {db}");
  126. $options = array();
  127. foreach ($result as $r) {
  128. $options[$r->db_id] = $r->name;
  129. }
  130. return $options;
  131. }
  132. /**
  133. * Retrieves a chado database reference object
  134. *
  135. * Example Usage:
  136. * @code
  137. $identifiers = array(
  138. 'accession' => 'synonym',
  139. 'db_id' => array(
  140. 'name' => 'SOFP'
  141. )
  142. );
  143. $dbxref_object = tripal_db_get_dbxref($identifiers);
  144. * @endcode
  145. * The above code selects the synonym database reference and returns the following object:
  146. * @code
  147. $dbxref_object = stdClass Object (
  148. [dbxref_id] => 2581
  149. [accession] => synonym
  150. [description] =>
  151. [version] =>
  152. [db_db_id] => 49
  153. [db_name] => SOFP
  154. [db_description] =>
  155. [db_urlprefix] =>
  156. [db_url] =>
  157. );
  158. * @endcode
  159. *
  160. * @param $identifier
  161. * An array with the key stating what the identifier is. Supported keys (only on of the
  162. * following unique keys is required):
  163. * - dbxref_id: the chado dbxref.dbxref_id primary key
  164. * - accession: the chado dbxref.accession field (assume unique)
  165. * @param $options
  166. * An array of options. Supported keys include:
  167. * - Any keys supported by chado_generate_var(). See that function definition for
  168. * additional details.
  169. *
  170. * NOTE: the $identifier parameter can really be any array similar to $values passed into
  171. * chado_select_record(). It should fully specify the dbxref record to be returned.
  172. *
  173. * @return
  174. * If unique values were passed in as an identifier then an object describing the dbxref
  175. * will be returned (will be a chado variable from chado_generate_var()). Otherwise,
  176. * FALSE will be returned.
  177. *
  178. * @ingroup tripal_db_api
  179. */
  180. function chado_get_dbxref($identifiers, $options = array()) {
  181. // Error Checking of parameters
  182. if (!is_array($identifiers)) {
  183. tripal_report_error(
  184. 'tripal_db_api',
  185. TRIPAL_ERROR,
  186. "chado_get_dbxref: The identifier passed in is expected to be an array with the key
  187. matching a column name in the dbxref table (ie: dbxref_id or name). You passed in %identifier.",
  188. array(
  189. '%identifier'=> print_r($identifiers, TRUE)
  190. )
  191. );
  192. }
  193. elseif (empty($identifiers)) {
  194. tripal_report_error(
  195. 'tripal_db_api',
  196. TRIPAL_ERROR,
  197. "chado_get_dbxref: You did not pass in anything to identify the dbxref you want. The identifier
  198. is expected to be an array with the key matching a column name in the dbxref table
  199. (ie: dbxref_id or name). You passed in %identifier.",
  200. array(
  201. '%identifier'=> print_r($identifiers, TRUE)
  202. )
  203. );
  204. }
  205. // Try to get the dbxref
  206. $dbxref = chado_generate_var(
  207. 'dbxref',
  208. $identifiers,
  209. $options
  210. );
  211. // Ensure the dbxref is singular. If it's an array then it is not singular
  212. if (is_array($dbxref)) {
  213. tripal_report_error(
  214. 'tripal_db_api',
  215. TRIPAL_ERROR,
  216. "chado_get_dbxref: The identifiers you passed in were not unique. You passed in %identifier.",
  217. array(
  218. '%identifier'=> print_r($identifiers, TRUE)
  219. )
  220. );
  221. }
  222. // Report an error if $dbxref is FALSE since then chado_generate_var has failed
  223. elseif ($dbxref === FALSE) {
  224. tripal_report_error(
  225. 'tripal_db_api',
  226. TRIPAL_ERROR,
  227. "chado_get_dbxref: chado_generate_var() failed to return a dbxref based on the identifiers
  228. you passed in. You should check that your identifiers are correct, as well as, look
  229. for a chado_generate_var error for additional clues. You passed in %identifier.",
  230. array(
  231. '%identifier'=> print_r($identifiers, TRUE)
  232. )
  233. );
  234. }
  235. // Else, as far we know, everything is fine so give them their dbxref :)
  236. else {
  237. return $dbxref;
  238. }
  239. }
  240. /**
  241. * Adds a new database to the Chado DB table and returns the DB object.
  242. *
  243. * @param $values
  244. * An associative array of the values of the db (those to be inserted)
  245. * - name: The name of the database. This name is usually used as the prefix for
  246. * CV term accessions
  247. * - description: (Optional) A description of the database. By default no description is required.
  248. * - url: (Optional) The URL for the database
  249. * - urlprefix: (Optional) The URL that is to be used as a prefix when constructing a
  250. * link to a database term
  251. * @param $options
  252. * An associative array of options including:
  253. * - update_existing: (Optional) Set this to '1' to force an update of the database if it
  254. * already exists. The default is to not update. If the database exists
  255. * then nothing is added.
  256. *
  257. * @return
  258. * An object populated with fields from the newly added database. If the
  259. * database already exists it returns the values in the current entry.
  260. *
  261. * @ingroup tripal_db_api
  262. */
  263. function chado_insert_db($values, $options) {
  264. // Default Values
  265. $dbname = $values['name'];
  266. $description = (isset($values['description'])) ? $values['description'] : '';
  267. $url = (isset($values['url'])) ? $values['url'] : '';
  268. $urlprefix = (isset($values['urlprefix'])) ? $values['urlprefix'] : '';
  269. $update = (isset($options['update_existing'])) ? $options['update_existing'] : TRUE;
  270. // build the values array for inserting/updating
  271. $ins_values = array(
  272. 'name' => $dbname,
  273. 'description' => $description,
  274. 'url' => $url,
  275. 'urlprefix' => $urlprefix
  276. );
  277. // get the database record if it already exists
  278. $sel_values = array('name' => $dbname);
  279. $sel_options = array('statement_name' => 'sel_db_na');
  280. $result = chado_select_record('db', array('*'), $sel_values, $sel_options);
  281. // if it does not exists then add it
  282. if (count($result) == 0) {
  283. $ins_options = array('statement_name' => 'ins_db_nadeurur');
  284. $success = chado_insert_record('db', $ins_values, $ins_options);
  285. if (!$success) {
  286. tripal_report_error('tripal_db', TRIPAL_WARNING, "Cannot create db '$dbname'.", NULL);
  287. return 0;
  288. }
  289. $result = chado_select_record('db', array('*'), $sel_values, $sel_options);
  290. }
  291. // if it exists and update is enabled the do the update
  292. elseif ($update) {
  293. $upd_options = array('statement_name' => 'upd_db_nadeurur');
  294. $success = chado_update_record('db', $sel_values, $ins_values, $upd_options);
  295. if (!$success) {
  296. tripal_report_error('tripal_db', TRIPAL_WARNING, "Cannot update db '$dbname'.", NULL);
  297. return 0;
  298. }
  299. $result = chado_select_record('db', array('*'), $sel_values, $sel_options);
  300. }
  301. // return the database object
  302. return $result[0];
  303. }
  304. /**
  305. * Add a database reference
  306. *
  307. * @param $values
  308. * An associative array of the values to be inserted including:
  309. * - db_id: the database_id of the database the reference is from
  310. * - accession: the accession
  311. * - version: (Optional) The version of the database reference
  312. * - description: (Optional) A description of the database reference
  313. *
  314. * @ingroup tripal_db_api
  315. */
  316. function chado_insert_dbxref($values) {
  317. $db_id = $values['db_id'];
  318. $accession = $values['accession'];
  319. $version = (isset($values['version'])) ? $values['version'] : '';
  320. $description = (isset($values['description'])) ? $values['description'] : '';
  321. $ins_values = array(
  322. 'db_id' => $db_id,
  323. 'accession' => $accession,
  324. 'version' => $version,
  325. 'description' => $description
  326. );
  327. // check to see if the dbxref exists
  328. $sel_values = array(
  329. 'db_id' => $db_id,
  330. 'accession' => $accession,
  331. 'version' => $version
  332. );
  333. $result = chado_select_record('dbxref', array('*'), $sel_values);
  334. // if it doesn't already exist then add it
  335. if (!$result) {
  336. $success = chado_insert_record('dbxref', $ins_values);
  337. if (!$success) {
  338. tripal_report_error('tripal_cv', TRIPAL_WARNING, "Failed to insert the dbxref record $accession", NULL);
  339. return 0;
  340. }
  341. $result = chado_select_record('dbxref', array('*'), $sel_values);
  342. }
  343. if (isset($result[0])) {
  344. return $result[0];
  345. }
  346. else {
  347. return FALSE;
  348. }
  349. }
  350. /**
  351. * Add a record to a database reference linking table (ie: feature_dbxref)
  352. *
  353. * @param $basetable
  354. * The base table for which the dbxref should be associated. Thus to associate a dbxref
  355. * with a feature the basetable=feature and dbxref_id is added to the feature_dbxref table
  356. * @param $record_id
  357. * The primary key of the basetable to associate the dbxref with. This should be in integer.
  358. * @param $dbxref
  359. * An associative array describing the dbxref. Valid keys include:
  360. * 'accession' => the accession for the dbxref,
  361. * 'db_name' => the name of the database the dbxref belongs to;
  362. * 'db_id' => the db_id from the databaes table of Chado. Substitutes for 'db_name'
  363. * 'dbxref_id' => the dbxref_id of the dbxref to assocaite. Substitutes for all other keys.
  364. * @param $options
  365. * An associative array of options. Valid keys include:
  366. * - insert_dbxref: Insert the dbxref if it doesn't already exist. TRUE is the default
  367. *
  368. * @ingroup tripal_db_api
  369. */
  370. function chado_associate_dbxref($basetable, $record_id, $dbxref, $options = array()) {
  371. $linking_table = $basetable . '_dbxref';
  372. $foreignkey_name = $basetable . '_id';
  373. // Default Values
  374. $options['insert_dbxref'] = (isset($options['insert_dbxref'])) ? $options['insert_dbxref'] : TRUE;
  375. // If the dbxref_id is set then we know it already exists
  376. // Otherwise, select to check
  377. if (!isset($dbxref['dbxref_id'])) {
  378. $values = array(
  379. 'accession' => $dbxref['accession'],
  380. );
  381. if (isset($dbxref['db_id'])) {
  382. $values['db_id'] = $dbxref['db_id'];
  383. }
  384. elseif (isset($dbxref['db_name'])) {
  385. $values['db_id'] = array(
  386. 'name' => $dbxref['db_name']
  387. );
  388. }
  389. else {
  390. tripal_report_error(
  391. 'tripal_db_api',
  392. TRIPAL_WARNING,
  393. "chado_associate_dbxref: The dbxref needs to have either the db_name or db_id
  394. supplied. You were trying to associate a dbxref with the %base %record_id
  395. and supplied the dbxref values: %dbxref.",
  396. array('%base' => $basetable, '%record_id' => $record_id, '%dbxref' => print_r($dbxref,TRUE))
  397. );
  398. return FALSE;
  399. }
  400. $select = chado_select_record('dbxref',array('*'), $values);
  401. if ($select) {
  402. $dbxref['dbxref_id'] = $select[0]->dbxref_id;
  403. }
  404. elseif ($options['insert_dbxref']) {
  405. // Insert the dbxref
  406. $insert = chado_insert_dbxref($values);
  407. if (isset($insert->dbxref_id)) {
  408. $dbxref['dbxref_id'] = $insert->dbxref_id;
  409. }
  410. else {
  411. tripal_report_error(
  412. 'tripal_db_api',
  413. TRIPAL_WARNING,
  414. "chado_associate_dbxref: Unable to insert the dbxref using the dbxref values: %dbxref.",
  415. array('%dbxref' => print_r($dbxref,TRUE))
  416. );
  417. return FALSE;
  418. }
  419. }
  420. else {
  421. tripal_report_error(
  422. 'tripal_api',
  423. TRIPAL_WARNING,
  424. "chado_associate_dbxref: The dbxref doesn't already exist. You supplied the dbxref values: %dbxref.",
  425. array('%dbxref' => print_r($dbxref,TRUE))
  426. );
  427. return FALSE;
  428. }
  429. }
  430. // Now add the link between the record & dbxref
  431. if ($dbxref['dbxref_id'] > 0) {
  432. $values = array(
  433. 'dbxref_id' => $dbxref['dbxref_id'],
  434. $foreignkey_name => $record_id
  435. );
  436. $result = chado_select_record($linking_table, array('*'), $values);
  437. // if it doesn't already exist then add it
  438. if (!$result) {
  439. $success = chado_insert_record($linking_table, $values);
  440. if (!$success) {
  441. tripal_report_error(
  442. 'tripal_api',
  443. TRIPAL_WARNING,
  444. "Failed to insert the %base record %accession",
  445. array('%base' => $linking_table, '%accession' => $dbxref['accession'])
  446. );
  447. return FALSE;
  448. }
  449. $result = chado_select_record($linking_table, array('*'), $values);
  450. }
  451. if (isset($result[0])) {
  452. return $result[0];
  453. }
  454. else {
  455. return FALSE;
  456. }
  457. }
  458. return FALSE;
  459. }