This function is confusing, pointless and buggy (passing wrong args to format_text etc) because it was originally added to get all the student grades from the course, but was incorrectly implemented so that it A) exposed hidden grades to students (now nerfed by adding a capability check to view hidden grades, which means that students cannot access this function) B) Only returns grades for activities and the course - no categories or manual items.
It cannot be fixed properly to return manual grade items and category items, because the return signature has hardcoded "activityid" and not "gradeitemid" and already existing hacks to insert the word "course" in the activityid response.
A proper useful function to retrieve student grades would be great - it would need https://tracker.moodle.org/browse/MDL-50582 to land first.
Do we have a good deprecation process for web service functions?
If this was a Moodle internal API, we would
- Implement the new function / class / whatever API change.
- Modify the old functions so that using them causes a warning message.
- Announce in the release notes for that Moodle release that the old API is now deprecated.
- A few Moodle releases later, remove the old API.
- Announce in the release notes for that Moodle release that the old API is now gone.
That is a good system. Can we come up with an equivalent for web service APIs?
The only place I can think of to put the warning message is in the PHP logs on the Moodle server, and they are highly likely to not be seen. However, I hope there is a better option that I have failed to think of.
We have deprecated webservices before - but usually with a replacement because they were wrongly named etc.
The way this was done previously was just through the description of the method in the db/services.php which is shown in the webservices api documentation pages.
E.g. "DEPRECATED: this deprecated function will be removed in a future version. This function has been renamed as core_webservice_get_site_info()"
The way this was done previously was just through the description of the method in the db/services.php which is shown in the webservices api documentation pages.
E.g. "DEPRECATED: this deprecated function will be removed in a future version. This function has been renamed as core_webservice_get_site_info()"
And the reason I raised it is because I saw the code and it looked bonkers, so I spent 20 mins writing a unit test to prove it was bonkers, then went to create an issue, but found several issues already saying it was bonkers but closed as "wont fix".
Well, it definitely looks like we should deprecate this function, and create a non-bonkers function that does the job right.
+1 to remove that function
As an alternative, I implemented this function: https://github.com/moodle/moodle/blob/MOODLE_29_STABLE/grade/report/user/externallib.php#L64 to retrieve the gradebook for users.
Note that this function rely in the report API, the information returned is not ready to be treated by external SIS but it's useful if you want to build a visual representation of the user gradebook.
Regards, Juan