PhotoArch mini-HOWTO

Ilia Baldine

v 0.2, 1 February 2002

This document describes how to setup and use PhotoArch - a PHP photo archival system

1. Copyright

Copyright 2001(c) by Ilia Baldine. This document may be distributed only subject to the terms and conditions set forth in the GPL License at, except that this document must not be distributed in modified form without the author's consent.

2. License

PhotoArch is provided under the GPL open-source license:

Copyright (C) 2001  Ilia Baldine

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

3. Disclaimer

4. What is PhotoArch?

PhotoArch is a photographic storage and retrieval system. It is written mostly in PHP (PHP3 or PHP4 compatible) with a bit of JavaScript thrown in for good measure.You might say - "'...photographic storage and retrieval system': that's just a fancy name for a web photoalbum" and we all know there's plenty of those around.

So how is PhotoArch different? In a number of ways actually:

PhotoArch can index mountable volumes containing digitized pictures:

if you want to store high-quality digitized pictures on a bunch of CD-s and need a way to track them - PhotoArch is for you

PhotoArch can help you keep track of the original film media:

if you are old-fashioned, like myself, and have a lot of older pictures on slides or prints, with stored negatives, PhotoArch is for you

PhotoArch provides you with a graphical front-end to the database:

you can modify any part of your database at any time by simply using your web browser.

PhotoArch can also serve as a web photoalbum. To that end it provides the following capabilities:

Keyword searching for photographs:

each photograph has meta data associated with it: location, people, comments, date etc. The database can be searched by any combination of these parameters

Album browsing:

instead of searching you can choose to browse individual albums

Album permissions:

each album can be either open to the public, a limited set of users who must be authenticated prior to viewing them or, finally, only to the database administrator

Other miscellaneous features include:

Support for EXIF in images:

EXIF data of your choosing is stored along with images (yes, you can customize the set of EXIF tags that is gathered)

Dynamic resizing of images on-demand:

for your low-bandwidth friends, PhotoArch offers the ability to dynamically resize (shrink) the original high-res images before sending them on the wire

Batch processing of new images:

in addition to being able to add each volume of images interactively, PhotoArch allows you to add each volume as a single batch operation, giving you an option to put all images in a given volume into a specific album.

New in version 1.0:

Free-structured volumes:

gone are the days when you were forced to structure each volume by film directories. Now a volume can have any directory structure of arbitrary depth and complexity: from the simple single directory to a complex arrangement of directories only you can figure out. Arrangement of image files by film, as present in the previous versions of PhotoArch is still possible, but is no longer a requirement.

Batch processing:

interactive addition of volume content (images) to the database is no longer the only choice - you can also add the entire volume in batch mode. You can specify the default album the volume contents will belong to, sit back and relax.

The following sections will describe how to install and use PhotoArch.

5. Prerequisites

Prerequisites to running PhotoArch include:

This code was developed under the following configuration:

Useful URLs are:

6. Installation and configuration

6.1 Installing PhotoArch

Presumably, first you acquire the code to PhotoArch from You must now pick a location in your filesystem, where you want PhotoArch to reside. The installation process simply consists of uncompressing the archive in the right place and telling Apache (if you want to have a type URL) where to find it. Alternatively, you can just put it wherever Apache can get to it (your  /public_html directory, for instance) and run it from there. For the former case you must insert the following directive in your httpd.conf file:

Remember, that if you are putting PhotoArch in a location that is not described in one of Apache's

tags, you will have to add such a tag.

Also, for convenience, you may link photoarch.php3 file in the distribution to an index.php3 (make sure your Apache configuration includes using index.php3 along with index.html for default directory index)

6.2 Configuring PHP

Depending on the distribution and the flavor of your *NIX box, you may need to finesse your PHP configuration prior to using PhotoArch. This configuration is contained in php.ini (/etc/php.ini or /usr/local/etc/php.ini or some other conspicuous place) file. The thing to check in it is the safe_mode directive.

