Understanding common errors

There are five main areas that cause the majority of problems for Joomla! sites. Understanding these areas and the common problems that occur with in each of them is a very important part of fixing them and thus, our site.

Even though there is a practically unlimited number of potential issues and problems that can occur, there are certain problems which occur much more regularly than others.

If we understand these main problems, we should be able to take care of many of the problems that will occur on our site without needing to resort to hiring people to fix them, or waiting for extension developers to provide support.

The five areas are:

• PHP code
• JavaScript code
• CSS/HTML code
• Web server
• Database

We will now look at the two most common error sources, PHP and JavaScript.

PHP code

Because PHP code is executed on the server, we usually have some control over the conditions that it is subject to.

Most PHP errors originate from one of four sources:

• Incorrect extension parameters
• PHP code error
• PHP version
• Server settings

Incorrect extension parameters

It is often easy to misunderstand what the correct value for an extension parameter is, or if a particular parameter is required or not. These misunderstandings are behind a large number of PHP “errors” that developers experience when building a site.

Diagnosis

In a well-coded extension, putting the wrong information into a parameter shouldn’t result in an error, but will usually result in the extension producing strange or unexpected output, or even no output at all.

In a poorly coded extension, an incorrect parameter value will probably cause an error. These errors are often easy to spot, especially in modules, because our site will output everything it processed up until the point of the error, giving our page the appearance of being cut off.

Some very minor errors may even result in the whole page, except for the error causing extension, being output correctly, and error messages appearing in the page, where the extension with the error was supposed to appear.

A critical error, however, may cause the site to crash completely, and output only an error message. In extreme cases not even an error message will be output, and visitors will only see a white screen.

The messages should always appear in our PHP log though.

Fixing the problem

Incorrect extension parameters are the easiest problems to fix, and are often solved simply by going through the parameter screens for the extensions on the page with the errors, and making sure they all have correct values.

If they all look correct, then we may want to try changing some parameters to see if that fixes the issue. If this still doesn’t work, then we have a genuine error.

PHP code error

Extension developers aren’t perfect, and even the best ones can overlook or miss small issues in the code. This is especially true with large, complex extensions so please remember that even if an extension has PHP code error, it may not necessarily mean that the whole extension is poorly coded.

Diagnosis

Similar to incorrect extension parameters, a PHP coding error will usually result in a cut-off page, or a white screen, sometimes with an error message displayed, sometimes without.

Whether an error message is displayed or not depends partly on the configuration of your server, and partly on how severe the error was. Some servers are configured to suppress error output of certain types of errors.

Regardless of the screen output, all PHP errors should be output to the PHP log. So, if we get a white screen, or even get a normal screen but strange output, checking our PHP log can often help us to find the problem.

PHP logs can reside in different places on differently configured servers, although it will almost always be in a directory called logs. We may also not have direct access to the log, again depending on our server host. We should ask our web hosting company’s support staff for the location of our PHP log, if we can’t easily find it.

Some common error messages and causes are:

Parse error: parse error, unexpected T_STRING in...

This is usually caused by a missing semi-colon at the end of a line, or a missing double quote (“) or end bracket ()) after we opened one. For quotes and semicolons, the problem is usually the line above the one reported in the error. For missing brackets, the error will sometimes occur at the end of the script, even though the problem code is much earlier in the script.

Parse error: syntax error, unexpected $end in...

We are most likely missing a closing brace (}) somewhere. Make sure that each open brace ({) we have has been closed with a closing brace (}).

Parse error: syntax error, unexpected T_STRING, expecting ',' or ';' in...

There may be double quotes within double quotes. They either need to be escaped, using a forward slash before the inside quote, or changed to single quotes.

Fixing the problem

Fixing a PHP code error is possible but can be difficult depending on the extension.

Usually when there is a PHP code error, it will give a brief description of the error, and a line number. If nothing is being output at all, then we may need to turn error reporting up as described later.

We will then go to the line specified to examine it and the lines around it to try and find our problem. If we can’t find an obvious error, then it might be better to take the error back to the developer and ask them for support.

PHP version

The current version of PHP is 5.x.x and version 6.x is expected soon, but because many older, but still popular, applications only run on PHP version 4.x.x. It is still very common to find many Web hosting companies still using PHP 4 on their servers. This problem is even more unfortunate due to the fact that PHP 4 isn’t even supported anymore by the PHP developers.

In PHP 5, there are many new functions and features that don’t exist in PHP 4. As a result, using these functions in an extension will cause it to error when run on a PHP 4 server.

Diagnosis

Diagnosing if we have the wrong PHP version is not obvious, as it will usually result in an error about an unknown function when the extension tries to call a function that doesn’t exist in the version of PHP installed on our server.

Sometimes, the error will not be that the function is unknown, but that the number of parameters we are sending it is incorrect if they were changed between PHP 4 and PHP 5.

Fixing the problem

