Intoduction

It’s time to install the product and configure it minimally for first-time use. Our reason for installing phpMyAdmin could be one of the following:

• Our host provider did not install a central copy
• Our provider installed it, but the version installed is not current
• We are working directly on our enterprise’s web server

Required information

Some host providers offer an integrated web panel where we can manage accounts, including MySQL accounts, and also a file manager that can be used to upload web content. Depending on this, the mechanism that we use to transfer phpMyAdmin source files to our webspace may vary. We will need some specific information (listed below) before starting the installation:

• The web server’s name or address: Here, we will assume it to be www.mydomain.com
• Our web server’s account information (username, password): This information will be used for either FTP or SFTP transfer, SSH login, or web control panel login.
• The MySQL server’s name or IP address: If this information is not available, a good alternative choice is localhost, which means that the MySQL server is located on the same machine as the web server. We will assume this to be localhost.
• Our MySQL server’s account information (username, password).

System requirements

The up-to-date requirements for a specific phpMyAdmin version are always stated in the accompanying Documentation.html file. For phpMyAdmin 3.3, the minimum PHP version required is PHP 5.2 with session support and the Standard PHP Library (SPL). Moreover, the web server must have access to a MySQL server (version 5.0 or later)—either locally or on a remote machine. It is strongly recommended that the PHP mcrypt extension be present for improved performance in cookie authentication mode. In fact, on a 64-bit server, this extension is required.

On the browser side, cookie support must be activated, whatever authentication mode we use.

Downloading the files

There are various files available in the Download section of http://www.phpmyadmin.net. There might be more than one version offered here, and it is always a good idea to download the latest stable version. We only need to download one file, which works regardless of the platform (browser, web server, MySQL, or PHP version). For version 3.3, there are two groups of files—english and all-languages. If we need only the English interface, we can download a file whose name contains “english”—for example, phpMyAdmin-3.3.2-english.zip. On the other hand, if we have the need for at least one other language, choosing all-languages would be appropriate.

If we are using a server supporting only PHP4—for which the PHP team has discontinued support since December 31, 2007—the latest stable version of phpMyAdmin is not a good choice for download. I recommend using version 2.11.x, which is the latest branch that supports PHP4.

The files offered have various extensions: .zip, .tar.bz2, .tar.gz, .7z. Download a file having an extension for which you have the corresponding extractor. In the Windows world, .zip is the most universal file format, although the files are bigger than .gz or .bz2 files (which are common in the Linux/Unix world). The .7z extension denotes a 7-Zip file, which is a format that achieves a higher compression ratio than the other formats offered—an extractor is available at http://www.7-zip.org. In the following examples, we will assume that the chosen file was phpMyAdmin-3.3.2-all-languages.zip.

After clicking on the appropriate file, the nearest mirror site will be chosen by Sourceforge.net. The file will start to download, and we can save it on our computer.

Installing on different platforms

The next step depends on the platform you are using. The following sections detail the procedures for some common platforms. You may proceed directly to the relevant section.

Installing on a remote server using a Windows machine

Using the File explorer, we double-click the phpMyAdmin-3.3.2-all-languages.zip file that we just downloaded on the Windows machine. A file extractor will start, showing us all of the scripts and directories inside a main phpMyAdmin-3.3.2-all-languages directory.

Use whatever mechanism your file extractor offers to save all the files, including subdirectories, to some location on your workstation. Here, we have chosen C:. Therefore, a C:phpMyAdmin-3.3.2-all-languages directory has been created for extraction.

Now, it’s time to transfer the entire directory structure C:phpMyAdmin-3.3.2-alllanguages to the web server in our webspace. We use our favorite SFTP or FTP software, or the web control panel, for the transfer.

The exact directory under which we transfer phpMyAdmin may vary. It could be our public_html directory or another directory to which we usually transfer web documents. For further instructions about the exact directory to be used, or the best way to transfer the directory structure, we can consult our host provider’s help desk.

After the transfer is complete, these files can be removed from our Windows machine as they are no longer needed.

Installing on a local Linux server

Let’s say we chose phpMyAdmin-3.3.2-all-languages.tar.gz and downloaded it directly to some directory on the Linux server. We move it to our web server’s document root directory (for example, /var/www/html) or to one of its subdirectories (for example, /var/www/html/utilities). We then extract it by issuing the following shell command or by using any graphical file extractor that our window manager offers:

tar -xzvf phpMyAdmin-3.3.2-all-languages.tar.gz

We must ensure that the permissions and ownership of the directory and files are appropriate for our web server. The web server user or group must be able to read them.

