added a comment - - edited
Oki, so we decided to assume that all texts will be html by default. From http://docs.moodle.org/dev/How_to_contribute_a_web_service_function_to_core :
- description/summary/textfields are commonly HTML. They are check against PARAM_CLEANHTML and there is no need to send a text format attribut. However don't forget to call format_text() when returning a text field.
NP with that at all. But that implies that:
1) On input (insert/update), they must be checked against PARAM_CLEANHTML.
2) The corresponding format field will be, always = FORMAT_HTML
3) On output (select), it needs to be prepared (to support files over WS) and then processed by format_text() (to apply filters and clean HTML).
4) format_text() must NOT be used on input, only on output.
The only point I cannot agree is about the need to use PARAM_CLEANHTML (point 1), when we always and everywhere have been delegating the cleaning to output (point 3). More yet, users with perms given to execute those webservices are trusted 100%. I only see the PARAM_CLEANHTML type to process some contents allowing HTML that, later, are not processed by format_text() but by (lighter) format_string(), like happens with activity names and other few strings.
So, I would:
A) Recommend to change the Docs about how to support text contents. I may agree it can be assumed all them will be HTML format, np with that at all. Then, I'd detail a bit more both the input and output "rules" like:
- Use PARAM_RAW
- Never use format_text() nor any other formatting option. it causes filters and other things to be processed.
- Set the corresponding xxxformat to FORMAT_HTML always
B) Change this issue to observe the "rules" of correct text processing.
I'm happy if we discuss the A) point above in HQ if needed. But using PARAM_CLEANHTML + format_text() on input seems to be an incorrect combination 100%. So I'm reopening this again until it gets 100% agreed and documented.
Edited to add one point about filtering from HQ chat.
Edited to add another point about cleaning from HQ chat.