Troubleshooting Tip - Isolate the Variables

[jamesa]

Many questions here are along the lines of "why doesn't this work as expected" or "I can't figure out what's wrong with this script, where am I going wrong", so I thought I'd share a basic troubleshooting principle that I learned early on from a mentor. It's a simple but powerful concept: Isolate the Variables.

The first step in solving a problem in your script's logic is finding exactly where the problem is. Once you do this the solution is usually obvious.

---

Example of the process

A picture is worth a thousand words, so here's an example script with line numbers for reference. Let's say the variable called "firstname' (highlighted below in bold) comes from a form submission, but for some reason it's not getting to the database.

1. <?php
2.
3. /* Connecting, selecting database */
4. $link = mysql_connect("mysql_host", "mysql_user", "mysql_password")
5.    or die("Could not connect : " . mysql_error());
7. mysql_select_db("my_database") or die("Could not select database");
8.
9. /* Performing SQL query */
10. $query = "INSERT INTO my_table VALUES ('$firstname')";
11. $result = mysql_query($query) or die("Query failed : " . mysql_error());
12.
13. echo "done";
14.
15. /* Closing connection */
16. mysql_close($link);
17.
18.?>

Let's say I'm at a total loss why this won't work, so I'm going break it down and completely isolate every variable.

First a sanity check - is the server actually handling php pages:

<?php

echo "hello world";

?>

Next, can I log into mysql successfully via the shell (or phpMyAdmin if you prefer) and run a query:

shell> mysql -u mysql_user -p my_database
Enter password:
Welcome to the MySQL monitor. Commands end with ; or \g.
Your MySQL connection id is 144713 to server version: 4.0.13

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> select count(*) from my_table;
+----------+
¦ count(*) ¦
+----------+
¦ 1195 ¦
+----------+
1 row in set (0.00 sec)

Great so far. Back to the original script. Let's see if the script is actually grabbing the 'firstname' variable okay by adding the line shown in bold:

1. <?php
2. echo $firstname;
3. /* Connecting, selecting database */
4. $link = mysql_connect("mysql_host", "mysql_user", "mysql_password")
5.    or die("Could not connect : " . mysql_error());
7. mysql_select_db("my_database") or die("Could not select database");
8.
9. /* Performing SQL query */
10. $query = "INSERT INTO my_table VALUES ('$firstname')";
11. $result = mysql_query($query) or die("Query failed : " . mysql_error());
12.
13. echo "done";
14.
15. /* Closing connection */
16. mysql_close($link);
17.
18.?>

Now, we know lines 4, 7 and 11 in the original script work or it would have died with an error message. Just check over to make sure we are connecting to the right database and tables.

Next look at line 10. What does the query look like to the database? Let's find out by adding the line shown in bold:

1. <?php
2. echo $firstname;
3. /* Connecting, selecting database */
4. $link = mysql_connect("mysql_host", "mysql_user", "mysql_password")
5.    or die("Could not connect : " . mysql_error());
7. mysql_select_db("my_database") or die("Could not select database");
8.
9. /* Performing SQL query */
10. $query = "INSERT INTO my_table VALUES ('$firstname')";
11. echo $query;
12. $result = mysql_query($query) or die("Query failed : " . mysql_error());
13.
14. echo "done";
15.
16. /* Closing connection */
17. mysql_close($link);
18.
19.?>

Now we can see the query in the browser window, let's say it displays:

INSERT INTO my_table VALUES ('Joe')

Copy and paste it directly into mysql and see if the query produces the expected result:

mysql> INSERT INTO my_table VALUES ('Joe');

---

That's basically how it works. You test every link in the chain, one-by-one. Make no assumptions. Isolate. Using this technique you can pinpoint any problem with precision. This applies to any language and even hardware issues or tech support. Do this and the solution usually jumps right out at you. If not, at least you'll have a clear idea of the problem so you can ask the right questions.

[grandpa]

Thanks for the reminder jamesa. I remember there were 6 steps to troubleshooting that I was taught when I was becoming tech. Danged if I remember even one of them today, and the best I find on the web is 5 steps.

1. Collect Information
2. Localize the Problem
3. Isolate the Problem
4. Correct the Problem
5. Verify Problem Resolution

Basically good troubleshooting boils down to taking a breath, maybe even a walk, then, as you pointed out, be logical about the process. Heh - still doesn't seem to stop me from asking a noob question...

[edited by: jatar_k at 4:53 pm (utc) on April 21, 2004]
[edit reason] replaced link with steps [/edit]