If it is turned On, you have two choices:

  1. Turn it to Off and wallow in the sense of insecurity this gives you. (PhotoArch, however, will work just fine)
  2. Leave in on and adjust the safe_mode_exec_dir directive so that it matches the location of ImageMagick executables ('convert' and 'identify'). It is usually either /usr/bin or /usr/X11R6/bin.
  3. If you plan to use EXIF features and safe_mode is left On, copy the 'exifextr' script from the distribution's scripts/ directory to the same directory where 'convert' and 'identify' are.

If, however, the safe_mode directive is Off you can probably leave it as is, or else do as the above paragraph describes.

After all modifications to httpd.conf and php.ini are completed, you can restart your webserver and test the installation.

Note: if you do not have the authority or the skill to modify the installation configuration, do not dispair: in all likelihood everything will work just fine. You may need to ask your system administrator what safe_mode for PHP is set to and modify the safe_mode_exec_dir. Placing PhotoArch source into your user home directory under html/ or public_html/ will make it perfectly usable, albeit the URL to get to it will look a bit ugly (something like <username>/photoarch/).

One more fact to keep in mind: you must change the ownership of the PhotoArch php scripts to be the same as the webserver (user www or wwwrun or httpd) when using PHP safe_mode.

6.3 Configuring MySQL

PhotoArch uses MySQL as its back-end database. The scripts to create users and tables in your MySQL database are provided:

  1. createusers.sql to create database users.
  2. createtables.sql to create the database and the tables it it.

You may wish to modify the createusers.sql file to change the default access password to the photoarch database. This script creates two users:

  1. photoarch - the user that has only read permissions to the database
  2. photoarchadmin - the user that has modify permissions to the database

You may need to run one or both of these scripts depending on your situation:

Prior to running this script however, you must edit it and replace all occurences of "mypassword" with the password of your choosing - this will be the password you use to modify your database.

Once ready, you can run it as follows:

$ > mysql -u root -p < createusers.sql
Note that you must use the database root password when prompted. If no errors are reported, you may run the second script as follows:
$ > mysql -u photoarchadmin -p < createtables.sql
Note that you must use the password that you chose for your database when prompted.

6.4 Configuring PhotoArch

The behavior of PhotoArch and the look and feel of it are defined by the config.php3 file found with the distributions. Future versions will utilize CSS (Cascading Style Sheets) for ease of customization of the look.

Open the configuration file config.php3 with one of your favorite editors and lets look at it closer. Skip down to the line that says:

