PHP Photo Album

Welcome to the PHP Photo Album. The album is capable of managing one album or multiple albums, can display thumbnails, indexes, different sort orders, display only new photos since a user's last visit, and more.

Features

The PHP Photo Album can do all of the following:

Manage and display one or many albums
Handle uploading new photos, with captions
Automatic thumbnail generation on uploads (see below)
Change captions on existing photos
Remove existing photos
Customizable user preferences that are saved in a cookie
Simple posting access control for multiple users in conjunction with HTTP authentication
Optional input sanitizing with Kses.
Customizable colors, images, and page content.
Customizable number of photos displayed at once.
Customizable number of thumbnails to display
Automatic multi-page thumbnail index
Sort photos by date or by name

License

The PHP Photo Album was created by Robert Kesterson (see website), who retains the copyright. Permission is granted to use this script freely for any non-commercial purpose. Commercial users are asked only to notify me that they are using it, at which point I will grant permission. (I just want to know who's using it.) The only caveat is that my copyright notice (which is sent as an invisible HTML comment) must not be removed from the documentation, the script, or its output. If you redistribute the script, you must keep the other files in this archive with it. Kses is written by Ulf Harnhammar under the GPL license, and is distributed with this script as a convenience.

Requirements

This is a PHP script, and as such, requires a PHP-enabled web server. It should work with any PHP version 3 or higher, and is designed to work best with PHP 4. It should work on any platform, though it has been most heavily tested on Linux under the Apache web server. If you want to use PHP image scaling, you'll need PHP 4.3 or later and libgd. (If you don't have that, you can use the included helper app, but you'll need to be able to compile the program for your target system and be able to link with libjpeg. And if you don't have that, the photo album will still work, you just won't be able to get automatic thumbnail generation.)

Intallation

If you just want to have a quick look, drop the entire contents of this directory someplace that your PHP-enabled web server can serve it up, and open the "index.php" file. You won't get some of the more interesting features without configuring your setup, but it should work so you can at least see what it looks like. If you like what you see, do a real installation.

Installation is fairly simple. On your PHP-enabled web server, create a directory and drop the script into it. You will need, at a mimimum, the index.php and config.php files. It is also highly recommended that you include the kses.php file. You will then need to create a directory for each photo album you want to create, named with the name you want people to see. Then configure your options in the config.php file (see below for configuration parameters), upload your pictures, and you're done. You can upload pictures through the script itself, or by FTP or whatever. In order for the album to display a photo, there must be three files present -- the file itself, the thumbnail, and the caption. These are named (for example) filename.jpg, filename.thumb.jpg, and filename.caption. Each photo in the album will have those three files, named appropriately. If you upload using the script, the proper files are generated automatically. If you do it manually (handy for large groups of images), just make sure you name the files appropriately. Notice that you will probably want to change the "config.php" file to match your setup. If nothing else, you'll want to change the domain name and user names for yourself to match what you're really using. For more detail, see the configuration section below.

Multi-user Intallation

If you want to have access control, uploads, editing, and so on, you have to set it up as multi-user, even if you yourself are the only user. (Actually, you really aren't the only user -- everybody on the internet is a potential user, you're just the only one who can post anything.) To do so, you'll need to set up HTTP basic authentication to allow you to log into your site and thus establish your username. When you log in with a username, this is checked against the configuration of the script and the individual albums to see whether upload and admin functions should be available to you for that album. HTTP basic authentication setup is not difficult, but is beyond the scope of this document. See the documentation for your web server for details. (Note that you only need the authentication to establish your username -- you don't have to restrict access to only those with a login. One simple trick if you want a public album that anyone can see but only you can modify is to create a second directory. Do your HTTP basic authentication on *that* directory, and from there, have a symlink that points to your album directory. So once you log in, you click the symlink, and you're authenticated in the album and can make your changes.)

Usage

Once you have the photo album installed (see previous section), usage is very simple. An image panel is displayed with three sections. The center section shows the current image(s) being displayed. The left section shows thumbnails of images prior to the current display, and the right section shows thumbnails of images which follow the current display.

To navigate, either click the previous and next buttons at the lower left and right, or click on any of the thumbnails to jump directly to that photo. If you like, you can click the index button to see an index of thumbnails that you can click to skip quickly to a different album page.

Above the main album display is a drop-down list of photo albums. (Note: This can be turned off.) Selecting a different photo album from the list and clicking "go" will take you to the first page of that album.

Below the main album display is the user preferences section. It contains four items which have the following functions:

Show Albums: When using multiple albums, select whether to show only the ones which actually contain photos, or to show all of them.
Show Pictures: For users who have visited before, choose whether to show all photos, or only photos which are newer than their last visit date.
Show Link URLs: Whether to display an URL below each photo that the user could cut and paste to link to each photo album page.
Sort Photos By: Choose whether to sort photos by date (oldest first or newest first) or by name.

After changing any of these settings, the user must click "Apply". The preferences will then be written to a cookie and take effect. If the user has cookies disabled, the page will reload with those settings, but they will be ignored on subsequent pages.

Uploading Photos

If uploading is allowed for you in the album which you are currently viewing, a button will appear at the top that will allow you to add a photo to the current album. Clicking it will present a form where you can enter the filename to upload, and a caption to be displayed with the photo. Thumbnails will be generated automatically. [b]Note that only JPG images are supported.[/b] Once you have entered the caption and selected the file to add, hit "Upload!" and your photo will be added to the album. You may also manually upload photos, which can be a much faster method when dealing with large numbers of photos. To do so, each photo must have the photo itself, a thumbnail, and a caption. These must be named with ".jpg", ".thumb.jpg", and ".caption" extensions, respectively. For example, if you have a photo called "fish.jpg", then you would create a small thumbnail called "fish.thumb.jpg", and then whatever text you want in a file called "fish.caption". When you manually put those in the album directory (via FTP or whatever), they will automatically show up in the album.

Administration

If you are logged in as a user with administration privileges to the current album, the main album display will contain two additional buttons -- one to change the caption, and one to delete the photo. Pressing "Change Caption" will present a text bow where you can change the existing photo's caption. Choosing to delete the photo will first ask for confirmation, and then delete the photo.

Configuration Parameters The following parameters control the PHP Photo Album. These are set in the global configuration file "config.php". If you like, you can override these parameters for each album by putting a config.php file in the album directory. Parameters in the album's config.php will take precedence over the global options.

$Domain The domain part of your web address. This is used to set cookies for preferenced. Typically, this will be something like ".yourdomain.com". Note the leading dot, which is required.

$AdminOwner What username can administer any album or photo?

$DefaultAlbum The album (directory) to display by default

$PublicAlbums A colon-separated list of album(s) where anyone may upload a photo

$ShowByLines Whether to show who uploaded a photo (either "Yes" or "No")

$SanitizeInput Whether to sanitize uploaded captions via the kses html input filter.

$albumdir The directory where your albums are stored. This should be a relative path based on the directory the script runs from. Each album is then contained in a subdirectory of your albumdir directory.

$scriptlocation The filename of the script itself. This is used in generating requests from the web server.

$numthumbs How many thumbnails to show in the left or right panels.

$ThumbsPerRow How many thumbnails to show in each row in the index. It will also show this many rows, so setting it to "5" would show 5 rows of 5 thumbnails in the index.

$numcols How many columns to show in the main photo display section

$numrows How many rows to show in the main photo display section

$prevbutton Image filename to use for the "previous" navigation button. This should be relative to the directory the script runs from.

$nextbutton Image filename to use for the "next" navigation button. This should be relative to the directory the script runs from.

$indexbutton Image filename to use for the "index" navigation button. This should be relative to the directory the script runs from.

$SortOrder Order in which to display the photos. Either "N" for name order, "D" for date order (oldest first), or "R" for date order (newest first)

$ThumbFontColor The font color to use for the thumbnail areas

$ThumbBGColor The background color to use for the thumbnail areas

$NavFontColor The font color to use for the navigation areas

$NavBGColor The font color to use for the navigation areas

$ThumbBGImage Optional background image to use for the thumbnail areas

$AlbumBGColor The background color to use for the main display area

$AlbumBGImage Optional background image to use for the main display area

$CaptionFontColor The font color to use for the captions

$CaptionFontStartStyle Any extra HTML tags to prepend to the caption. You could open bold, italics, or whatever tags here. These are passed through unchanged.

$CaptionFontEndStyle Any extra HTML tags to append to the caption. You could close bold, italics, or whatever tags here. These are passed through unchanged.

$HeaderFile A partial HTML file to output unmodified before the output of the photo album. This can be used to "embed" the photo album in an HTML page. Just split it where you want the album to appear, storing the first part here, and the second part in $FooterFile. Filenames are relative to the album directory, so you may need a "../" if you have them in the same directory with the script. Also remember that these can be changed on a per-album basis by using a config.php for that album to override this.

$FooterFile A partial HTML file to output unmodified after the output of the photo album. See the discussion of $HeaderFile for more info.

$GenHeaders Set to "Yes" to have the script generate its own HTML headers. This is used if you want to run the script with no $HeaderFile. If you have a $HeaderFile, set this to "No".

$ShowAlbumList Whether to show the album list. This is useful if you only have a single album (in which case the list would be pointless). Set it to "Yes" or "No" as appropriate.

$PhotoHeight The height to constrain uploaded photos to. This prevents someone from uploading a gigantic image which would put undue load on the system.

$ThumbHeight The height for the generated thumbnails. A good value is 100.

$ShowLinks Whether to show an HTML link to the photos that users can copy/paste elsewhere.

$UsePHPScaling Whether to use PHP's image scaling capabilities. This requires PHP 4.3 or later, and libgd 2.0 or later. If you don't have these versions, you can still get automatic thumbnail generation, but it will require an external program (see "makethumb.c" in the "helpers" directory of this distribution).

$Domain		The domain part of your web address. This is used to set cookies for preferenced. Typically, this will be something like ".yourdomain.com". Note the leading dot, which is required.
$AdminOwner		What username can administer any album or photo?
$DefaultAlbum		The album (directory) to display by default
$PublicAlbums		A colon-separated list of album(s) where anyone may upload a photo
$ShowByLines		Whether to show who uploaded a photo (either "Yes" or "No")
$SanitizeInput		Whether to sanitize uploaded captions via the kses html input filter.
$albumdir		The directory where your albums are stored. This should be a relative path based on the directory the script runs from. Each album is then contained in a subdirectory of your albumdir directory.
$scriptlocation		The filename of the script itself. This is used in generating requests from the web server.
$numthumbs		How many thumbnails to show in the left or right panels.
$ThumbsPerRow		How many thumbnails to show in each row in the index. It will also show this many rows, so setting it to "5" would show 5 rows of 5 thumbnails in the index.
$numcols		How many columns to show in the main photo display section
$numrows		How many rows to show in the main photo display section
$prevbutton		Image filename to use for the "previous" navigation button. This should be relative to the directory the script runs from.
$nextbutton		Image filename to use for the "next" navigation button. This should be relative to the directory the script runs from.
$indexbutton		Image filename to use for the "index" navigation button. This should be relative to the directory the script runs from.
$SortOrder		Order in which to display the photos. Either "N" for name order, "D" for date order (oldest first), or "R" for date order (newest first)
$ThumbFontColor		The font color to use for the thumbnail areas
$ThumbBGColor		The background color to use for the thumbnail areas
$NavFontColor		The font color to use for the navigation areas
$NavBGColor		The font color to use for the navigation areas
$ThumbBGImage		Optional background image to use for the thumbnail areas
$AlbumBGColor		The background color to use for the main display area
$AlbumBGImage		Optional background image to use for the main display area
$CaptionFontColor		The font color to use for the captions
$CaptionFontStartStyle		Any extra HTML tags to prepend to the caption. You could open bold, italics, or whatever tags here. These are passed through unchanged.
$CaptionFontEndStyle		Any extra HTML tags to append to the caption. You could close bold, italics, or whatever tags here. These are passed through unchanged.
$HeaderFile		A partial HTML file to output unmodified before the output of the photo album. This can be used to "embed" the photo album in an HTML page. Just split it where you want the album to appear, storing the first part here, and the second part in $FooterFile. Filenames are relative to the album directory, so you may need a "../" if you have them in the same directory with the script. Also remember that these can be changed on a per-album basis by using a config.php for that album to override this.
$FooterFile		A partial HTML file to output unmodified after the output of the photo album. See the discussion of $HeaderFile for more info.
$GenHeaders		Set to "Yes" to have the script generate its own HTML headers. This is used if you want to run the script with no $HeaderFile. If you have a $HeaderFile, set this to "No".
$ShowAlbumList		Whether to show the album list. This is useful if you only have a single album (in which case the list would be pointless). Set it to "Yes" or "No" as appropriate.
$PhotoHeight		The height to constrain uploaded photos to. This prevents someone from uploading a gigantic image which would put undue load on the system.
$ThumbHeight		The height for the generated thumbnails. A good value is 100.
$ShowLinks		Whether to show an HTML link to the photos that users can copy/paste elsewhere.
$UsePHPScaling		Whether to use PHP's image scaling capabilities. This requires PHP 4.3 or later, and libgd 2.0 or later. If you don't have these versions, you can still get automatic thumbnail generation, but it will require an external program (see "makethumb.c" in the "helpers" directory of this distribution).