MDL-37684 - phpunit add missing definitions to phpunit.xml.dist
[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
0c246ae5 72 // Ensure there are courseids to loop through.
2b9fe87d 73 if (!empty($courseids)) {
0c246ae5
MN
74 // Go through the courseids and return the forums.
75 foreach ($courseids as $cid) {
76 // Get the course context.
77 $context = context_course::instance($cid);
78 // Check the user can function in this context.
79 self::validate_context($context);
80 // Get the forums in this course
81 if ($forums = $DB->get_records('forum', array('course' => $cid))) {
82 // Get the modinfo for the course.
83 $modinfo = get_fast_modinfo($cid);
84 // If modinfo returns no forum instances, set it to empty array.
85 if (!isset($modinfo->instances['forum'])) {
86 $modinfo->instances['forum'] = array();
87 }
88 // Loop through the courses returned by modinfo.
89 foreach ($modinfo->instances['forum'] as $forumid => $cm) {
90 // If it is not visible or present in the forums get_records call, continue.
91 if (!$cm->uservisible || !isset($forums[$forumid])) {
92 continue;
93 }
94 // Set the forum object.
95 $forum = $forums[$forumid];
0c246ae5
MN
96 // Get the module context.
97 $context = context_module::instance($cm->id);
98 // Check they have the view forum capability.
99 require_capability('mod/forum:viewdiscussion', $context);
100 // Format the intro before being returning using the format setting.
101 list($forum->intro, $forum->introformat) = external_format_text($forum->intro, $forum->introformat,
102 $context->id, 'mod_forum', 'intro', 0);
103 // Add the course module id to the object, this information is useful.
104 $forum->cmid = $cm->id;
105 // Add the forum to the array to return.
106 $arrforums[$forum->id] = (array) $forum;
2b9fe87d 107 }
2b9fe87d
MN
108 }
109 }
110 }
111
112 return $arrforums;
113 }
114
115 /**
116 * Describes the get_forum return value
117 *
118 * @return external_single_structure
119 * @since Moodle 2.5
120 */
121 public static function get_forums_by_courses_returns() {
122 return new external_multiple_structure(
123 new external_single_structure(
124 array(
125 'id' => new external_value(PARAM_INT, 'Forum id'),
126 'course' => new external_value(PARAM_TEXT, 'Course id'),
127 'type' => new external_value(PARAM_TEXT, 'The forum type'),
128 'name' => new external_value(PARAM_TEXT, 'Forum name'),
129 'intro' => new external_value(PARAM_RAW, 'The forum intro'),
130 'introformat' => new external_format_value('intro'),
131 'assessed' => new external_value(PARAM_INT, 'Aggregate type'),
132 'assesstimestart' => new external_value(PARAM_INT, 'Assess start time'),
133 'assesstimefinish' => new external_value(PARAM_INT, 'Assess finish time'),
134 'scale' => new external_value(PARAM_INT, 'Scale'),
135 'maxbytes' => new external_value(PARAM_INT, 'Maximum attachment size'),
136 'maxattachments' => new external_value(PARAM_INT, 'Maximum number of attachments'),
137 'forcesubscribe' => new external_value(PARAM_INT, 'Force users to subscribe'),
138 'trackingtype' => new external_value(PARAM_INT, 'Subscription mode'),
139 'rsstype' => new external_value(PARAM_INT, 'RSS feed for this activity'),
140 'rssarticles' => new external_value(PARAM_INT, 'Number of RSS recent articles'),
141 'timemodified' => new external_value(PARAM_INT, 'Time modified'),
142 'warnafter' => new external_value(PARAM_INT, 'Post threshold for warning'),
143 'blockafter' => new external_value(PARAM_INT, 'Post threshold for blocking'),
144 'blockperiod' => new external_value(PARAM_INT, 'Time period for blocking'),
145 'completiondiscussions' => new external_value(PARAM_INT, 'Student must create discussions'),
146 'completionreplies' => new external_value(PARAM_INT, 'Student must post replies'),
147 'completionposts' => new external_value(PARAM_INT, 'Student must post discussions or replies'),
148 'cmid' => new external_value(PARAM_INT, 'Course module id')
149 ), 'forum'
150 )
151 );
152 }
153}