TripalWebService.inc 27 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748
  1. <?php
  2. class TripalWebService {
  3. // --------------------------------------------------------------------------
  4. // EDITABLE STATIC CONSTANTS
  5. //
  6. // The following constants SHOULD be set for each descendent class. They are
  7. // used by the static functions to provide information to Drupal about
  8. // the field and it's default widget and formatter.
  9. // --------------------------------------------------------------------------
  10. /**
  11. * The human-readable label for this web service.
  12. */
  13. public static $label = 'Base WebService';
  14. /**
  15. * A bit of text to describe what this service provides.
  16. */
  17. public static $description = 'This is the base class for Tripal web services as is not meant to be used on it\'s own';
  18. /**
  19. * A machine-readable type for this service. This name must be unique
  20. * among all Tripal web services and is used to form the URL to access
  21. * this service.
  22. */
  23. public static $type = 'services';
  24. // --------------------------------------------------------------------------
  25. // PROTECTED CLASS MEMBERS -- DO NOT OVERRIDE
  26. // --------------------------------------------------------------------------
  27. /**
  28. * The resource that will be returned by the webservice given the
  29. * arguments provided. This is a private
  30. */
  31. protected $resource;
  32. /**
  33. * An array containing the elements of the URL path. Each level of the
  34. * URL appears in a separate element of the array. The service type and
  35. * version are automatically removed from the array.
  36. */
  37. protected $path;
  38. /**
  39. * The set of paramters provided to the sesrvice. These are the values
  40. * that would occur in a URL after the question mark in an HTTP GET or
  41. * the data items of an HTTP POST.
  42. */
  43. protected $params;
  44. /**
  45. * The URL at which Tripal web services are found. This is used
  46. * for creating the IRI for resources.
  47. */
  48. protected $base_path;
  49. /**
  50. * The list of documented classes used by this service. For the web service
  51. * to be discoverable all of the entity classes and their collections
  52. * must be defined.
  53. */
  54. protected $documentation;
  55. // --------------------------------------------------------------------------
  56. // CONSTRUCTORS
  57. // --------------------------------------------------------------------------
  58. /**
  59. * Implements the constructor.
  60. */
  61. public function __construct($base_path) {
  62. if (!$base_path) {
  63. throw new Exception('Please provide a $base_path argument when creating a new TripalWebService.');
  64. }
  65. // Create a default resource so that the service always some something.
  66. $this->resource = new TripalWebServiceResource($base_path);
  67. // Intialize the private members variables.
  68. $this->path = [];
  69. $this->params = [];
  70. $this->base_path = $base_path;
  71. $this->documentation = [];
  72. $this->addDocClass([
  73. "id" => "http://www.w3.org/ns/hydra/core#Resource",
  74. "term" => 'hydra:Resource',
  75. "title" => "Resource",
  76. 'subClassOf' => NULL,
  77. ]);
  78. }
  79. // --------------------------------------------------------------------------
  80. // OVERRIDEABLE FUNCTIONS
  81. // --------------------------------------------------------------------------
  82. /**
  83. * Responds to the request argument provided to the service.
  84. *
  85. * This function should be implemented by a TripalWebService child class.
  86. *
  87. */
  88. public function handleRequest() {
  89. // TODO: make sure the $this->path and $this->params are set before
  90. // continuing.
  91. }
  92. // --------------------------------------------------------------------------
  93. // CLASS FUNCTIONS -- DO NOT OVERRIDE
  94. // --------------------------------------------------------------------------
  95. /**
  96. * Sets the URL path for the resource being called.
  97. *
  98. * @param $path
  99. * An array containing the elements of the URL path. Each level of the
  100. * URL appears in a separate element of the array. The service type and
  101. * version are automatically removed from the array. For example, a
  102. * URL of the type http://localhost/web-services/content/v0.1/Gene/sequence
  103. * will result in a $path array containing the following:
  104. *
  105. * @code
  106. * array(
  107. * 'Gene',
  108. * 'sequence',
  109. * );
  110. * @endcode
  111. *
  112. * @param unknown $path
  113. */
  114. public function setPath($path) {
  115. $this->path = $path;
  116. }
  117. /**
  118. * Sets the parameters for the resource.
  119. *
  120. * @param $params
  121. * The set of paramters provided to the sesrvice. These are the values
  122. * that would occur in a URL after the question mark in an HTTP GET or
  123. * the data items of an HTTP POST.
  124. */
  125. public function setParams($params) {
  126. $this->params = $params;
  127. }
  128. /**
  129. * Retrieves the version number for this web service.
  130. *
  131. * Each web service must have version number built into the name of the
  132. * class. The version number appears at the end of the class name, begins
  133. * with a lower-case 'v' and is followed by two numbers (major and minor) that
  134. * are separated by an underscore. This function identifies the version
  135. * from the class name and returns it here in a human-readable format.
  136. *
  137. * @param $sanitize
  138. * Set to TRUE to convert the period to underscore.
  139. *
  140. * @return
  141. * The version number for this web service.
  142. */
  143. public function getVersion($sanitize = FALSE) {
  144. $class = get_class($this);
  145. $major_version = '';
  146. $minor_version = '';
  147. if (preg_match('/v(\d+)_(\d+)$/', $class, $matches)) {
  148. $major_version = $matches[1];
  149. $minor_version = $matches[2];
  150. if ($sanitize) {
  151. return 'v' . $major_version . '_' . $minor_version;
  152. }
  153. return 'v' . $major_version . '.' . $minor_version;
  154. }
  155. return '';
  156. }
  157. /**
  158. * Retrieves the context section of the response.
  159. *
  160. * The JSON-LD response constists of two sections the '@context' section
  161. * and the data section. This function only returns the context section
  162. * of the response.
  163. *
  164. * @return
  165. * An associative array containing the context section of the response.
  166. */
  167. public function getContext() {
  168. return $this->resource->getContext();
  169. }
  170. /**
  171. * Returns the full web service response.
  172. *
  173. * The response includes both the @context and data sections of the
  174. * JSON-LD response.
  175. *
  176. * @return
  177. * An associative array containing that can be converted to JSON.
  178. */
  179. public function getResponse() {
  180. $class = get_called_class();
  181. $context_filename = $class::$type . '.' . $this->getVersion(TRUE);
  182. foreach ($this->path as $element) {
  183. $context_filename .= '.' . $element;
  184. }
  185. $context_filename .= '.json';
  186. $context_filename = strtolower($context_filename);
  187. $context_dir = 'public://tripal/ws/context';
  188. $context_file_path = $context_dir . '/' . $context_filename;
  189. // Make sure the user directory exists
  190. if (!file_prepare_directory($context_dir, FILE_CREATE_DIRECTORY)) {
  191. throw new Exception('Could not access the tripal/ws/context directory on the server for storing web services context files.');
  192. }
  193. $context = $this->resource ? $this->resource->getContext() : [];
  194. $context = [
  195. '@context' => $context,
  196. ];
  197. $cfh = fopen($context_file_path, "w");
  198. if (flock($cfh, LOCK_EX)) {
  199. fwrite($cfh, json_encode($context));
  200. flock($cfh, LOCK_UN);
  201. fclose($cfh);
  202. }
  203. else {
  204. throw new Exception(t('Error locking file: @file.', ['@file' => $context_file_path]));
  205. }
  206. $fid = db_select('file_managed', 'fm')
  207. ->fields('fm', ['fid'])
  208. ->condition('uri', $context_file_path)
  209. ->execute()
  210. ->fetchField();
  211. // Save the context file so Drupal can manage it and remove the file later.
  212. if (!$fid) {
  213. $context_file = new stdClass();
  214. $context_file->uri = $context_file_path;
  215. $context_file->filename = $context_filename;
  216. $context_file->filemime = 'application/ld+json';
  217. $context_file->uid = 0;
  218. file_save($context_file);
  219. }
  220. $type = $this->resource ? $this->resource->getType() : 'unknown';
  221. $json_ld = [
  222. '@context' => file_create_url($context_file_path),
  223. '@id' => '',
  224. '@type' => $type,
  225. ];
  226. $data = $this->getData();
  227. return array_merge($json_ld, $data);
  228. }
  229. /**
  230. * Retrieves the service URL for this service.
  231. */
  232. public function getServicePath() {
  233. $class = get_class($this);
  234. $version = $this->getVersion();
  235. $type = $class::$type;
  236. return $this->base_path . '/' . $type . '/' . $version;
  237. }
  238. /**
  239. * Retrieves the data section of the response.
  240. *
  241. * The JSON-LD response constists of two sections the '@context' section
  242. * and the data section. This function only returns the data section
  243. * of the response.
  244. *
  245. * @return
  246. * An associative array containing the data section of the response.
  247. */
  248. public function getData() {
  249. if ($this->resource) {
  250. return $this->resource->getData();
  251. }
  252. return [];
  253. }
  254. /**
  255. * Sets the resource to be returned by this web service.
  256. *
  257. * @param $resource .
  258. * An implementation of a TripalWebServiceResource.
  259. */
  260. public function setResource($resource) {
  261. // Make sure the $service provides is a TripalWebService class.
  262. if (!is_a($resource, 'TripalWebServiceResource')) {
  263. throw new Exception("Cannot add a new resource to this web service as it is not a TripalWebServiceResource.");
  264. }
  265. $this->resource = $resource;
  266. }
  267. /**
  268. * Set an error for the service.
  269. *
  270. * @param $message
  271. * The error message to report.
  272. */
  273. public function setError($message) {
  274. $this->resource = new TripalWebServiceResource($this->base_path);
  275. $this->resource->setID('error');
  276. $this->resource->addContextItem('error', 'rdfs:error');
  277. $this->resource->setType('error');
  278. $this->resource->addProperty('error', $message);
  279. }
  280. /**
  281. * Retrieves an array contining the supported classes.
  282. *
  283. * Supported classe are resources provided by this web services and the
  284. * operations supported by those classes.
  285. *
  286. * @return
  287. * An array of TripalWebServiceResource objects that follow the Hydra
  288. * documentation for documenting supported classes.
  289. */
  290. public function getDocumentation() {
  291. return $this->documentation;
  292. }
  293. /**
  294. * Defines an entity class for the web services.
  295. *
  296. * A class defines a resource including information about its properties
  297. * and the actions that can be performed. Each class as a unique @id,
  298. * title, type and description. The $details parameter is used to provide
  299. * this information. Additionally, a resource may support Create, Read
  300. * Update and Delete (CRUD) operations. Those are defined using the
  301. * $ops argument. Finally, resources may have properties (or fields). These
  302. * properties should be defined using the $props arugment.
  303. *
  304. * @param $details .
  305. * An array of key/value pairs providing the details for the class. Valid
  306. * keys include:
  307. * - id: The unique IRI for this class.
  308. * - term: the accession for the term for this class.
  309. * - title: The title for the resource that this Class represents.
  310. * - description: (Optional). A description of the resource.
  311. * - subClassOf: (Optional). If this class is a subclass of another
  312. * class then the value should be the @id of the parent class. This
  313. * defaults to hydra:Resource. If no subClass is desired, set it
  314. * to NULL.
  315. * - type: (Optional). Indicates the type of class. Defaults to
  316. * hydra:Class
  317. * @param $ops
  318. * If the resource supports CRUD functionality then those functions should
  319. * be defined using this argument. This is an associative array with
  320. * the following keys: GET, POST, PUT, DELETE. These keys, if provided,
  321. * indicate that a resource of this type can be retrieved (GET),
  322. * created (POST), updated (PUT) or deleted (DELETE). The value for each
  323. * key should be an associative array that supports the following keys:
  324. * = type: the @id that determines the type of operation. This type
  325. * should be specific to the resource, and it need not be a term
  326. * from a real vocabulary. Use the '_:' prefix for the term. For
  327. * example, for an 'Event' resource with a GET method, an appropriate
  328. * type would be '_:event_retrieve'.
  329. * - label: A label that describes the operation in the
  330. * context of the resource.
  331. * - description: A description for the operation. Can be set to NULL
  332. * for no description.
  333. * - expects: The information expected by the Web API.
  334. * - returns: The @id of a Class that will be returned by
  335. * the operation. Set to NULL if there is no return value.
  336. * - statusCodes: An array of status codes that could be returned when
  337. * an error occurs. Each element of the array is an associative
  338. * array with two key/value pairs: 'code' and 'description'. Set the
  339. * 'code' to be the HTTP code that can be returned on error and the
  340. * 'description' to an error message appropriate for the error. For
  341. * example an HTTP 404 error means "Not Found". You can sepecify this
  342. * code and provide a description appropriate for the method and
  343. * class.
  344. * @param $props .
  345. * Defines the list of properties that the resource provides. This is an
  346. * array of properties where each property is an associative array
  347. * containing the following keys:
  348. * - type: The @id of the type of property. Alternatively, this can
  349. * be an instance of a TripalWebServiceResource when the property
  350. * must support operations such as a property of type hydra:Link.
  351. * - title: (Optional). The human-readable title of this property. If
  352. * this key is absent then the title will be set to the term's title.
  353. * - description: (Optional). A short description of this property. If
  354. * this key is absent then the description will be set to the term's
  355. * description.
  356. * - required: Set to TRUE to indicate if this property is a required
  357. * field when creating a new resource.
  358. * - readable: Set to TRUE to indicate that the client can retrieve the
  359. * property's value?
  360. * altered by an update.
  361. * - writeable: Set to TRUE if the client can alter the value of the
  362. * property.
  363. * - domain: the @id of the rdfs:domain.
  364. * - range: the @id of the rdfs:range.
  365. */
  366. protected function addDocClass($details = [], $ops = [], $props = []) {
  367. $supported_class = new TripalWebServiceResource($this->getServicePath());
  368. // Add the context which all classes will need
  369. $supported_class->addContextItem('description', 'rdfs:comment');
  370. $supported_class->addContextItem('subClassOf', 'hydra:subClassOf');
  371. $supported_class->addContextItem('description', 'rdfs:comment');
  372. $supported_class->addContextItem('label', 'rdfs:label');
  373. // Set the Class ID.
  374. $class_id = $details['id'];
  375. $accession = $details['term'];
  376. if ($accession != $class_id) {
  377. $supported_class->addContextItem($accession, $class_id);
  378. }
  379. $supported_class->setID($accession);
  380. // Set the class Type.
  381. if (array_key_exists('type', $details)) {
  382. $supported_class->setType($details['type']);
  383. }
  384. else {
  385. $supported_class->setType('hydra:Class');
  386. }
  387. // Set title and description.
  388. $supported_class->addProperty('hydra:title', $details['title']);
  389. $supported_class->addProperty('hydra:description', array_key_exists('description', $details) ? $details['description'] : NULL);
  390. // Set the sub class.
  391. if (array_key_exists('subClassOf', $details)) {
  392. if ($details['subClassOf']) {
  393. $supported_class->addProperty('subClassOf', $details['subClassOf']);
  394. }
  395. }
  396. else {
  397. $supported_class->addProperty('subClassOf', 'hydra:Resource');
  398. }
  399. // Now add the supported operations.
  400. $class_ops = [];
  401. foreach ($ops as $op => $op_details) {
  402. $class_ops[] = $this->generateDocClassOp($supported_class, $op, $op_details);
  403. }
  404. $supported_class->addContextItem('supportedOperation', 'hydra:supportedOperation');
  405. $supported_class->addProperty('supportedOperation', $class_ops);
  406. // Now add in the supported proprerties.
  407. $class_props = [];
  408. foreach ($props as $prop) {
  409. $class_props[] = $this->generateDocClassProp($supported_class, $prop);
  410. }
  411. $supported_class->addContextItem('supportedProperty', 'hydra:supportedProperty');
  412. $supported_class->addProperty('supportedProperty', $class_props);
  413. $this->documentation[] = $supported_class;
  414. }
  415. /**
  416. * A helper function for the addClass() function for generating a property.
  417. */
  418. private function generateDocClassProp($supported_class, $prop) {
  419. $supported_class->addContextItem('property', [
  420. "@id" => "hydra:property",
  421. "@type" => "@id",
  422. ]);
  423. $supported_class->addContextItem('domain', [
  424. "@id" => "rdfs:domain",
  425. "@type" => "@id",
  426. ]);
  427. $supported_class->addContextItem('range', [
  428. "@id" => "rdfs:range",
  429. "@type" => "@id",
  430. ]);
  431. $supported_class->addContextItem('readable', 'hydra:readable');
  432. $supported_class->addContextItem('writeable', 'hydra:writeable');
  433. $supported_class->addContextItem('required', 'hydra:required');
  434. $supported_class->addContextItem('tripal_formatters', 'tripal:tripal_formatters');
  435. $class_prop = [
  436. 'property' => $prop['type'],
  437. 'hydra:title' => $prop['title'],
  438. 'hydra:description' => array_key_exists('description', $prop) ? $prop['description'] : NULL,
  439. 'required' => array_key_exists('required', $prop) ? $prop['required'] : NULL,
  440. 'readable' => array_key_exists('readonly', $prop) ? $prop['readonly'] : NULL,
  441. 'writeable' => array_key_exists('writeonly', $prop) ? $prop['writeonly'] : NULL,
  442. ];
  443. if (array_key_exists('domain', $prop)) {
  444. $class_prop['domain'] = $prop['domain'];
  445. }
  446. if (array_key_exists('range', $prop)) {
  447. $class_prop['range'] = $prop['range'];
  448. }
  449. if (array_key_exists('operations', $prop)) {
  450. $class_prop['supportedOperation'] = [];
  451. foreach ($prop['operations'] as $op => $op_details) {
  452. $class_prop['supportedOperation'][] = $this->generateOp($supported_class, $op, $op_details);
  453. }
  454. }
  455. if (array_key_exists('tripal_formatters', $prop)) {
  456. $class_prop['tripal_formatters'] = array_keys($prop['tripal_formatters']);
  457. }
  458. return $class_prop;
  459. }
  460. /**
  461. * A helper function for the addClass() function for generating an operation.
  462. */
  463. private function generateDocClassOp($supported_class, $op, $op_details) {
  464. if ($op != 'GET' and $op != 'PUT' and $op != 'DELETE' and $op != 'POST') {
  465. throw new Exception(t('The method, @method, provided to the TripalWebService::addClass function is not an oppropriate operations.', ['@method' => $op]));
  466. }
  467. if (!array_key_exists('type', $op_details)) {
  468. throw new Exception(t('Please provide a type in the operations array passed to the TripalWebService::addClass() function: @details', ['@details' => print_r($op_details, TRUE)]));
  469. }
  470. if (!array_key_exists('label', $op_details)) {
  471. throw new Exception(t('Please provide a label in the operations array passed to the TripalWebService::addClass() function: @details', ['@details' => print_r($op_details, TRUE)]));
  472. }
  473. $class_op = new TripalWebServiceResource($this->base_path);
  474. $class_op->setID($op_details['type']);
  475. switch ($op) {
  476. case 'GET':
  477. $class_op->setType('hydra:Operation');
  478. break;
  479. case 'POST':
  480. $class_op->setType('http://schema.org/AddAction');
  481. break;
  482. case 'DELETE':
  483. $class_op->setType('http://schema.org/DeleteAction');
  484. break;
  485. case 'PUT':
  486. $class_op->setType('http://schema.org/UpdateAction');
  487. break;
  488. }
  489. $class_op->addContextItem('method', 'hydra:method');
  490. $class_op->addContextItem('label', 'rdfs:label');
  491. $class_op->addContextItem('description', 'rdfs:comment');
  492. $class_op->addContextItem('expects', [
  493. "@id" => "hydra:expects",
  494. "@type" => "@id",
  495. ]);
  496. $class_op->addContextItem('returns', [
  497. "@id" => "hydra:returns",
  498. "@type" => "@id",
  499. ]);
  500. $class_op->addContextItem('statusCodes', 'hydra:statusCodes');
  501. $class_op->addContextItem('code', 'hydra:statusCode');
  502. $class_op->addProperty('method', $op);
  503. $class_op->addProperty('label', array_key_exists('label', $op_details) ? $op_details['label'] : 'Retrieves an instance of this resource');
  504. $class_op->addProperty('description', array_key_exists('description', $op_details) ? $op_details['description'] : NULL);
  505. $status_codes = array_key_exists('statusCodes', $op_details) ? $op_details['statusCodes'] : [];
  506. foreach ($status_codes as $code) {
  507. if (array_key_exists('code', $code) and array_key_exists('description', $code)) {
  508. $class_op->addProperty('statusCodes', $code);
  509. }
  510. else {
  511. throw new Exception(t('The status code provided to TripalWebService::addClass function is improperly formatted @code.', ['@code' => print_r($code, TRUE)]));
  512. }
  513. }
  514. if (count($status_codes) == 0) {
  515. $class_op->addProperty('statusCodes', []);
  516. }
  517. $class_op->addProperty('expects', array_key_exists('expects', $op_details) ? $op_details['expects'] : NULL);
  518. $class_op->addProperty('returns', array_key_exists('returns', $op_details) ? $op_details['returns'] : ' "http://www.w3.org/2002/07/owl#Nothing",');
  519. return $class_op;
  520. }
  521. /**
  522. * Converts a term array into an value appropriate for an @id or @type.
  523. *
  524. * @param $term
  525. * The term array.
  526. * @param $santize
  527. * An array of keywords indicating how to santize the key. By default,
  528. * no sanitizing occurs. The two valid types are 'lowercase', and 'spacing'
  529. * where 'lowercase' converts the term name to all lowercase and
  530. * 'spacing' replaces any spaces with underscores.
  531. *
  532. * @return
  533. * The id (the term name but with spaces replaced with underscores).
  534. */
  535. protected function getContextTerm($term, $sanitize = []) {
  536. if (!$term) {
  537. $backtrace = debug_backtrace();
  538. throw new Exception('getContextTerm: Please provide a non NUll or non empty $term.');
  539. }
  540. if (!$term['name']) {
  541. throw new Exception('getContextTerm: The provided term does not have a name: ' . print_r($term, TRUE));
  542. }
  543. $key = $term['name'];
  544. $key_adj = $key;
  545. if (in_array('spacing', $sanitize)) {
  546. $key_adj = preg_replace('/ /', '_', $key_adj);
  547. }
  548. if (in_array('lowercase', $sanitize)) {
  549. $key_adj = strtolower($key_adj);
  550. }
  551. return $key_adj;
  552. }
  553. /**
  554. * Adds a term to the '@context' section for a given resource.
  555. *
  556. * @param $resource
  557. * A TripalWebServiceResource instance.
  558. * @param $term
  559. * The term array.
  560. * @param $santize
  561. * An array of keywords indicating how to santize the key. By default,
  562. * no sanitizing occurs. The two valid types are 'lowercase', and 'spacing'
  563. * where 'lowercase' converts the term name to all lowercase and
  564. * 'spacing' replaces any spaces with underscores.
  565. *
  566. * @return
  567. * The id (the term name but with spaces replaced with underscores).
  568. */
  569. protected function addContextTerm($resource, $term, $sanitize = []) {
  570. if (!is_a($resource, 'TripalWebServiceResource')) {
  571. throw new Exception('addContextTerm: Please provide a $resource of type TripalWebServiceResource.');
  572. }
  573. if (!$term) {
  574. $backtrace = debug_backtrace();
  575. throw new Exception('addContextTerm: Please provide a non NUll or non empty $term.');
  576. }
  577. if (!$term['name']) {
  578. throw new Exception('addContextTerm: The provided term does not have a name: ' . print_r($term, TRUE));
  579. }
  580. // Make sure the vocab is present
  581. $vocab = $term['vocabulary'];
  582. $this->addContextVocab($resource, $vocab);
  583. // Sanitize the term key
  584. $key_adj = $this->getContextTerm($term, $sanitize);
  585. // Create the compact IRI
  586. $compact_iri = $vocab['short_name'] . ':' . $term['accession'];
  587. // If the full naming is indicated in the service parameters then
  588. // set the full name of the keys to include the vocab short name.
  589. if (array_key_exists('full_keys', $this->params)) {
  590. //$key_adj = $vocab['short_name'] . ':' . $key_adj;
  591. }
  592. $iri = $term['url'];
  593. $resource->addContextItem($key_adj, $compact_iri);
  594. $resource->addContextItem($compact_iri, $iri);
  595. return $key_adj;
  596. }
  597. /**
  598. * Adds a vocabulary to the '@context' section for a given resource.
  599. *
  600. * @param $resource
  601. * A TripalWebServiceResource instance.
  602. * @param $vocab
  603. * The vocabulary array.
  604. */
  605. protected function addContextVocab($resource, $vocab) {
  606. if (!is_a($resource, 'TripalWebServiceResource')) {
  607. throw new Exception('addContextVocab: Please provide a $resource of type TripalWebServiceResource.');
  608. }
  609. $key = $vocab['short_name'];
  610. // The URL here should be the URL prefix not the database home
  611. // page. But unfortunately, the URL prefix can't be guaranteed to be
  612. // a true prefix. Not all databases place by the rules. For this reason,
  613. // we can never use JSON-LD compact IRIs. :-(
  614. $iri = $vocab['sw_url'];
  615. $resource->addContextItem($key, $iri);
  616. }
  617. /**
  618. * Adds a key/value property to the given resource.
  619. *
  620. * @param $resource
  621. * A TripalWebServiceResource instance.
  622. * @param $term
  623. * The term array for the key.
  624. * @param $value
  625. * The value to add.
  626. * @param $santize
  627. * An array of keywords indicating how to santize the key. By default,
  628. * no sanitizing occurs. The two valid types are 'lowercase', and 'spacing'
  629. * where 'lowercase' converts the term name to all lowercase and
  630. * 'spacing' replaces any spaces with underscores.
  631. *
  632. * @return $key
  633. * The key (the term name but with spaces replaced with underscores).
  634. */
  635. public function addResourceProperty($resource, $term, $value, $sanitize = []) {
  636. if (!is_a($resource, 'TripalWebServiceResource')) {
  637. throw new Exception('addProperty: Please provide a $resource of type TripalWebServiceResource.');
  638. }
  639. // First add the term
  640. $key = $this->addContextTerm($resource, $term, $sanitize);
  641. // Then add the property.
  642. $resource->addProperty($key, $value);
  643. }
  644. /**
  645. * Sets the type for the given resource.
  646. *
  647. * The type exist in the context of the web service.
  648. *
  649. * @param $resource
  650. * A TripalWebServiceResource instance.
  651. * @param $type
  652. * The type
  653. * @param $santize
  654. * An array of keywords indicating how to santize the key. By default,
  655. * no sanitizing occurs. The two valid types are 'lowercase', and 'spacing'
  656. * where 'lowercase' converts the term name to all lowercase and
  657. * 'spacing' replaces any spaces with underscores.
  658. */
  659. public function setResourceType($resource, $term, $sanitize = ['spacing']) {
  660. if (!is_a($resource, 'TripalWebServiceResource')) {
  661. throw new Exception('addProperty: Please provide a $resource of type TripalWebServiceResource.');
  662. }
  663. // First add the term
  664. $key = $this->addContextTerm($resource, $term, $sanitize);
  665. // Then set the type
  666. $resource->setType($key);
  667. }
  668. }