tripal_core.api.inc 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391
  1. <?php
  2. /**
  3. * @file
  4. * The Tripal Core API
  5. *
  6. * This file provides the API needed for all other Tripal and Tripal dependent
  7. * modules.
  8. */
  9. require_once "chado_tables.schema.inc";
  10. // just a temporary function for debugging
  11. function tripal_core_chado_insert_test(){
  12. $ivalues = array(
  13. 'organism_id' => array(
  14. 'genus' => 'Citrus',
  15. 'species' => 'sinensis',
  16. ),
  17. 'name' => 'orange1.1g000034m.g',
  18. 'uniquename' => 'orange1.1g000034m.g7',
  19. 'type_id' => array (
  20. 'cv_id' => array (
  21. 'name' => 'sequence',
  22. ),
  23. 'name' => 'gene',
  24. 'is_obsolete' => 0
  25. ),
  26. );
  27. $umatch = array(
  28. 'organism_id' => array(
  29. 'genus' => 'Citrus',
  30. 'species' => 'sinensis',
  31. ),
  32. 'uniquename' => 'orange1.1g000034m.g7',
  33. 'type_id' => array (
  34. 'cv_id' => array (
  35. 'name' => 'sequence',
  36. ),
  37. 'name' => 'gene',
  38. 'is_obsolete' => 0
  39. ),
  40. );
  41. $uvalues = array(
  42. 'name' => 'orange1.1g000034m.g',
  43. 'type_id' => array (
  44. 'cv_id' => array (
  45. 'name' => 'sequence',
  46. ),
  47. 'name' => 'mRNA',
  48. 'is_obsolete' => 0
  49. ),
  50. );
  51. // $result = tripal_core_chado_insert('feature',$ivalues);
  52. // return "$result->feature_id";
  53. $result = tripal_core_chado_update('feature',$umatch,$uvalues);
  54. return $result;
  55. }
  56. /**
  57. * Provides a generic routine for inserting into any Chado table
  58. *
  59. * Use this function to insert a record into any Chado table. The first
  60. * argument specifies the table for inserting and the second is an array
  61. * of values to be inserted. The array is mutli-dimensional such that
  62. * foreign key lookup values can be specified.
  63. *
  64. * @param $table
  65. * The name of the chado table for inserting
  66. * @param $values
  67. * An associative array containing the values for inserting.
  68. *
  69. * @return
  70. * On success this function returns TRUE. On failure, it returns FALSE.
  71. *
  72. * Example usage:
  73. * @code
  74. * $values = array(
  75. * 'organism_id' => array(
  76. * 'genus' => 'Citrus',
  77. * 'species' => 'sinensis',
  78. * ),
  79. * 'name' => 'orange1.1g000034m.g',
  80. * 'uniquename' => 'orange1.1g000034m.g',
  81. * 'type_id' => array (
  82. * 'cv_id' => array (
  83. * 'name' => 'sequence',
  84. * ),
  85. * 'name' => 'gene',
  86. * 'is_obsolete' => 0
  87. * ),
  88. * );
  89. * $result = tripal_core_chado_insert('feature',$values);
  90. * @endcode
  91. * The above code inserts a record into the feature table. The $values array is
  92. * nested such that the organism is selected by way of the organism_id foreign
  93. * key constraint by specifying the genus and species. The cvterm is also
  94. * specified using its foreign key and the cv_id for the cvterm is nested as
  95. * well.
  96. */
  97. function tripal_core_chado_insert($table,$values){
  98. $insert_values = array();
  99. // get the table description
  100. $chado = tripal_core_get_chado_schema();
  101. $table_desc = $chado[$table];
  102. // iterate through the values array and create a new 'insert_values' array
  103. // that has all the values needed for insert with all foreign relationsihps
  104. // resolved.
  105. foreach($values as $field => $value){
  106. if(is_array($value)){
  107. // select the value from the foreign key relationship for this value
  108. $insert_values[$field] = tripal_core_chado_get_foreign_key($table_desc,$field,$value);
  109. }
  110. else {
  111. $insert_values[$field] = $value;
  112. }
  113. }
  114. // check for violation of any unique constraints
  115. $ukeys = $table_desc['unique keys'];
  116. $ukselect_cols = array();
  117. $ukselect_vals = array();
  118. foreach($ukeys as $name => $fields){
  119. foreach($fields as $index => $field){
  120. // build the arrays for performing a select that will check the contraint
  121. array_push($ukselect_cols,$field);
  122. $ukselect_vals[$field] = $insert_values[$field];
  123. }
  124. // now check the constraint
  125. if(db_fetch_object(tripal_core_chado_select($table,$ukselect_cols,$ukselect_vals))){
  126. watchdog('tripal_core',"Cannot insert duplicate record into $table table: " . print_r($values,1),array(),'WATCHDOG_ERROR');
  127. return false;
  128. }
  129. }
  130. // if trying to insert a field that is the primary key, make sure it also is unique
  131. $pkey = $table_desc['primary key'][0];
  132. if($insert_values[$pkey]){
  133. if(db_fetch_object(tripal_core_chado_select($table,array($pkey),array($pkey => $insert_values[$pkey])))){
  134. watchdog('tripal_core',"Cannot insert duplicate primary key into $table table: " . print_r($values,1),array(),'WATCHDOG_ERROR');
  135. return false;
  136. }
  137. }
  138. // make sure required fields have a value
  139. $fields = $table_desc['fields'];
  140. foreach($fields as $field => $def){
  141. // a field is considered missing if it cannot be null and there is no default
  142. // value for it or it is of type 'serial'
  143. if($def['not null'] == 1 and !$insert_values[$field] and !$def['default'] and strcmp($def['type'],serial)!=0){
  144. watchdog('tripal_core',"Field $field cannot be null: " . print_r($values,1),array(),'WATCHDOG_ERROR');
  145. return false;
  146. }
  147. }
  148. // Now build the insert SQL statement
  149. $ifields = array();
  150. $ivalues = array();
  151. $itypes = array();
  152. foreach ($insert_values as $field => $value){
  153. array_push($ifields,$field);
  154. array_push($ivalues,$value);
  155. if(strcmp($fields[$field]['type'],'serial')==0 or
  156. strcmp($fields[$field]['type'],'int')==0){
  157. array_push($itypes,"%d");
  158. } else {
  159. array_push($itypes,"'%s'");
  160. }
  161. }
  162. $sql = "INSERT INTO {$table} (" . implode(", ",$ifields) . ") VALUES (". implode(", ",$itypes) .")";
  163. // finally perform the insert.
  164. if(db_query($sql,$ivalues)){
  165. return true;
  166. }
  167. else {
  168. watchdog('tripal_core',"Cannot insert record into $table table: " . print_r($values,1),array(),'WATCHDOG_ERROR');
  169. return false;
  170. }
  171. return false;
  172. }
  173. /**
  174. *
  175. */
  176. function tripal_core_chado_update($table,$match,$values){
  177. $update_values = array(); // contains the values to be updated
  178. $update_matches = array(); // contains the values for the where clause
  179. // get the table description
  180. $chado = tripal_core_get_chado_schema();
  181. $table_desc = $chado[$table];
  182. // get the values needed for matching in the SQL statement
  183. foreach ($match as $field => $value){
  184. if(is_array($value)){
  185. $update_matches[$field] = tripal_core_chado_get_foreign_key($table_desc,$field,$value);
  186. }
  187. else {
  188. $update_matches[$field] = $value;
  189. }
  190. }
  191. // get the values used for updating
  192. foreach ($values as $field => $value){
  193. if(is_array($value)){
  194. $update_values[$field] = tripal_core_chado_get_foreign_key($table_desc,$field,$value);
  195. }
  196. else {
  197. $update_values[$field] = $value;
  198. }
  199. }
  200. // now build the SQL statement
  201. $sql = "UPDATE {$table} SET ";
  202. $fields = $table_desc['fields'];
  203. $uargs = array();
  204. foreach($update_values as $field => $value){
  205. if(strcmp($fields[$field]['type'],'serial')==0 or
  206. strcmp($fields[$field]['type'],'int')==0){
  207. $sql .= " $field = %d, ";
  208. } else {
  209. $sql .= " $field = '%s', ";
  210. }
  211. array_push($uargs,$value);
  212. }
  213. $sql = substr($sql,0,-2); // get rid of the trailing comma & space
  214. $sql .= " WHERE ";
  215. foreach($update_matches as $field => $value){
  216. if(strcmp($fields[$field]['type'],'serial')==0 or
  217. strcmp($fields[$field]['type'],'int')==0){
  218. $sql .= " $field = %d AND ";
  219. } else {
  220. $sql .= " $field = '%s' AND ";
  221. }
  222. array_push($uargs,$value);
  223. }
  224. $sql = substr($sql,0,-4); // get rid of the trailing 'AND'
  225. // finally perform the update. If successful, return the updated record
  226. if(db_query($sql,$uargs)){
  227. return true;
  228. }
  229. else {
  230. watchdog('tripal_core',"Cannot update record in $table table. Match:" . print_r($match,1) . ". Values: ". print_r($values,1),array(),'WATCHDOG_ERROR');
  231. return false;
  232. }
  233. return false;
  234. }
  235. /**
  236. * Provides a generic routine for selecting data from a Chado table
  237. *
  238. * Use this function to perform a simple select from any Chado table.
  239. *
  240. * @param $table
  241. * The name of the chado table for inserting
  242. * @param $columns
  243. * An array of column names
  244. * @param $values
  245. * An associative array containing the values for filtering the results.
  246. *
  247. * @return
  248. * A database query result resource, or FALSE if the query was not executed
  249. * correctly.
  250. *
  251. * Example usage:
  252. * @code
  253. * $columns = array('feature_id','name');
  254. * $values = array(
  255. * 'organism_id' => array(
  256. * 'genus' => 'Citrus',
  257. * 'species' => 'sinensis',
  258. * ),
  259. * 'uniquename' => 'orange1.1g000034m.g',
  260. * 'type_id' => array (
  261. * 'cv_id' => array (
  262. * 'name' => 'sequence',
  263. * ),
  264. * 'name' => 'gene',
  265. * 'is_obsolete' => 0
  266. * ),
  267. * );
  268. * $result = tripal_core_chado_select('feature',$columns,$values);
  269. * @endcode
  270. * The above code selects a record from the feature table using the three fields
  271. * that uniquely identify a feature. The $columns array simply lists the columns
  272. * to select. The $values array is nested such that the organism is identified by
  273. * way of the organism_id foreign key constraint by specifying the genus and
  274. * species. The cvterm is also specified using its foreign key and the cv_id
  275. * for the cvterm is nested as well.
  276. */
  277. function tripal_core_chado_select($table,$columns,$values){
  278. // get the table description
  279. $chado = tripal_core_get_chado_schema();
  280. $table_desc = $chado[$table];
  281. $select = '';
  282. $from = '';
  283. $where = '';
  284. $args = array();
  285. foreach($values as $field => $value){
  286. $select[] = $field;
  287. if(is_array($value)){
  288. // select the value from the foreign key relationship for this value
  289. $where[$field] = tripal_core_chado_get_foreign_key($table_desc,$field,$value);
  290. }
  291. else {
  292. $where[$field] = $value;
  293. }
  294. }
  295. // now build the SQL select statement
  296. $sql = "SELECT " . implode(',',$columns) . " ";
  297. $sql .= "FROM {$table} ";
  298. $sql .= "WHERE ";
  299. foreach($where as $field => $value){
  300. $sql .= "$field = '%s' AND ";
  301. $args[] = $value;
  302. }
  303. $sql = substr($sql,0,-4); // get rid of the trailing 'AND'
  304. return db_query($sql,$args);
  305. }
  306. /**
  307. * Gets the value of a foreign key relationship
  308. *
  309. * This function is used by tripal_core_chado_select, tripal_core_chado_insert,
  310. * and tripal_core_chado_update to iterate through the associate array of
  311. * values that gets passed to each of those routines. The values array
  312. * is nested where foreign key contraints are used to specify a value that. See
  313. * documentation for any of those functions for further information.
  314. *
  315. * @param $table_desc
  316. * A table description in Drupal Schema API format for the table with the
  317. * foreign key relationship that needs to be identified.
  318. * @param $field
  319. * The field in the table that is the foreign key.
  320. * @param $values
  321. * An associative array containing the values
  322. *
  323. * @return
  324. * A string containg the results of the foreign key lookup, or FALSE if
  325. * failed.
  326. *
  327. * Example usage:
  328. * @code
  329. *
  330. * $values = array(
  331. * 'genus' => 'Citrus',
  332. * 'species' => 'sinensis',
  333. * );
  334. * $value = tripal_core_chado_get_foreign_key('feature','organism_id',$values);
  335. *
  336. * @endcode
  337. * The above code selects a record from the feature table using the three fields
  338. * that uniquely identify a feature. The $columns array simply lists the columns
  339. * to select. The $values array is nested such that the organism is identified by
  340. * way of the organism_id foreign key constraint by specifying the genus and
  341. * species. The cvterm is also specified using its foreign key and the cv_id
  342. * for the cvterm is nested as well.
  343. */
  344. function tripal_core_chado_get_foreign_key($table_desc,$field,$values){
  345. // get the list of foreign keys for this table description and
  346. // iterate through those until we find the one we're looking for
  347. $fkeys = $table_desc['foreign keys'];
  348. if($fkeys){
  349. foreach($fkeys as $name => $def){
  350. $table = $def['table'];
  351. $columns = $def['columns'];
  352. // iterate through the columns of the foreign key relationship
  353. foreach($columns as $left => $right){
  354. // does the left column in the relationship match our field?
  355. if(strcmp($field,$left)==0){
  356. // the column name of the foreign key matches the field we want
  357. // so this is the right relationship. Now we want to select
  358. $select_cols = array($right);
  359. $result = db_fetch_object(tripal_core_chado_select($table,$select_cols,$values));
  360. return $result->$right;
  361. }
  362. }
  363. }
  364. }
  365. else {
  366. // TODO: what do we do if we get to this point and we have a fk
  367. // relationship expected but we don't have any definition for one in the
  368. // table schema??
  369. }
  370. return false;
  371. }