MDL-37247 mod_forum: adding webservice function to allow for the retrieval of forum...
[moodle.git] / mod / forum / externallib.php
CommitLineData
2b9fe87d
MN
1<?php
2
3// This file is part of Moodle - http://moodle.org/
4//
5// Moodle is free software: you can redistribute it and/or modify
6// it under the terms of the GNU General Public License as published by
7// the Free Software Foundation, either version 3 of the License, or
8// (at your option) any later version.
9//
10// Moodle is distributed in the hope that it will be useful,
11// but WITHOUT ANY WARRANTY; without even the implied warranty of
12// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13// GNU General Public License for more details.
14//
15// You should have received a copy of the GNU General Public License
16// along with Moodle. If not, see <http://www.gnu.org/licenses/>.
17
18/**
19 * External forum API
20 *
21 * @package mod_forum
22 * @copyright 2012 Mark Nelson <markn@moodle.com>
23 * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
24 */
25
26defined('MOODLE_INTERNAL') || die;
27
28require_once("$CFG->libdir/externallib.php");
29
30class mod_forum_external extends external_api {
31
32 /**
33 * Describes the parameters for get_forum
34 *
35 * @return external_external_function_parameters
36 * @since Moodle 2.5
37 */
38 public static function get_forums_by_courses_parameters() {
39 return new external_function_parameters (
40 array(
41 'courseids' => new external_multiple_structure(new external_value(PARAM_INT, 'course ID',
42 '', VALUE_REQUIRED, '', NULL_NOT_ALLOWED), 'Array of course IDs', VALUE_DEFAULT, array()),
43 )
44 );
45 }
46
47 /**
48 * Returns a list of forums in a provided list of courses,
49 * if no list is provided all forums that the user can view
50 * will be returned.
51 *
52 * @param array $courseids the course ids
53 * @return array the forum details
54 * @since Moodle 2.5
55 */
56 public static function get_forums_by_courses($courseids = array()) {
57 global $CFG, $DB, $USER;
58
59 require_once($CFG->dirroot . "/mod/forum/lib.php");
60
61 if (empty($courseids)) {
62 // Get all the courses the user can view.
63 $courseids = array_keys(enrol_get_my_courses());
64 } else {
65 $params = self::validate_parameters(self::get_forums_by_courses_parameters(), array('courseids' => $courseids));
66 $courseids = $params['courseids'];
67 }
68
69 // Array to store the forums to return.
70 $arrforums = array();
71
72 // Go through the courseids and return the forums.
73 if (!empty($courseids)) {
74 // Keep track of the course ids we have performed a require_course_login check on to avoid repeating.
75 $arrcourseschecked = array();
76 // Convert array to string to use in query.
77 list($subsql, $params) = $DB->get_in_or_equal($courseids);
78 $sql = "SELECT *
79 FROM {forum}
80 WHERE course $subsql";
81 if ($forums = $DB->get_records_sql($sql, $params)) {
82 foreach ($forums as $forum) {
83 // Check that that user can view this course if check not performed yet.
84 if (!in_array($forum->course, $arrcourseschecked)) {
85 // Get the course context.
86 $context = context_course::instance($forum->course);
87 // Check the user can function in this context.
88 self::validate_context($context);
89 // Add to the array.
90 $arrcourseschecked[] = $forum->course;
91 }
92 // Get the course module.
93 $cm = get_coursemodule_from_instance('forum', $forum->id, 0, false, MUST_EXIST);
94 // Get the module context.
95 $context = context_module::instance($cm->id);
96 // Check they have the view forum capability.
97 require_capability('mod/forum:viewdiscussion', $context);
98 // Format the intro before being returning using the format setting.
99 list($forum->intro, $forum->introformat) = external_format_text($forum->intro, $forum->introformat,
100 $context->id, 'mod_forum', 'intro', 0);
101 // Add the course module id to the object, this information is useful.
102 $forum->cmid = $cm->id;
103 // Add the forum to the array to return.
104 $arrforums[$forum->id] = (array) $forum;
105 }
106 }
107 }
108
109 return $arrforums;
110 }
111
112 /**
113 * Describes the get_forum return value
114 *
115 * @return external_single_structure
116 * @since Moodle 2.5
117 */
118 public static function get_forums_by_courses_returns() {
119 return new external_multiple_structure(
120 new external_single_structure(
121 array(
122 'id' => new external_value(PARAM_INT, 'Forum id'),
123 'course' => new external_value(PARAM_TEXT, 'Course id'),
124 'type' => new external_value(PARAM_TEXT, 'The forum type'),
125 'name' => new external_value(PARAM_TEXT, 'Forum name'),
126 'intro' => new external_value(PARAM_RAW, 'The forum intro'),
127 'introformat' => new external_format_value('intro'),
128 'assessed' => new external_value(PARAM_INT, 'Aggregate type'),
129 'assesstimestart' => new external_value(PARAM_INT, 'Assess start time'),
130 'assesstimefinish' => new external_value(PARAM_INT, 'Assess finish time'),
131 'scale' => new external_value(PARAM_INT, 'Scale'),
132 'maxbytes' => new external_value(PARAM_INT, 'Maximum attachment size'),
133 'maxattachments' => new external_value(PARAM_INT, 'Maximum number of attachments'),
134 'forcesubscribe' => new external_value(PARAM_INT, 'Force users to subscribe'),
135 'trackingtype' => new external_value(PARAM_INT, 'Subscription mode'),
136 'rsstype' => new external_value(PARAM_INT, 'RSS feed for this activity'),
137 'rssarticles' => new external_value(PARAM_INT, 'Number of RSS recent articles'),
138 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
139 'warnafter' => new external_value(PARAM_INT, 'Post threshold for warning'),
140 'blockafter' => new external_value(PARAM_INT, 'Post threshold for blocking'),
141 'blockperiod' => new external_value(PARAM_INT, 'Time period for blocking'),
142 'completiondiscussions' => new external_value(PARAM_INT, 'Student must create discussions'),
143 'completionreplies' => new external_value(PARAM_INT, 'Student must post replies'),
144 'completionposts' => new external_value(PARAM_INT, 'Student must post discussions or replies'),
145 'cmid' => new external_value(PARAM_INT, 'Course module id')
146 ), 'forum'
147 )
148 );
149 }
150}