While discussing the export to ZIP bug ( Bug 1013022 ) I realized that $USER->can_view_artefact() does not do what I thought it did. I thought that it was like can_view_view(), i.e. it was an easy way to tell whether a particular user is allowed to see the contents of a particular artefact.
But it does not mean that, as evidenced by the fact that it's not accessed at all on the artefact detail page, view/artefact.php. Instead, this function refers to whether or not the user should be able to see the artefact in their own or a group's Content area.
The reason it exists and has this name, is because of the group files permissions system (see http://manual.mahara.org/en/1.8/groups/inside_group.html#index-16 ). This defines three permission levels for a file: "View" lets you see the page in Contents and use it in Group pages, "Edit" lets you change the file's metadata, and "Publish" lets you use the file in your own Portfolio pages.
Anyway, I misunderstood it as doing the same thing as can_view_view(), which checks whether a particular user can see a particular Page in display-mode. The similar functionality for artefacts, as seen on view/artefact.php, is to provide an artefact ID & a page ID, and to check whether the artefact is in the page and the user can view the page.
Also, while implementing fixes to Bug 1211758 and Bug 1236636 (where we weren't validating artefact ownership before putting artefacts into blocks), we universally used $USER-> can_edit_ artefact( ) to check whether a user had the right to put an artefact into a block. We *should* have been using $USER-> can_view_ artefact( ) or $USER-> can_publish_ artefact( ) in nearly every one of these cases.
In fact, this has caused a notable regression. Currently, if I set a file to "view" permission only, then as a group member I see the file in the file picker, but receive an error when I try to select it.
This will also be tricky to implement, because knowing whether you need to use $USER-> can_view_ artefact( ) or $USER-> can_publish_ artefact( ) is dependent upon whether the Page is your own or a Group's.