The only real way to fix the problem is to upgrade our PHP version. Some web hosts offer PHP 4 or 5 as an option and it might be as simple as checking a box or clicking a button to turn on PHP 5.

In case if our host doesn’t offer PHP 5 at all, the only solution is to use a different extension or change our web host. This may actually be a good idea anyway, because if our host is still using an unsupported PHP version with no option to upgrade, then what other unsupported, out of date software is running those servers?

Server settings

One of the most common problems encountered by site owners in regards to server settings is file permissions.

Many web hosting companies run Linux, which uses a three-part permission model, on their servers. Using this model, every file can have separate permissions set for:

• The user who owns the particular file
• Other users in the same user group as the owner
• Everyone else (in a web site situation this is mainly the site visitors)

Each file also has three permissions that enable, or disable, certain actions on the file. These permissions are read, write, and execute.

Permissions are usually expressed in one of two ways, first as single characters in a file listing or as a three digit number.

For example, a file listing on a Linux server might look like this:

drwxr-x--- 2 auser agroup 4096 Dec 28 04:09 tmp
-rwxr-x--- 1 auser agroup 345 Sep 1 04:12 somefile.php
-rwxr--r-- 1 auser agroup 345 Sep 1 04:12 foo

The very first character to the left, a d or – in this case, indicates if this is a directory (the d) or a file (the -). The next nine characters indicate the permissions and who they apply to.

The first three belong to the file owner, next three to those in the same group as the owner, and the final three to everyone else.

The letters used are:

• r—read permission
• w—write permission
• x—execute permission

A dash (-) indicates that this permission hasn’t been given to those particular people.

So in our example above, tmp.php can be read, written to, or executed by the owner (a user). It can be read or executed (but not written to) by other users in the same group (agroup) as the owner, but the file cannot be used at all by people outside the group.foo however, can be read by people in the owners group, and also read by everyone else, but it cannot be executed by them.

As mentioned above, permissions are also often expressed as a three-digit number. Each of the digits represents the sum of the numbers that represent the permissions granted.

For example: r = 4, w = 2, and x = 1.

Adding these together gives us a number from 0-7, which can indicate the permission level. So a file with a permission level of 644 would translate as:

6 = 4 + 2 = rw
4 = r
4 = r

or -rw-r–r– in the first notation that we looked at.

Most servers are set by default to one of the following:

644 -rw-r--r--
755 -rwxr-xr-x
775 -rwxrwxr-x

All of this looks fine so far. The problems start to creep in depending on how the server runs their PHP. PHP can either be set up to run as the same user who owns all the files (usually our FTP user or hosting account owner), or it can be set up to run as a different user, but in the same group as the owner. Or it can be set up to be a completely different user and group, as illustrated here:

The ideal setup, from a convenience point of view, is the first one where PHP is executed as the same user who owns the files. This setup should have no problems with permissions.

But the ideal setup for a very security-conscious web host is the third one since the PHP engine can’t be used to hack the web site files, or the server itself. A web server with this setup though used to have a difficult time running a Joomla! site. It was difficult because changing the server preferences requires that files be edited by the PHP user, uploading extensions means that folders and files need to be created by the PHP user, and so on.

If the PHP engine isn’t even in the same group as the file owner, then it gets treated the same as any site visitor and can usually only read, and probably execute files, but not change them. This prevents us from editing preferences or uploading new extensions. However, if we changed the files so that the PHP engine could edit and execute them (permission 777, for example) then anyone who can see our site on the internet can potentially edit and execute our files by themselves, making our site very vulnerable to being hacked by even a novice hacker.

We should never give files or directories a permission of 777 (read, write, and execute to all three user types) because it is almost guaranteed that our site will be hacked eventually as a result. If, for some reason, we need to do it for testing, or because we need to in order to install extensions, then we should change it back as soon as possible.

Diagnosis

To spot this problem is relatively simple. If we can’t edit our web site configuration, or install any extensions at all, then nine times out of ten, server permissions will be the problem.

Fixing the problem

We can start by asking our web host if they allow PHP to be run as CGI, or install suEXEC (technical terms for running it as the same user who owns the files) and if so, how do we set it up.

If they don’t allow this, then the next best situation is to enable the Joomla! FTP layer in our configuration. This will force Joomla! to log into our site as the FTP user, which is almost always the same user that uploaded the site files, and edit or install files.

We can enable the FTP layer by going to the Site | Global Configuration page and then clicking on the server item in the menu below the heading. We can then enter the required information for the FTP layer on this screen.

The FTP layer should only be used on Linux-based servers. More information about the FTP layer can be found in the official Joomla! documentation at http://help.joomla.org/content/view/1941/302/1/2/

If for some reason the FTP layer doesn’t work, we only have two other options. We could change our web hosting provider as one option. Or, whenever we want to install a new extension or change our configuration, we need to change the permissions on our folders, perform our tasks, and then change the permissions back to their original settings.