I am trying to prepare myself for 1.7, but can't see its logic. Please help clearing this out:
Roles and capabilities - MoodleDocs;
"Definitions
* A role is an identifier of the user's status in some context, for example teacher, student and forum moderator.
* A capability is a description of a particular Moodle feature, for example moodle/blog:create. Capabilities are associated with roles.
* A permission is a value that is assigned for a capability for a particular role, for example allow or prevent.
* A context is ...."
http://docs.moodle.org/en/Roles
But in "Add a new role"
domain.td/admin/roles/manage.php?action=add
the roles called LEGACY* are listed together with capabilities. So when are they capabilities and when are they roles?
Another thing is that I can not find a definition of these LEGACY roles. It could be lack of English understanding but I am really not sure. What is it that makes them different from user defined roles if they are not capabilities? And what is it that seem to make them both capabilities AND roles?
I asked the same thing in the Moodle Docs comment page, didn't get an answer so I'm joining your query:
What are the legacy capabilities for?
I've been reading the Roles documentation, and my a lot of work going on in here! Keep it up! I might be understanding something incorrectly as I can't figure out what the legacy capabilities are for? I thought that Roles are sets of capabilities. There might/should be Roles for all of the "legacy roles", which would then have the default set of capabilities matching the capabilities in 1.6. What are the "legacy capabilities" then? --Samuli Karevaara 07:27, 1 September 2006 (CDT)
In some places it seems that the role system is a bit too clever for it's own good... at least it seems to be more clever than me
I will attempt to answer this topic since it has gone unanswered for so long. I am lacking some of the details of understanding myself...so go easy on me!
First off: Before Moodle 1.7 there were only several fixed roles. Each user was either an Admin, Course Creator, Teacher, Non-editing Teacher, Student or a Guest. One of the key enhancements of Moodle 1.7 was to allow users to have different abilities depending upon where they were in Moodle.
Now, let me reword the previous sentence but using Moodle terminology...
One of the key enhancements of Moodle 1.7 was to allow users to have different abilities CAPABILITIES depending upon where they were their CONTEXT in Moodle.
To handle all of these various capabilities, Moodle also implements something called ROLES. Roles are aggregates of many capabilities. The next thing done was to create Moodle Roles that behaved as much like the old moodle user types as possible. So they created the roles of Admin, Course Creator, Teacher, Non-editing Teacher, Student, and Guest. Since one of Moodle's goals all along has been to be upgradable, they also had to handle upgrading lots of code that was designed to work with the 'old way' of doing things. So they implemented several special capabilities, the LEGACY* capabilities. These aren't Roles, but rather capabilities that are used to handle backwards compatibility within different areas of Moodle. So, for instance, the LEGACY ROLE: Teacher (editing) will have all of the capabilities that an editing teacher had in Moodle 1.6. Keep in mind that in Moodle 1.6 there was no concept of CONTEXT...so if you were an editing teacher, you were an editing teacher throughout. With Moodle 1.7 you can be an editing teacher in one course, a non-editing teacher in another course, and a Student in a third course. Each of those courses would be a CONTEXT. These legacy roles ease the bridge for developers between a non-context Moodle and a context based Moodle.
I believe it's the expectation that Moodle will be weaned off of the LEGACY capabilities over the course of a few Moodle releases.
As I'm reading back over this I'm not sure I have explained it very well, and I don't know for certain that I have captured the reason for the legacy roles completely or correctly. I hope (as always) that somebody else can expand on the topic.
Greg.
First off: Before Moodle 1.7 there were only several fixed roles. Each user was either an Admin, Course Creator, Teacher, Non-editing Teacher, Student or a Guest. One of the key enhancements of Moodle 1.7 was to allow users to have different abilities depending upon where they were in Moodle.
Now, let me reword the previous sentence but using Moodle terminology...
One of the key enhancements of Moodle 1.7 was to allow users to have different abilities CAPABILITIES depending upon where they were their CONTEXT in Moodle.
To handle all of these various capabilities, Moodle also implements something called ROLES. Roles are aggregates of many capabilities. The next thing done was to create Moodle Roles that behaved as much like the old moodle user types as possible. So they created the roles of Admin, Course Creator, Teacher, Non-editing Teacher, Student, and Guest. Since one of Moodle's goals all along has been to be upgradable, they also had to handle upgrading lots of code that was designed to work with the 'old way' of doing things. So they implemented several special capabilities, the LEGACY* capabilities. These aren't Roles, but rather capabilities that are used to handle backwards compatibility within different areas of Moodle. So, for instance, the LEGACY ROLE: Teacher (editing) will have all of the capabilities that an editing teacher had in Moodle 1.6. Keep in mind that in Moodle 1.6 there was no concept of CONTEXT...so if you were an editing teacher, you were an editing teacher throughout. With Moodle 1.7 you can be an editing teacher in one course, a non-editing teacher in another course, and a Student in a third course. Each of those courses would be a CONTEXT. These legacy roles ease the bridge for developers between a non-context Moodle and a context based Moodle.
I believe it's the expectation that Moodle will be weaned off of the LEGACY capabilities over the course of a few Moodle releases.
As I'm reading back over this I'm not sure I have explained it very well, and I don't know for certain that I have captured the reason for the legacy roles completely or correctly. I hope (as always) that somebody else can expand on the topic.
Greg.
Thanks for your description of legacy roles, roles, capabilities, and context. Just a point of clarification, I think in Moodle 1.6 there was an element of context with regards to roles. You could be an editing teacher of one course and a non-editing teacher of another course and even a student of a third course. However, within that course there was no real flexibility and the capabilities that one had could not vary. So you could not have a teacher's assistant to help post assignments without also giving that person the right to edit grades or make any change that you the editing teacher might have. I see legacy roles as default roles that are defined in ways that behaved like the static roles did prior to 1.7. They provide an introduction in to some of the more common roles that folks actually use.
I got this far in my thinking as well, but still it feels like an unnecessary hack to have legacy capabilities. My current understanding is that the legacy capabilities were introduced mostly (maybe only) to accomodate the legacy functions like isadmin(), iscreator() etc. so that third-party modules/block/customisations can still call these functions in 1.7.
Currently isadmin() says
$context = get_context_instance(CONTEXT_SYSTEM, SITEID);
return has_capability('moodle/legacy:admin', $context, $userid, false);
As there are also "legacy roles", my first thought was that "why isn't this:
return has_role('admin', $context, $userid, false);
or something similar?"
Ok, it makes sense that there are no permission checks against roles, just against capabilities. Still, I would've done isadmin() with something like
$context = get_context_instance(CONTEXT_SYSTEM, SITEID);
return has_capability('moodle/site:doanything', $context, $userid, false);
and similar constructs for the others. (iscreator(): "moodle/course:create" etc.)
Then the roles could be just "default roles" instead of legacy roles. And their permissions would be set to mimic those of 1.6, for obvious legacy/backwards compatibility reasons. Then only the functions would be "legacy stuff", and deprecated as they are now.
I'm still thinking that I might be missing something about how the roles, the related capabilities, capability inheritance and the rest of the role engine works, as I get puzzled by the legacy capabilities every once in a while when working with the roles code.
Edit: Also, I realised, the roles are customisable so the legacy roles that are there by default might be removed later by the user, breaking the isadmin() if it's done with has_role() (this function doesn't exist, and shouldn't, I know).
Currently isadmin() says
$context = get_context_instance(CONTEXT_SYSTEM, SITEID);
return has_capability('moodle/legacy:admin', $context, $userid, false);
As there are also "legacy roles", my first thought was that "why isn't this:
return has_role('admin', $context, $userid, false);
or something similar?"
Ok, it makes sense that there are no permission checks against roles, just against capabilities. Still, I would've done isadmin() with something like
$context = get_context_instance(CONTEXT_SYSTEM, SITEID);
return has_capability('moodle/site:doanything', $context, $userid, false);
and similar constructs for the others. (iscreator(): "moodle/course:create" etc.)
Then the roles could be just "default roles" instead of legacy roles. And their permissions would be set to mimic those of 1.6, for obvious legacy/backwards compatibility reasons. Then only the functions would be "legacy stuff", and deprecated as they are now.
I'm still thinking that I might be missing something about how the roles, the related capabilities, capability inheritance and the rest of the role engine works, as I get puzzled by the legacy capabilities every once in a while when working with the roles code.
Edit: Also, I realised, the roles are customisable so the legacy roles that are there by default might be removed later by the user, breaking the isadmin() if it's done with has_role() (this function doesn't exist, and shouldn't, I know).
I am having a lot of grief getting a custom module to work with the code in this area. In my case I have a clean 1.7.1 install and database, with my old 1.6-based module installed which is using calls to isadmin(). In this instance, isadmin() (or more accurately has_capability('moodle/legacy:admin', $context, $userid, false)) is returning null so my module is broken, so now I have to go through the new Moodle code in question to try to figure out what is going on 
I guess when you change something as fundamental as user roles in a system as widely used as Moodle then you are always going to throw up unforeseen errors, I would imagine that other module designers are going to have similiar issues in this area.
Ok just to follow on here, if we look at the code in the depreciated isadmin() function (found in lib/deprecatedlib.php), it is returning the following:
return has_capability('moodle/legacy:admin', $context, $userid, false);
For me as I described previously, this call is returning a null value, which is odd because that function is supossed to return a Boolean value. The fourth parameter being passed to has_capability is called $doanything and defaults to true, but this is being overridden with a value of false in the call from isadmin() (why?). This is odd behaviour because the admin of a site will have the doanything capability by default (check under the "Allowed to do everything" capabilty on the role permissions admin screen).
What I have done to get past this problem with my module is to change the $doanything parameter to true in the call from isadmin(), so it now looks like this:
return has_capability('moodle/legacy:admin', $context, $userid, true);
You could also leave the fourth parameter out as it defaults to true anyhow. Now isadmin() returns true as expected for anyone with the doanything capability, i.e. an administrator. Not sure if this is a bug, but I thought I would highlight it here in case other module designers have the same issue with isadmin() in 1.7+.
return has_capability('moodle/legacy:admin', $context, $userid, false);
For me as I described previously, this call is returning a null value, which is odd because that function is supossed to return a Boolean value. The fourth parameter being passed to has_capability is called $doanything and defaults to true, but this is being overridden with a value of false in the call from isadmin() (why?). This is odd behaviour because the admin of a site will have the doanything capability by default (check under the "Allowed to do everything" capabilty on the role permissions admin screen).
What I have done to get past this problem with my module is to change the $doanything parameter to true in the call from isadmin(), so it now looks like this:
return has_capability('moodle/legacy:admin', $context, $userid, true);
You could also leave the fourth parameter out as it defaults to true anyhow. Now isadmin() returns true as expected for anyone with the doanything capability, i.e. an administrator. Not sure if this is a bug, but I thought I would highlight it here in case other module designers have the same issue with isadmin() in 1.7+.