webservice_course.php 19 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506
  1. <?php
  2. /* For licensing terms, see /license.txt */
  3. /**
  4. * @package chamilo.webservices
  5. */
  6. require_once(dirname(__FILE__).'/../inc/global.inc.php');
  7. $libpath = api_get_path(LIBRARY_PATH);
  8. require_once $libpath.'course.lib.php';
  9. require_once $libpath.'add_course.lib.inc.php';
  10. require_once $libpath.'course_description.lib.php';
  11. require_once(dirname(__FILE__).'/webservice.php');
  12. /**
  13. * Web services available for the Course module. This class extends the WS class
  14. */
  15. class WSCourse extends WS {
  16. /**
  17. * Deletes a course (helper method)
  18. *
  19. * @param string Course id field name
  20. * @param string Course id value
  21. * @return mixed True if the course was successfully deleted, WSError otherwise
  22. */
  23. protected function deleteCourseHelper($course_id_field_name, $course_id_value) {
  24. $course_id = $this->getCourseId($course_id_field_name, $course_id_value);
  25. if($course_id instanceof WSError) {
  26. return $course_id;
  27. } else {
  28. $course_code = CourseManager::get_course_code_from_course_id($course_id);
  29. CourseManager::delete_course($course_code);
  30. return true;
  31. }
  32. }
  33. /**
  34. * Deletes a course
  35. *
  36. * @param string API secret key
  37. * @param string Course id field name
  38. * @param string Course id value
  39. */
  40. public function DeleteCourse($secret_key, $course_id_field_name, $course_id_value) {
  41. $verifKey = $this->verifyKey($secret_key);
  42. if($verifKey instanceof WSError) {
  43. $this->handleError($verifKey);
  44. } else {
  45. $result = $this->deleteCourseHelper($course_id_field_name, $course_id_value);
  46. if($result instanceof WSError) {
  47. $this->handleError($result);
  48. }
  49. }
  50. }
  51. /**
  52. * Deletes multiple courses
  53. *
  54. * @param string API secret key
  55. * @param array Array of courses with elements of the form array('course_id_field_name' => 'name_of_field', 'course_id_value' => 'value')
  56. * @return array Array with elements like array('course_id_value' => 'value', 'result' => array('code' => 0, 'message' => 'Operation was successful')). Note that if the result array contains a code different
  57. * than 0, an error occured
  58. */
  59. public function DeleteCourses($secret_key, $courses) {
  60. $verifKey = $this->verifyKey($secret_key);
  61. if($verifKey instanceof WSError) {
  62. $this->handleError($verifKey);
  63. } else {
  64. $results = array();
  65. foreach($courses as $course) {
  66. $result_tmp = array();
  67. $result_op = $this->deleteCourseHelper($course['course_id_field_name'], $course['course_id_value']);
  68. $result_tmp['course_id_value'] = $course['course_id_value'];
  69. if($result_op instanceof WSError) {
  70. // Return the error in the results
  71. $result_tmp['result'] = $result_op->toArray();
  72. } else {
  73. $result_tmp['result'] = $this->getSuccessfulResult();
  74. }
  75. $results[] = $result_tmp;
  76. }
  77. return $results;
  78. }
  79. }
  80. /**
  81. * Creates a course (helper method)
  82. *
  83. * @param string Title
  84. * @param string Category code
  85. * @param string Wanted code. If it's not defined, it will be generated automatically
  86. * @param string Tutor name
  87. * @param string Course admin user id field name
  88. * @param string Course admin user id value
  89. * @param string Course language
  90. * @param string Course id field name
  91. * @param string Course id value
  92. * @param array Course extra fields
  93. * @return mixed Generated id if creation was successful, WSError otherwise
  94. */
  95. protected function createCourseHelper($title, $category_code, $wanted_code, $tutor_name, $course_admin_user_id_field_name, $course_admin_user_id_value, $language, $course_id_field_name, $course_id_value, $extras) {
  96. // Add the original course id field name and value to the extra fields if needed
  97. $extras_associative = array();
  98. if($course_id_field_name != "chamilo_course_id") {
  99. $extras_associative[$course_id_field_name] = $course_id_value;
  100. }
  101. foreach($extras as $extra) {
  102. $extras_associative[$extra['field_name']] = $extra['field_value'];
  103. }
  104. $course_admin_id = $this->getUserId($course_admin_user_id_field_name, $course_admin_user_id_value);
  105. if($course_admin_id instanceof WSError) {
  106. return $course_admin_id;
  107. }
  108. if($wanted_code == '') {
  109. $wanted_code = generate_course_code($title);
  110. }
  111. $result = create_course($wanted_code, $title, $tutor_name, $category_code, $language, $course_admin_id, $this->_configuration['db_prefix'], 0);
  112. if (!$result) {
  113. return new WSError(202, 'There was an error creating the course');
  114. } else {
  115. // Update extra fields
  116. foreach($extras_associative as $fname => $fvalue) {
  117. CourseManager::update_course_extra_field_value($result, $fname, $fvalue);
  118. }
  119. // Get course id
  120. $course_info = CourseManager::get_course_information($result);
  121. return $course_info['id'];
  122. }
  123. }
  124. /**
  125. * Creates a course
  126. *
  127. * @param string API secret key
  128. * @param string Title
  129. * @param string Category code
  130. * @param string Wanted code. If it's not defined, it will be generated automatically
  131. * @param string Tutor name
  132. * @param string Course admin user id field name
  133. * @param string Course admin user id value
  134. * @param string Course language
  135. * @param string Course id field name
  136. * @param string Course id value
  137. * @param array Course extra fields
  138. * @return int Course id generated
  139. */
  140. public function CreateCourse($secret_key, $title, $category_code, $wanted_code, $tutor_name, $course_admin_user_id_field_name, $course_admin_user_id_value, $language, $course_id_field_name, $course_id_value, $extras) {
  141. // First, verify the secret key
  142. $verifKey = $this->verifyKey($secret_key);
  143. if($verifKey instanceof WSError) {
  144. $this->handleError($verifKey);
  145. } else {
  146. $result = $this->createCourseHelper($title, $category_code, $wanted_code, $tutor_name, $course_admin_user_id_field_name, $course_admin_user_id_value, $language, $course_id_field_name, $course_id_value, $extras);
  147. if($result instanceof WSError) {
  148. $this->handleError($result);
  149. } else {
  150. return $result;
  151. }
  152. }
  153. }
  154. /**
  155. * Create multiple courses
  156. *
  157. * @param string API secret key
  158. * @param array Courses to be created, with elements following the structure presented in CreateCourse
  159. * @return array Array with elements of the form array('course_id_value' => 'original value sent', 'course_id_generated' => 'value_generated', 'result' => array('code' => 0, 'message' => 'Operation was successful'))
  160. */
  161. public function CreateCourses($secret_key, $courses) {
  162. // First, verify the secret key
  163. $verifKey = $this->verifyKey($secret_key);
  164. if($verifKey instanceof WSError) {
  165. $this->handleError($verifKey);
  166. } else {
  167. $results = array();
  168. foreach($courses as $course) {
  169. $result_tmp = array();
  170. // re-initialize variables just in case
  171. $title = $category_code = $wanted_code = $tutor_name = $course_admin_user_id_field_name = $course_admin_user_id_value = $language = $course_id_field_name = $course_id_value = $extras = 0;
  172. extract($course);
  173. $result = $this->createCourseHelper($title, $category_code, $wanted_code, $tutor_name, $course_admin_user_id_field_name, $course_admin_user_id_value, $language, $course_id_field_name, $course_id_value, $extras);
  174. if($result instanceof WSError) {
  175. $result_tmp['result'] = $result->toArray();
  176. $result_tmp['course_id_value'] = $course_id_value;
  177. $result_tmp['course_id_generated'] = 0;
  178. } else {
  179. $result_tmp['result'] = $this->getSuccessfulResult();
  180. $result_tmp['course_id_value'] = $course_id_value;
  181. $result_tmp['course_id_generated'] = $result;
  182. }
  183. $results[] = $result_tmp;
  184. }
  185. return $results;
  186. }
  187. }
  188. /**
  189. * Edits a course (helper method)
  190. *
  191. * @param string Course id field name
  192. * @param string Course id value
  193. * @param string Title
  194. * @param string Category code
  195. * @param string Department name
  196. * @param string Department url
  197. * @param string Course language
  198. * @param int Visibility
  199. * @param int Subscribe (0 = denied, 1 = allowed)
  200. * @param int Unsubscribe (0 = denied, 1 = allowed)
  201. * @param string Visual code
  202. * @param array Course extra fields
  203. * @return mixed True in case of success, WSError otherwise
  204. */
  205. protected function editCourseHelper($course_id_field_name, $course_id_value, $title, $category_code, $department_name, $department_url, $language, $visibility, $subscribe, $unsubscribe, $visual_code, $extras) {
  206. $course_id = $this->getCourseId($course_id_field_name, $course_id_value);
  207. if($course_id instanceof WSError) {
  208. return $course_id;
  209. } else {
  210. $attributes = array();
  211. if(!is_empty($title)) {
  212. $attributes['title'] = $title;
  213. }
  214. if(!is_empty($category_code)) {
  215. $attributes['category_code'] = $category_code;
  216. }
  217. if(!is_empty($department_name)) {
  218. $attributes['department_name'] = $department_name;
  219. }
  220. if(!is_empty($department_url)) {
  221. $attributes['department_url'] = $department_url;
  222. }
  223. if(!is_empty($language)) {
  224. $attributes['course_language'] = $language;
  225. }
  226. if($visibility != '') {
  227. $attributes['visibility'] = (int)$visibility;
  228. }
  229. if($subscribe != '') {
  230. $attributes['subscribe'] = (int)$subscribe;
  231. }
  232. if($unsubscribe != '') {
  233. $attributes['unsubscribe'] = (int)$unsubscribe;
  234. }
  235. if(!is_empty($visual_code)) {
  236. $attributes['visual_code'] = $visual_code;
  237. }
  238. if(!is_empty($attributes)) {
  239. CourseManager::update_attributes($course_id, $attributes);
  240. }
  241. if(!empty($extras)) {
  242. $course_code = CourseManager::get_course_code_from_course_id($course_id);
  243. $extras_associative = array();
  244. foreach($extras as $extra) {
  245. $extras_associative[$extra['field_name']] = $extra['field_value'];
  246. }
  247. foreach($extras_associative as $fname => $fvalue) {
  248. CourseManager::update_extra_field_value($course_code, $fname, $fvalue);
  249. }
  250. }
  251. return true;
  252. }
  253. }
  254. /**
  255. * Edits a course
  256. *
  257. * @param string API secret key
  258. * @param string Course id field name
  259. * @param string Course id value
  260. * @param string Title
  261. * @param string Category code
  262. * @param string Department name
  263. * @param string Department url
  264. * @param string Course language
  265. * @param int Visibility
  266. * @param int Subscribe (0 = denied, 1 = allowed)
  267. * @param int Unsubscribe (0 = denied, 1 = allowed)
  268. * @param string Visual code
  269. * @param array Course extra fields
  270. */
  271. public function EditCourse($secret_key, $course_id_field_name, $course_id_value, $title, $category_code, $department_name, $department_url, $language, $visibility, $subscribe, $unsubscribe, $visual_code, $extras) {
  272. $verifKey = $this->verifyKey($secret_key);
  273. if($verifKey instanceof WSError) {
  274. $this->handleError($verifKey);
  275. } else {
  276. $result = $this->editCourseHelper($course_id_field_name, $course_id_value, $title, $category_code, $department_name, $department_url, $language, $visibility, $subscribe, $unsubscribe, $visual_code, $extras);
  277. if($result instanceof WSError) {
  278. $this->handleError($result);
  279. }
  280. }
  281. }
  282. /**
  283. * List courses
  284. *
  285. * @param string API secret key
  286. * @param string A list of visibility filter we want to apply
  287. * @return array An array with elements of the form ('id' => 'Course internal id', 'code' => 'Course code', 'title' => 'Course title', 'language' => 'Course language', 'visibility' => 'Course visibility',
  288. * 'category_name' => 'Name of the category of the course', 'number_students' => 'Number of students in the course', 'external_course_id' => 'External course id')
  289. */
  290. public function ListCourses($secret_key, $visibility = 'public,public-registered,private,closed') {
  291. $verifKey = $this->verifyKey($secret_key);
  292. if($verifKey instanceof WSError) {
  293. $this->handleError($verifKey);
  294. } else {
  295. $visibilities = split(',',$visibility);
  296. $vis = array('public' => '3', 'public-registered' => '2', 'private' => '1', 'closed' => '0');
  297. foreach ($visibilities as $p => $visibility) {
  298. $visibilities[$p] = $vis[$visibility];
  299. }
  300. $courses_result = array();
  301. $category_names = array();
  302. $courses = CourseManager::get_courses_list();
  303. foreach($courses as $course) {
  304. //skip elements that do not match required visibility
  305. if (!in_array($course['visibility'],$visibilities)) { continue; }
  306. $course_tmp = array();
  307. $course_tmp['id'] = $course['id'];
  308. $course_tmp['code'] = $course['code'];
  309. $course_tmp['title'] = $course['title'];
  310. $course_tmp['language'] = $course['course_language'];
  311. $course_tmp['visibility'] = $course['visibility'];
  312. // Determining category name
  313. if($category_names[$course['category_code']]) {
  314. $course_tmp['category_name'] = $category_names[$course['category_code']];
  315. } else {
  316. $category = CourseManager::get_course_category($course['category_code']);
  317. $category_names[$course['category_code']] = $category['name'];
  318. $course_tmp['category_name'] = $category['name'];
  319. }
  320. // Determining number of students registered in course
  321. $user_list = CourseManager::get_user_list_from_course_code($course['code'], false);
  322. $course_tmp['number_students'] = count($user_list);
  323. // Determining external course id - this code misses the external course id field name
  324. // $course_tmp['external_course_id'] = CourseManager::get_course_extra_field_value($course_field_name, $course['code']);
  325. $courses_result[] = $course_tmp;
  326. }
  327. return $courses_result;
  328. }
  329. }
  330. /**
  331. * Subscribe or unsubscribe user to a course (helper method)
  332. *
  333. * @param string Course id field name. Use "chamilo_course_id" to use internal id
  334. * @param string Course id value.
  335. * @param string User id field name. Use "chamilo_user_id" to use internal id
  336. * @param string User id value
  337. * @param int Set to 1 to subscribe, 0 to unsubscribe
  338. * @param int Status (STUDENT or TEACHER) Used for subscription only
  339. * @return mixed True if subscription or unsubscription was successful, false otherwise
  340. */
  341. protected function changeUserSubscription($course_id_field_name, $course_id_value, $user_id_field_name, $user_id_value, $state, $status = STUDENT) {
  342. $course_id = $this->getCourseId($course_id_field_name, $course_id_value);
  343. if($course_id instanceof WSError) {
  344. return $course_id;
  345. } else {
  346. $user_id = $this->getUserId($user_id_field_name, $user_id_value);
  347. if($user_id instanceof WSError) {
  348. return $user_id;
  349. } else {
  350. $course_code = CourseManager::get_course_code_from_course_id($course_id);
  351. if($state == 0) {
  352. // Unsubscribe user
  353. CourseManager::unsubscribe_user($user_id, $course_code);
  354. return true;
  355. } else {
  356. // Subscribe user
  357. if(CourseManager::subscribe_user($user_id, $course_code, $status)) {
  358. return true;
  359. } else {
  360. return new WSError(203, 'An error occured subscribing to this course');
  361. }
  362. }
  363. }
  364. }
  365. }
  366. /**
  367. * Subscribe user to a course
  368. *
  369. * @param string API secret key
  370. * @param string Course id field name. Use "chamilo_course_id" to use internal id
  371. * @param string Course id value.
  372. * @param string User id field name. Use "chamilo_user_id" to use internal id
  373. * @param string User id value
  374. * @param int Status (1 = Teacher, 5 = Student)
  375. */
  376. public function SubscribeUserToCourse($secret_key, $course_id_field_name, $course_id_value, $user_id_field_name, $user_id_value, $status) {
  377. $verifKey = $this->verifyKey($secret_key);
  378. if($verifKey instanceof WSError) {
  379. $this->handleError($verifKey);
  380. } else {
  381. $result = $this->changeUserSubscription($course_id_field_name, $course_id_value, $user_id_field_name, $user_id_value, 1, $status);
  382. if($result instanceof WSError) {
  383. $this->handleError($result);
  384. }
  385. }
  386. }
  387. /**
  388. * Unsusbscribe user from course
  389. *
  390. * @param string API secret key
  391. * @param string Course id field name. Use "chamilo_course_id" to use internal id
  392. * @param string Course id value.
  393. * @param string User id field name. Use "chamilo_user_id" to use internal id
  394. * @param string User id value
  395. */
  396. public function UnsubscribeUserFromCourse($secret_key, $course_id_field_name, $course_id_value, $user_id_field_name, $user_id_value) {
  397. $verifKey = $this->verifyKey($secret_key);
  398. if($verifKey instanceof WSError) {
  399. $this->handleError($verifKey);
  400. } else {
  401. $result = $this->changeUserSubscription($course_id_field_name, $course_id_value, $user_id_field_name, $user_id_value, 0);
  402. if($result instanceof WSError) {
  403. $this->handleError($result);
  404. }
  405. }
  406. }
  407. /**
  408. * Returns the descriptions of a course, along with their id
  409. *
  410. * @param string API secret key
  411. * @param string Course id field name
  412. * @param string Course id value
  413. * @return array Returns an array with elements of the form ('course_desc_id' => 1, 'course_desc_title' => 'Title', 'course_desc_content' => 'Content')
  414. */
  415. public function GetCourseDescriptions($secret_key, $course_id_field_name, $course_id_value) {
  416. $verifKey = $this->verifyKey($secret_key);
  417. if($verifKey instanceof WSError) {
  418. $this->handleError($verifKey);
  419. } else {
  420. $course_id = $this->getCourseId($course_id_field_name, $course_id_value);
  421. if($course_id instanceof WSError) {
  422. return $course_id;
  423. } else {
  424. // Course exists, get its descriptions
  425. $descriptions = CourseDescription::get_descriptions($course_id);
  426. $results = array();
  427. foreach($descriptions as $description) {
  428. $results[] = array('course_desc_id' => $description->get_description_type(),
  429. 'course_desc_title' => $description->get_title(),
  430. 'course_desc_content' => $description->get_content());
  431. }
  432. return $results;
  433. }
  434. }
  435. }
  436. /**
  437. * Edit course description
  438. *
  439. * @param string API secret key
  440. * @param string Course id field name
  441. * @param string Course id value
  442. * @param int Category id from course description
  443. * @param string Description title
  444. * @param string Course description content
  445. */
  446. public function EditCourseDescription($secret_key, $course_id_field_name, $course_id_value, $course_desc_id, $course_desc_title, $course_desc_content) {
  447. $verifKey = $this->verifyKey($secret_key);
  448. if($verifKey instanceof WSError) {
  449. $this->handleError($verifKey);
  450. } else {
  451. $course_id = $this->getCourseId($course_id_field_name, $course_id_value);
  452. if($course_id instanceof WSError) {
  453. return $course_id;
  454. } else {
  455. // Create the new course description
  456. $cd = new CourseDescription();
  457. $cd->set_description_type($course_desc_id);
  458. $cd->set_title($course_desc_title);
  459. $cd->set_content($course_desc_content);
  460. $cd->set_session_id(0);
  461. // Get course info
  462. $course_info = CourseManager::get_course_information(CourseManager::get_course_code_from_course_id($course_id));
  463. // Check if this course description exists
  464. $descriptions = CourseDescription::get_descriptions($course_id);
  465. $exists = false;
  466. foreach($descriptions as $description) {
  467. if($description->get_description_type() == $course_desc_id) {
  468. $exists = true;
  469. }
  470. }
  471. if (!$exists) {
  472. $cd->set_progress(0);
  473. $cd->insert($course_info['db_name']);
  474. } else {
  475. $cd->update($course_info['db_name']);
  476. }
  477. }
  478. }
  479. }
  480. }