if (!defined("CONFIG_INC")) {
define (CONFIG_INC, true);


The first block of definitions has to do with the database configuration - which host it resides on. They are pretty self-explanatory. If you database server and the webserver are co-located, you can put DEFAULT_MYSQHOST as "localhost". Unless you modified the default database and usernames in the createusers.sql script, the other three options should remain the same.


Next block of definitions has to do with EXIF functionality. If you don't know what it is, or don't need it - simply set USE_EXIF to "no". It is only useful to you if you have a digital camera that is capable of producing JPEG images of EXIF variety (with embedded meta-data like date, time, focus mode etc.). If you decide you do want to utilize EXIF, make sure that perl is installed on the host and Image::Info module is available to it. Easy way to test it is to run the exifdump script in the php/scripts directory and give it a name of one of the JPEG images from your camera as a command-line parameter. If you see a bunch of data being extracted - you are in good shape. Installation of PERL and its modules is outside of the scope of this document. See the installation chapter for useful URLs to visit for help.

Remember, if you are running PHP in safe mode, move exifextr script to the same directory where convert and identify reside and change the EXIF_SCRIPT variable in config.php3 appropriately.

PhotoArch provides you with opportunity to pick and choose which EXIF options you want to extract and store. As mentioned above, you should run exifdump on one of your images and see what types of EXIF data are available. Next step is to pick the ones that are of interest to you and add them to the space separated array called ExifOpts. They must be spelled exactly the way they appear in the exifdump output.


The next several options govern the appearance of PhotoArch:


- background color of every page


- text color


- hyperlink color


- visited link color


- depressed link color


- size of generated thumbnail images in pixels (thumbnail fits into SIZExSIZE square)


- size of generated loq-quality sample images (stored in the database)


- JPEG quality parameter for thumbnails. The higher the quality, the larger the image


- JPEG quality parameter for sample images. Sample images are the ones that you see by clicking on a thumbnail (search or browse mode). They are also the only large images that unauthenticated users are allowed to see. I would not advise to put it above 50 unless you have oodles of free disk space and bandwidth.


- number of images displayed per page in "Add Volume" and "Search" modes.


- number of rows of thumbnails displayed in "Browse" mode.


- number of columns of thumbnails displayed in "Browse" mode.


- in "Search" and "Browse" modes the thumbnails are displayed inside a dark frame, so they appear like mounted positives (purely for aesthetic purposes). This determines the ratio of the frame size to the thumbnail size.



- location of ImageMagick "convert" executable (if PHP is in safe mode, make sure the directory where it is located is on the safe list)


- location of ImageMagick "identify" executable (if PHP is in safe mode, make sure the directory where it is located is on the safe list)


- location for temporary file storage


- mount point of the CDROM drive


- mount point of a JAZZ drive


- mount point of a ZIP drive


- mount point for some other mountable device


The final adjustable parameters must be changed with caution: their modification must be accompanied by a matching modification of the createtables.sql file, because they have to do with the database structure.


- supported film media types


- supported volume types


- supported graphic file formats/MIME types

No other parameters should be modified in config.php3.

6.5 Security

PhotoArch uses MD5 hashes for passwords, this way they are not stored in cleartext for everyone to see.

For improved security you may want to choose to run PhotoArch over SSL, if your capabilities allow. This will prevent anyone from sniffing out your administrative password, which is the main thing you need to protect.

To that end it is advisable to create a file named .htaccess in the sql/ directory with the following contents:

Order allow,deny
Deny from all

This will prevent enterprising miscreants from directly looking up the password from the SQL scripts.

6.6 Upgrading from the previous version

Mainly you should go over the new config.php3 and restore your settings. Its is a good idea to save your old config.php3 and the compare the two. Starting with ver 1.0 more features have been introduced, so most likely you will not be able to reuse your old config.php3, but they are similar enough so you will have a pretty good idea of what to set things to.

If you used a pre-ver 1.0 PhotoArch (and thank you, by the way), you will need to update tables in your MySQL database. Your existing data will not be disturbed, nor will it affect how your old pics are displayed. It will simply offer you more options with your new pics. Use upgradetables.sql script in sql/ directory:

$ > mysql -u photoarchadmin -p < upgradetables.sql

7. How it all works

7.1 Overview

PhotoArch is built on a slightly different premise than most web photoalbums out there. Its main goal is in assisting the user in keeping track of his/her photography database stored on mountable volumes (CDROMs or other).

Logically the data is represented as follows: images belong to


- each image comes from a negative of some film, which can be referenced. This association is optional. If you don't want to track your pictures by film, you don't have to.


- images are stored on digital volumes, which can be directories on your filesystem or mountable digital volumes (CD-ROMs, JAZZ or ZIP disks, etc)


- images belong to albums which are logical arrangements of images.

What is actually stored in the database, is information about each image, film, volume and album. It is then cross-referenced to make searches possible.

7.2 Adding a new volume to the database

7.3 Volume structure

Unless you are planning to track images by film (in which case you need to read the section entitled 'Correlating film media to digital images'), a volume can have any directory structure you want - it can be completely flat, with all images placed immediately under the volume top directory, or it can have a complex directory structure and depth of your choosing. PhotoArch will index all image files and skip non-image files in the volume.

7.4 Correlating film media to digital images

For those of us who are not blessed with a digital camera, or for some other reason stubbornly insist on using film, PhotoArch offers a unique ability of keeping track of which digital image belongs to which film, allowing you to quickly locate the negatives based on your search in the digital library of PhotoArch.

This requires a special arrangement of files on your digital volumes, to help PhotoArch figure out which images belong to which films. If you plan not to use this feature, you can go ahead and skip this section. You will still be able to correllate images and the digital volumes they came from.

When adding a volume of scanned images which you want to track together with the films they came from, some additional steps are required, as compared to adding a volume of digital pictures which require no correlation to the negatives they came from.

In this case, when adding new images to the database the volume must be structured as follows:

The rest of actions are identical with adding an unstructured volume. One note is that on the same volume you can have directories which are named film## and others that are not. Images in directories named film## will be correllated with film## for future reference. Images in directories named something else will have a film number 0 assigned to them. This film number is reserved, it cannot be deleted, unlike all others.

7.5 Batch processing

New feature in ver 1.0 is the ability to add images in a volume in batches, by skipping the interactive add, in which you tediously enter information for each image. In batch mode you can simply point PhotoArch to a volume directory and click 'SUBMIT' and it will add images under that volume.

A convenient feature for batch processing is the 'Default Album' option in 'Modify/Add digital volume'. Selecting a particular album will put all images in the new volume into this album. This feature also works with interactive mode.

7.6 Viewing images

After you entered images into the database in this manner, they are available for searching and browsing. When a particular image is found, you can readily view the

Additionally, if you wish to view the high-quality version of the image, PhotoArch will attempt to display it off the filesystem. If the image was on a mountable volume, it will request that you mount the volume first.

As explained below, only the administrator and authenticated users are allowed to see the high-resolution images. Unauthenticated users will have to contend with low-quality jpegs stored in the database.

7.7 Albums and Users

The easiest way to search and browse a photo database is by albums. PhotoArch presents extensive features to allow you to do that. Additionally it gives you as the database administrator the ability to select who can view a particular album. This latter feature is achieved through the following:

Each album can have the following permissions:


- album is viewable by anyone

Private with authorizes users

- album is only viewable by certain users, whom you create accounts for with password protection

Totally private

- album is only viewable by the database owner

Each private album can have up to 3 different users who are authorized to view it (not counting the administrator).

When using PhotoArch each user possesses a status, which can be:


- can modify anything in the database. Can view the complete contents of the database.

Authenticated user

- user which supplied a correct password to his/her username. Can view albums that were administratively allowed to him by the administrator and all public albums.

Unauthenticated user

- can only view public albums and only the low-quality sample images. How low a quality is adjusted through the configuration file.

In addition, authenticated users are allowed to view the high-resolution versions of each picture, while unauthenticated users can only view the low-quality samples stored in the database. This is done to save bandwith and compute resources on the server. Additionally, PhotoArch offers dynamic resizing capabilities for high-res images, which can be draining on the server if a large number of users attempt to view the collection.

7.8 Searching and Browsing

PhotoArch gives you the ability to do targeted searches as well as simply browse the database. Searches can be done by any combination of metadata associated with each image: keywords, dates, association with a specific album, film or volume. All search criteria are logically 'AND'ed to produce the final search query.

Browsing on the other hand simply allows you to look through an album sequentially.

Access permissions are always in effect while searching or browsing. Depending on your status, you are allowed to search through or browse only the albums that the administrator wants you to browse.

7.9 Database manipulation

All database functions have a front end in PhotoArch. Users can be assigned to albums at any time and user permissions can be removed from an album at any time by the database owner. You, as the owner, can create and delete users at will.

You can add and delete films, volumes and albums. Keep in mind however, that deleting a volume or a film also deletes all images associated with them. Deleting an album puts all images from that album into the Unfiled album. (Unfiled is a special private album which cannot be deleted or modified)

8. Further Extensions

Things I would like to see done:

9. Acknowledgements

This software contains code written by others:

10. Resources

Most of the resources for PhotoArch can be located through SourceForge: or directly at