The rolesdebug.php roles debugging script
Note: You are currently viewing documentation for Moodle 1.9. Up-to-date documentation for the latest stable version is available here: The rolesdebug.php roles debugging script.
Rolesdebug.php is a stand-alone script that is extremely useful for debugging problems related to roles and permissions. The output can be interpreted by anyone with a good understanding of Moodle's Roles and capabilities system. If you're a "roles novice" and you need help with a roles-related problem, ask a roles expert to help you with running the script and interpreting the output. If you don't have access to an expert, post a request for help to the Roles and Capabilities forum. After using the script a few times, you'll be an expert too!
You can download rolesdebug.php from the Modules and Plugins database. To install the script, simply drop it into the Moodle root directory or any directory under the root directory.
Rolesdebug.php requires a login, so only someone with a Moodle user account who is currently logged in can use it. Since it is a php script, you will see the output in your browser. No one else will see it unless they're looking over your shoulder. Furthermore, rolesdebug.php will only give you information about YOUR permissions. You cannot use it to get information about another user's permissions (unless you can login as them).
Rolesdebug.php outputs a table giving a spatial view of the role assignments and overrides that affect you in a specified context. From the table, you will be able to see how Moodle calculates a specified permission. The table format is explained (and several examples are given) in the article How permissions are calculated.
Rolesdebug.php reads permission data from the Moodle database but does not modify the database in any way. In this respect, it is similar to other debug scripts in the standard distribution, like the TeX notation debugger.
- 1 The use case for rolesdebug.php
- 2 Essential roles and capabilities concepts
- 3 Overview of a script session
- 4 Using the script
- 5 How to read the output
- 6 How to determine the context id
- 7 Rolesdebug says I should be able do this, but Moodle won't let me!
The use case for rolesdebug.php
The main use case for rolesdebug.php is a roles expert helping a roles novice troubleshoot a roles-related problem. A roles expert is anyone with a solid understanding of the essential roles concepts listed in the next section. A roles novice is any Moodle user with the ability to follow simple instructions from the expert. While the expert and novice may occasionally share the same physical location and have accounts on the same Moodle site, it is not required that they do so. The expert must be able to help the novice without logging in to the novice's site, and by communicating with the novice only by e-mail, messaging, forum posts, etc.. For example, the novice may be a user posting to a moodle.org forum and the expert may be a moodler wanting to be helpful. Even when expert and novice share a physical location and have accounts on the same Moodle site, the expert may not be in a position to give direct help, e.g., by "logging in as" the novice or meeting with the novice. For example, the expert may be a Moodle administrator with an extremely busy schedule.
Here's a typical scenario. Supposed the novice is a teacher who has created a quiz, but is being prevented from previewing the quiz for some unknown reason. The novice reports the problem to moodle.org in a forum post. The expert (a helpful moodler) suspects a roles problem and replies by asking the novice to (1) log in to Moodle, reproduce the problem (2) browse to rolesdebug.php (3) enter two or three parameters as specified by the expert (4) paste the output from rolesdebug.php into a reply to this forum post. The expert views the output and immediately diagnoses the problem.
Secondary use cases for rolesdebug.php include
- a user troubleshooting his own problems
- a user troubleshooting another user's problem while logged in as that user
Note that both of these secondary use cases are equivalent, since there is only one actor (the expert), not two. To keep things simple in the remainder of the article, I'll describe the secondary use case, and I'll refer only to YOU. Keeping the primary use case in mind, it should be clear when "you" means roles expert and when it means the roles novice.
Essential roles and capabilities concepts
Interpreting the output from rolesdebug.php requires a solid understanding of the concepts listed below. If any of these concepts are unfamiliar to you, stop and follow the documentation link.
Overview of a script session
First, you will log in to Moodle and navigate to the context where you're having the problem. Perhaps this is a quiz which Moodle, for some unknown reason, is preventing you from attempting. Then, without logging out of Moodle, point your browser at rolesdebug.php (I find it convenient to open a new browser tab for this). Input the context you're interested in and (optionally) the name of a capability to investigate, then press the Go button. The script will return a page with a table presenting a spatial view of the role assignments and overrides that affect you in the specified context. From the table, you will be able to see why Moodle is preventing you from attempting the quiz.
Using the script
This step is done in Moodle (you won't use the script until STEP 2). Login to Moodle and navigate into the context where the problem is occurring. Once you're there, you'll make note of the context id, which is needed in STEP 2. I'll tell you how to determine the context id later.
Incidentally, even if you know the context id, it is essential that you actually navigate to the context. This is because Moodle loads certain permission data "lazily" -- i.e., only when actually needed. Navigating to the context guarantees that Moodle will have loaded the data. For example, suppose the target context is a certain quiz in some course. You must enter the course and click on the Quiz icon.
However if you are debugging a problem related to a change to a user policy such as Site administration -> Front page -> Front page settings -> Default front page role, you must logout and log back in after making the change.
Do not log out!
Open a second browser window. In the window, point your browser at rolesdebug.php. The script URL will be something like
Rolesdebug.php will NOT ask you to login because you are already logged in. The script will ask you for three inputs:
- CAPABILITY. If you're only interested in seeing your role assignments and overrides, you can leave this field empty. If you're interested in analyzing a particular permission, you'll need to enter the capability name. For example, if you're interested in the capability that controls your ability to attempt quizzes, enter mod/quiz:attempt.
- CONTEXT TYPE. Choose one of the following from the dropdown menu:
- CONTEXT ID. The context id is a number at the end of the URL of the page you found in STEP 1. See How to determine the context id below.
Incidentally, MODULE means activity or resource. There is no FRONT PAGE context. If you're interested in the Front page context, choose COURSE and specify a context id of 1.
Here's an example of input:
Press the Go button. Rolesdebug.php will return a page of information. The main item on the page is a table giving a spatial view of all the role assignments and overrides that affect you in the specified context.
How to read the output
The first three lines of output (1) simply echo your input values, and the next two lines (2) remind you of who YOU are, and tell you the actual name of the context you have selected. Check these carefully to make sure you are who you think you are, and have specified the correct context.
For each of your roles, you will see a line of the form alias = role name where
- role name is the actual role name
- alias is the name used to represent the role in the table
In the example, R7 = user means the the role user (the shortname of Authorized user) will be represented in the table by the alias R7. Aliases are used because long role names could make the table very wide, forcing you to scroll horizontally. By using aliases, the table will hopefully fit in a window, allowing you to see the entire table in a single a glance.
Next comes the table (4). I'll have a lot more to say about the table below.
If you specified a capability, then you will see the three lines immediately after the table (5).
- The first line gives the calculated permission, which is based on the table. The value can be either A (Allow) or P (Prevent).
- The second line tells you if you are able to "do anything," that is, if you have moodle/site:doanything = Allow (this is typically only true for administrators)
- The third line tells you if you can "do this." If you can do anything, you can obviously do this regardless of the calculated permission.
How to read the table
If the target context is N levels deep, the table will have N rows and N columns, one for each context level. The example above has four levels:
System | | Category "A" | | Course "cooking" | | Module "quiz-1"
The column headings give the names of the contexts. These are listed in order of increasing depth: System, A, cooking, quiz-1.
To save space, the table does not have row headings. If it did, they would be the same as the column headings. For example, row 1 would be labeled "System" and row 4 would be labeled "quiz-1".
The first row of the table contains the role assignments made in each context level. In the example, you can see that R7 (Authorized user) is assigned in the System context and R5 (Student) is assigned in the course context. If there are no overrides (as in this example) you will only see entries in row 1.
The letters N and A in parentheses are the values of the capabilities in the role definitions. The possible values are:
N - Not set A - Allow P - Prevent X - Prohibit
"Not set" means that the role doesn't say anything about the capability. In the example, we see that the Student role allows quiz attempts, while the Authorized user role doesn't have anything to say about quiz attempts.
If there are role overrides, there will be entries in other rows of the table. Overrides have the same format as the assignments in row 1. An override is shown in the ROW of the context where it is made, and the COLUMN of the assignment that it overrides.
To illustrate, let's override the Student role in the Quiz context, setting mod/quiz:attempt to Prevent, and then rerun rolesdebug.php. Of course before running the script, the student must attempt the quiz. This time, the student should be prevented because of the override. Now we run the script and get the following output:
Notice the newly added R5(P). This is the override. It is in the fourth row because the override was made in the quiz context, and it is in the course column because the Student role was assigned in the Course context.
The calculated permission is now P, as expected.
How Moodle calculates the permission
For a full explanation of how permissions are calculated, see the article How permissions are calculated. This section merely illustrates the calculation for the examples given in this article.
How to determine the context id
Here are rules for determining the context id for each context type.
For a COURSE context, the context id is the course id. You can get the course id from the URL that appears in the address bar when when you're on the course page. For example when I point my browser at the "Features" course on demo.moodle.org, I see this:
The course id, and therefore the context id for this course is 2.
If Moodle won't let you enter the course for some reason, but you can see a link to the course, let your mouse hover over the link as in the following screenshot. Your browser will show you the address at the bottom of the window.
The front page of a Moodle site is also a course, but you can't use either of the above tricks to get the id. The front page course id is 1.
MODULE (activity or resource)
For a MODULE context, the context id is the activity or resource id. You can get the id from the URL that appears in the address bar when you're viewing the activity or resource, or from the bottom of the browser window when you let your mouse hover over a link. Here are some examples:
http://demo.moodle.org/mod/choice/view.php?id=25 http://demo.moodle.org/mod/forum/view.php?id=28 http://demo.moodle.org/mod/lesson/view.php?id=38 http://demo.moodle.org/mod/quiz/view.php?id=61 http://demo.moodle.org/mod/resource/view.php?id=10 http://demo.moodle.org/mod/resource/view.php?id=48
The context id's for these modules are 25, 28, 38, 61, 10, and 48.
For a BLOCK context, the context id is the "instanceid" of the block. To get the instanceid, turn editing on and let the mouse hover over the "eye" icon in the block header. Then take the instanceid from URL that appears in the at the bottom of the window. For example:
The context id for this block is 19. Note that for blocks, only a user who can turn editing on can get the instanceid.
For a COURSECAT context, the context id is the category id. You can get the id from the URL that appears in the address bar when you're on the category page. If the site has only one category (usually called "Miscellaneous") the id is 1. If there is more than one category, the easiest way to get the category id for a specific category is to have a Category list or a Combo list on the front page of the site (or a Courses block) and let your mouse hover over one of the links. For example:
The context id for this category is 3
For a USER context, the context id is the user id. You can get the id from the URL that appears in the address bar when you're on a profile page, or from the bottom of the browser window when you let your mouse hover over a user's name. For example:
The context id for this user is 6
There is only one SYSTEM context. Its id is 1.
Rolesdebug says I should be able do this, but Moodle won't let me!
When this happens it is because Moodle is calculating your permission differently from the way you think it is. Here are three possibilities:
- Moodle may be calculating the permission in a different context than the one you specified (Moodle calculates some permissions explicitly in System or User contexts).
- If you are assigned any legacy roles (particularly Guest), Moodle may be ignoring the calculated permission. For example, Guest has been edited, allowing it to post to Forums, Rolesdebug will report that you can post, but Moodle will simply ignore the permission. If you ask a developer why, they will tell you "because guests can never post."
- The action you are attempting requires two or more permissions.
When such a disagreement occurs, further research will be needed to debug the problem. Sometimes you can find the answer in documentation. For example, when a permission is calculated in a different context, the documentation usually says so. Other times you will just need to read the code.