tripal_chado.stock.api.inc 7.3 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230
  1. <?php
  2. /**
  3. * @file
  4. * Provides API functions specificially for managing stock
  5. * records in Chado.
  6. */
  7. /**
  8. * @defgroup tripal_stock_api Chado Stock
  9. * @ingroup tripal_chado_api
  10. * @{
  11. * Provides API functions specificially for managing stock
  12. * records in Chado. The stock table of Chado is used for storing a variety
  13. * of data types besides just stocks from a stock collection. Examples of
  14. * other records commonly stored in the stock table are germplasm and
  15. * individuals from a breeding population.
  16. * @}
  17. */
  18. /**
  19. * Retrieves a chado stock variable
  20. *
  21. * @param $identifier
  22. * An array with the key stating what the identifier is. Supported keys (only
  23. * one of the following unique keys is required):
  24. * - stock_id: the chado stock.stock_id primary key
  25. * - nid: the drupal nid of the stock
  26. * There are also some specially handled keys. They are:
  27. * - property: An array/object describing the property to select records for.
  28. * It should at least have either a type_name (if unique across cvs) or
  29. * type_id. Other supported keys include: cv_id/cv_name (of the type),
  30. * value and rank
  31. * @param $options
  32. * An array of options. Supported keys include:
  33. * - Any keys supported by chado_generate_var(). See that function
  34. * definition for additional details.
  35. *
  36. * NOTE: the $identifier parameter can really be any array similar to $values
  37. * passed into chado_select_record(). It should fully specify the stock record
  38. * to be returned.
  39. *
  40. * @return
  41. * If unique values were passed in as an identifier then an object describing
  42. * the stock will be returned (will be a chado variable from
  43. * chado_generate_var()). Otherwise, FALSE will be returned.
  44. *
  45. * @ingroup tripal_stock_api
  46. */
  47. function chado_get_stock($identifiers, $options = array()) {
  48. // Set Defaults.
  49. if (!isset($options['include_fk'])) {
  50. // Tells chado_generate_var to only expand 1 level.
  51. $options['include_fk'] = array('type_id' => TRUE, 'dbxref_id' => TRUE);
  52. }
  53. // Error Checking of parameters.
  54. if (!is_array($identifiers)) {
  55. tripal_report_error(
  56. 'tripal_stock_api',
  57. TRIPAL_ERROR,
  58. "chado_get_stock: The identifier passed in is expected to be an array with the key
  59. matching a column name in the stock table (ie: stock_id or name). You passed in %identifier.",
  60. array(
  61. '%identifier'=> print_r($identifiers, TRUE)
  62. )
  63. );
  64. }
  65. elseif (empty($identifiers)) {
  66. tripal_report_error(
  67. 'tripal_stock_api',
  68. TRIPAL_ERROR,
  69. "chado_get_stock: You did not pass in anything to identify the stock you want. The identifier
  70. is expected to be an array with the key matching a column name in the stock table
  71. (ie: stock_id or name). You passed in %identifier.",
  72. array(
  73. '%identifier'=> print_r($identifiers, TRUE)
  74. )
  75. );
  76. }
  77. // If one of the identifiers is property then use
  78. // chado_get_record_with_property().
  79. if (isset($identifiers['property'])) {
  80. $property = $identifiers['property'];
  81. unset($identifiers['property']);
  82. $stock = chado_get_record_with_property(
  83. array('table' => 'stock', 'base_records' => $identifiers),
  84. array('type_name' => $property),
  85. $options
  86. );
  87. }
  88. // Else we have a simple case and we can just use chado_generate_var to get
  89. // the stock.
  90. else {
  91. // Try to get the stock.
  92. $stock = chado_generate_var(
  93. 'stock',
  94. $identifiers,
  95. $options
  96. );
  97. }
  98. // Ensure the stock is singular. If it's an array then it is not singular.
  99. if (is_array($stock)) {
  100. tripal_report_error(
  101. 'tripal_stock_api',
  102. TRIPAL_ERROR,
  103. "chado_get_stock: The identifiers you passed in were not unique. You passed in %identifier.",
  104. array(
  105. '%identifier'=> print_r($identifiers, TRUE)
  106. )
  107. );
  108. }
  109. // Report an error if $stock is FALSE since then chado_generate_var has failed.
  110. elseif ($stock === FALSE) {
  111. tripal_report_error(
  112. 'tripal_stock_api',
  113. TRIPAL_ERROR,
  114. "chado_get_stock: chado_generate_var() failed to return a stock based on the identifiers
  115. you passed in. You should check that your identifiers are correct, as well as, look
  116. for a chado_generate_var error for additional clues. You passed in %identifier.",
  117. array(
  118. '%identifier'=> print_r($identifiers, TRUE)
  119. )
  120. );
  121. }
  122. // Else, as far we know, everything is fine so give them their stock :)
  123. else {
  124. return $stock;
  125. }
  126. }
  127. /**
  128. * Retrieves a chado stock variable.
  129. *
  130. * @param $identifier
  131. * An array with the key stating what the identifier is. Supported keys
  132. * include any field in the stock table. See the chado_select_record() $values
  133. * parameter for additional details including an example.
  134. * @param $options
  135. * An array of options. Supported keys include:
  136. * - Any keys supported by chado_generate_var(). See that function
  137. * definition for additional details.
  138. *
  139. * @return
  140. * An array of stock objects matching the criteria.
  141. *
  142. * @ingroup tripal_stock_api
  143. */
  144. function chado_get_multiple_stocks($identifiers, $options = array()) {
  145. // Set Defaults.
  146. if (!isset($options['include_fk'])) {
  147. // Tells chado_generate_var to only expand 1 level.
  148. $options['include_fk'] = array('type_id' => TRUE, 'dbxref_id' => TRUE);
  149. }
  150. // Error Checking of parameters.
  151. if (!is_array($identifiers)) {
  152. tripal_report_error(
  153. 'tripal_stock_api',
  154. TRIPAL_ERROR,
  155. "chado_get_stock: The identifier passed in is expected to be an array with the key
  156. matching a column name in the stock table (ie: stock_id or name). You passed in %identifier.",
  157. array(
  158. '%identifier'=> print_r($identifiers, TRUE)
  159. )
  160. );
  161. }
  162. elseif (empty($identifiers)) {
  163. tripal_report_error(
  164. 'tripal_stock_api',
  165. TRIPAL_ERROR,
  166. "chado_get_stock: You did not pass in anything to identify the stock you want. The identifier
  167. is expected to be an array with the key matching a column name in the stock table
  168. (ie: stock_id or name). You passed in %identifier.",
  169. array(
  170. '%identifier'=> print_r($identifiers, TRUE)
  171. )
  172. );
  173. }
  174. // If one of the identifiers is property then use
  175. // chado_get_record_with_property().
  176. if (isset($identifiers['property'])) {
  177. $property = $identifiers['property'];
  178. unset($identifiers['property']);
  179. $stock = chado_get_record_with_property(
  180. array('table' => 'stock', 'base_records' => $identifiers),
  181. array('type_name' => $property),
  182. $options
  183. );
  184. }
  185. // Else we have a simple case and we can just use chado_generate_var to get
  186. //the stock.
  187. else {
  188. // Try to get the stock.
  189. $stock = chado_generate_var(
  190. 'stock',
  191. $identifiers,
  192. $options
  193. );
  194. }
  195. // Report an error if $stock is FALSE since then chado_generate_var has failed.
  196. if ($stock === FALSE) {
  197. tripal_report_error(
  198. 'tripal_stock_api',
  199. TRIPAL_ERROR,
  200. "chado_get_stock: chado_generate_var() failed to return a stock based on the identifiers
  201. you passed in. You should check that your identifiers are correct, as well as, look
  202. for a chado_generate_var error for additional clues. You passed in %identifier.",
  203. array(
  204. '%identifier'=> print_r($identifiers, TRUE)
  205. )
  206. );
  207. }
  208. // Else, as far we know, everything is fine so give them their stock :)
  209. else {
  210. return $stock;
  211. }
  212. }