Installing on local Windows servers (Apache, IIS)

The procedure here is similar to that described in the Installation on a remote server using a Windows machine section, except that the target directory will be under our DocumentRoot (for Apache) or our wwwroot (for IIS). Of course, we do not need to transfer anything after modifications are made to config.inc.php (described in the next section), as the directory is already on the webspace.

Apache is usually run as a service. Hence, we have to ensure that the user under whom the service is running has normal read privileges to access our newly-created directory. The same principle applies to IIS, which uses the IUSR_machinename user. This user must have read access to the directory. You can adjust permissions in the Security/permissions tab of the directory’s properties.

Configuring phpMyAdmin

Here, we will learn how to prepare and use the configuration file containing the parameters to connect to MySQL, and which can be customized as per our requirements.

Before configuring, we can rename the directory phpMyAdmin-3.3.2-all-languages to something like phpMyAdmin or just something easier to remember. This way, we and our users can visit an easily-remembered URL to start phpMyAdmin. On most servers, the directory part of URLs is case-sensitive, so we should communicate the exact URL to our users. We can also use a symbolic link if our server supports this feature.

The config.inc.php file

This file contains valid PHP code that defines the majority of the parameters (expressed by PHP variables) that we can change in order to tune phpMyAdmin to our own needs. There are also normal PHP comments in it, and we can comment our changes.

Be careful not to add any blank lines at the beginning or end of the file; doing so would hamper the execution of phpMyAdmin.

Note that phpMyAdmin looks for this file in the first level directory—the same one where index.php is located.

In versions before 2.8.0, a generic config.inc.php file was included in the downloaded kit. Since 2.8.0, this file is no longer present in the directory structure. Since version 2.9.0, a config.sample.inc.php file is included, and this can be copied and renamed to config.inc.php to act as a starting point. However, it is recommended that you use the web-based setup script instead, for a more comfortable configuration interface.

There is another file—layout.inc.php—that contains some configuration information. Because phpMyAdmin offers theme management, this file contains the theme-specific colors and settings. There is one layout.inc.php file per theme, located in themes/themename, for example, themes/original.

Avoiding false error messages about permissions on config.inc.php

In its normal behavior, phpMyAdmin verifies that the permissions on this file do not allow everyone to modify it. This means that the file should not be writable to the world. Also, it displays a warning if the permissions are not correct. However, in some situations (for example, an NTFS file system mounted on a non-Windows server), the permission detection fails. In these cases, you should set the followingparameter to false:

$cfg[‘CheckConfigurationPermissions’] = false;

The following sections explain various methods for adding or changing a parameter in the config.inc.php file.

Configuration principles

phpMyAdmin’s behavior, given that no configuration file is present, has changed in version 3.1.0. In versions 3.0 and earlier, the application used its default settings as defined in libraries/config.default.php and tried to connect to a MySQL server on localhost—the same machine where the web server is running—with user as root and no password. This is the default set-up produced by most MySQL installation procedures, even though it is not really secure. Therefore, if our freshly installed MySQL server were still to have the default root account, we would have logged on automatically and would have seen a warning given by phpMyAdmin about such lack of security.

If the notion of a MySQL root user eludes you, now might be the time to browse http://dev.mysql.com/doc/refman/5.1/en/privilege-system.html, in order to learn the basics about MySQL’s privilege system.

Since version 3.1.0, the development team has wanted to promote a more flexible login panel. This is why, with the lack of a configuration file, phpMyAdmin displays the cookie-based login panel by default

We can verify this fact by visiting http://www.mydomain.com/phpMyAdmin and substituting the appropriate values for the domain part and the directory part. If we are able to log in, it means that there is a MySQL server running on the same host as the web server (localhost) and we’ve just made a connection to it. However, not having created a configuration file means that we would not be able to manage other hosts via our installation of phpMyAdmin. Moreover, many advanced phpMyAdmin features (for example, query bookmarks, full relational support, column transformation, and so on) would not be activated.

The cookie-based authentication method uses Blowfish encryption for storing credentials in browser cookies. If no configuration file exists, a Blowfish secret key is generated and stored in session data, which can open the door to security issues. This is why the following warning message is displayed: The configuration file now needs a secret passphrase (blowfish_secret).

At this point, we have some choices:

• Use phpMyAdmin without a configuration file
• Use the web-based setup script to generate a config.inc.php file
• Create a config.inc.php file manually

These options are presented in the following sections. We should note that even if we use the web-based setup script, we should familiarize ourselves with the config.inc.php file format, because the setup script does not cover all of the possible configuration options.