How to debug Caravel
When trying to figure out why something isn't working in Caravel, here are some tools that may be useful...
- Error log. Caravel errors are logged to PHP's error facility (often the Apache server error log). This is the first place to look if you get a completely blank screen, which usually indicates a syntax error.
- Turn on T_DEBUGGING. Set this constant to 1 in conf/caravel.conf. Then whenever a Caravel error is raised, you will get a full stack backtrace in addition to the error message, which makes it much easier to figure out where the error is arising. (You may want to set it conditionally based on username or remote IP address.) This flag must also be enabled in order to see output from the next tool:
- Print out variables properly. Use the p($object) function to dump the contents of an object. This function delays output until it can be inserted into the proper place in the HTML document, so that it does not break validation and cause browsers to go into quirks rendering mode. However, this means that if an error is raised the info may not get printed. Use p($object,1) to force it to print immediately. This form is also necessary when working in popup windows rather than the standard template. This latter form is equivalent to print Utility::getVal($object). NOTE: p() only prints if T_DEBUGGING is on, so that it doesn't matter as much if some debugging code makes it on to the production server. But keep this in mind if you are scratching your head trying to figure out why your expected debug info isn't printing.
- Add &CV_DEBUG to the URL query string. This will print out a stream of debug information at the end of the page, which is occasionally helpful.