AtWillys.de

Force nullmailer to use a fixed “from” address

stfwi — Wed, 25 Jan 2012 22:51:54 +0000

As small replacement for postfix and the like, nullmailer has established on the one and other Linux home server – such as mine. My specific problem with the provider/email relay: They check if the sender email address matches the relay account email address to prevent spam. That’s a good feature, but nullmailer uses actual user@host, where host defaults to the content of /etc/mailname (e.g. root@myserver.dyndns.org or www-data@myserver.dyndns.org). Nullmailer has no rewrite functionality based on config files, but in the specific case a simple (but not completely accurate) solution can be applied:

# 1) Rename the original sendmail binary:
$ mv /usr/sbin/sendmail /usr/sbin/sendmail-bin

# 2) Create and edit a script called sendmail:
$ touch /usr/sbin/sendmail
$ chmod 755 /usr/sbin/sendmail

Edit the sendmail script file and paste this content:

#!/bin/bash
/usr/sbin/sendmail-bin $@ -f `cat /etc/nullmailer/forced-from` 
The script simply forwards all arguments and the STDIN to the original sendmail, but adds the -f argument to replace the from address. In my case, I save the full sender address of the relay account in the file /etc/nullmailer/forced-from. That’s it. 
There are two things I did not test yet:

After done a test with PHP and “sendmail -f www-data” in the php.ini, I assume that the last “-f SENDER-EMAIL” argument that occurs will be the used one. No idea if this will be that way for all time. The argument list will have to be filtered then.
What does the package manager/aptitude do with this when removing, updating, etc. (That’s why I say not really accurate :-) )

Mount a FTP connection in your file system on Ubuntu

stfwi — Mon, 19 Sep 2011 00:05:18 +0000

I was just looking for an easy and strict way to process files and directories via FTP (in a shell script) and stumbled over the CurlFtpFS, which allows you to mount an FTP connection as part of your file system. Extremely nice and elaborated solution these guys implemented. You can either mount it using sudo e.g. in /mnt/ftp/hostname or simply in your home directory, e.g. “~/ftp”. As Bob Ross used to say: “And it’s really that simple”.

Installation

sudo aptitude install curlftpfs

Mount

# Create a directory to have a mount point
mkdir ~/ftp

# To directly connect with username and password in the command line:
sudo curlftpfs username:password@host.or.domain ~/ftp

# If you want to type the password in the shell:
sudo curlftpfs -o user="username" host.or.domain ~/ftp

# To check if's mounted
mount
# You get a list that should include the line like:
#   curlftpfs#.... on ..../ftp type fuse (rw,nosuid,nodev,user=....)

Unnount

sudo umount ~/ftp

Annotation: I added sudo because you very likely cannot unmount the drive without root permissions, even not in your home folder.

Boot camp with Windows 7 and a SSD

stfwi — Sat, 17 Sep 2011 20:37:00 +0000

As not all programs are available on MacOS 10.7, you may want to install Windows 7 either on a virtual machine or, to get the whole performance of your machine, on a Boot Camp partition. As described in the last article, I switched to a Vertex 2 SSD, which is much faster then the HDD before, but provides with 240GB only half of the space compared to the replaced hard disk. As a very result, I didn’t want to waste space on a second partition that needs already more than 20GB for the operating system (we can forgive Steve Jobs that Lion has a similar disk usage, but for any reason we can’t forgive Steve Ballmer). So, 50GB was my choice for the Boot Camp partition, and the Windows 7 space had to be trimmed somehow. The major issue was to prevent that the disk usage grows too much after the installation (due to indexing, backups, shadow images, memory dumps etc). The updates will increase the required space enough anyway. Furthermore, SSDs and convendtional HDDs require different handling, e.g. SSD do not need to be defragmented. Here are the steps that helped me keeping the system clean and speedy. I hope it helps you, too. Note: Every change has its side effects, so checkout if you need a feature or not.

Cleanup and removing the disk shadow copy

A simple way of freeing space is to use the normal disk cleanup. This package also contains the functionality to remove a disk shadow copy.

Go to START > Computer
Right click on drive C:, select “Properties”
Switch to tab “General” and click the “Disk Cleanup” button
If the button “Cleanup system files” is shown, click it
The tab “More options” should be visible, switch to it
Under “System Restore and Shadow Copy”, click “Cleanup” and confirm the deletion

Disable Hybernation

Hybernation is principally a good thing. However, it has the side effect that a file is created, which contains the RAM state during hybernation. Depending on the RAM size, this preserves gigabytes of disk space (in my case a 1/6 of the disk space!), and the file is not deleted after hybernation. Disabling it is easy (the file will be automatically removed). Side effect: The system can only switch to sleep mode, which still requires battery. If latter is empty Windows would normally hybernate, but can’t. So it will either force a shutdown or just go off.

Click START, search “cmd.exe”, and run it as admin (don’t hit RETURN, but right click on the found item “cmd.exe”)
Enter “powercfg -h off” in the shell window

Disabling Indexing service

The indexing service is the Windows-Spotlight background task and uses disk space as well. Side effects: Finding programs and files still works, but more detailled searches, such as words in mails or PDFs does not work.

Go START:, search for “services.msc”
Locate “Windows Search Service”, right click: Properties
Select “disabled” in the dropdown “Startup type”

Trimming page file size

The page file is the virtual memory and similar to the scratch partition. It can grow quite a lot. Side effects: You could run out out of memory. This never happend to me up to now, but if you use Software, which needs huge amount of RAM … well – could happen that the program crashes or throws an allocation error.

Go START
Right click on “Computer”, select “Properties” from menu
Select “Advanced System Settings” on the left side menu
Under “Performance”, click on the “settings” button
Click the “Advanced tab”
In section “Virtual memory” click on “Change”
Uncheck “Automatically manage paging file size [...]“
Click option “Custom size” enter “500″ under Initial size and what you want (e.g. 1000 for 1GB) for maximum size.

Disable System Restore

The System Restore Points are principally a good Idea, but they need space. Here how to disable this feature. Side effects: You don’t have a direct undo operation for your system setup (I use incremental network backups to get around this problem).

Go START, search for “gpedit.msc” and hit return
Browse to the folder “Local Computer Policy”/”Administrative Templates”/”Windows Components”/”Backup”/”Client”
Double click “Turn off the ability to back up data files” and select the “enabled” option. (Yes, it is ENABLED), click OK
Double click “Turn off restore functionality” and select the “enabled” option. Click OK
Double click “Turn off the ability to create a system image” and select the “enabled” option. Click OK

Disable Defrag schedule

SSDs don’t need to be defragmented, indeed it is a waste of resources and decreases the life time unnecessarily.

Go to START/All Programs/Accessories/System Tools/Disk Defragmenter
Click the “Configure Schedule” button
Untick the checkbox “Run on a schedule (recommended)”

Disable MacOS X partition visibility

If you don’t want that windows programs can access your Mac partition, you can unassign its drive letter. This is not a “really secure security feature”, but it should help a bit, because admin permissions are required to reassign a drive letter.

Click START, search for “Administrative Tools”
Doubleclick on “Computer Management”
Click in the side bar on “Disk Management” (in folder “Storage”)
Right click on the partition, which file system is HFS and select from the context menu “Change drive letter and paths”
Remove the drive letter by clicking the “Remove” button and ignore the warning that programs may rely on this drive.

References

Migrate Mac OS 10.7 Lion on a OCZ Vertex SSD in a unibody MacBook Pro

stfwi — Fri, 16 Sep 2011 22:58:55 +0000

To speed up my unibody MacBook Pro (6,2) I decided to replace the internal hard disk with a SSD (OCZ-Vertex 2, 240GB, SATA2/3Gbps, Rev. 1.33). After browsing loads of tutorials I found another really easy way to put Lion on the blank disk. I have no confirmation if this is really the “master way” and that complications or side effects are impossible, but it works without 3rd party software, without shell commands, but only with Apple software and the tools you use anyway.

I assume you have already have …

an installed and functioning system in on your internal hard disk. If this is a MacOS 10.6 Snow Leopard installation, you must upgrade to Lion, because the Recovery Disk Assistant will be used, which is not available under 10.6 yet.
a Time Machine disk
a “scrap” USB stick or old USB hard disk. The Apple guys say it must have at least 1GB space.

Installation sequence

Make Time Machine backup
Remove large files (videos, music, photos, etc) from your internal hard disk until the used disk space is less than the disk size of the SSD. (I simply removed almost all media files and had 90GB disk usage after this cleanup. No applications or settings in the Library deleted.) A software which helped me quite well finding the space wastes was WhatSize. Probably you could use some cleanup programs as well to reduce the used disk space first (I didn’t). I would definitely propose to remove more rather than less. You can get the stuff back from the backup anyway.
Make a Time Machine backup again. This backup will be the one to migrate later on.
Download the Lion Recovery Disk Assistant. Additional information about this Apple software can be found in the article OS X Lion: About Lion Recovery Disk Assistant.
Connect the USB disk and format it with a HFS+ filesystem using the the Disk Utility. Then run downloaded Recovery Disk Assistant, which will detect the USB disk (“follow the instructions :-)”. In my case it was a 8GB USB stick (one of the d**ned Cuiser sticks), I repartitioned it with one partition, Journaled HFS+, partition name: “LionRecovery”).
Replace the internal HDD with the SSD. A good Tutorial by mefouryou how to do this can be found at YouTube: How to Install an SSD Into a Unibody MacBook Pro.
Switch on your notebook, press the option-key until the boot menu shows up, and boot from your Lion Recovery disk.
Plug in the Time Machine backup disk and choose the “Restore From Time Machine Backup” option. In my case the process took about 1 hour. After finishing the restore procedure, the notebook restarted and I could log in as usual.

Conclusion and annotations

After restoring on the SSD, the system worked out of the box. All settings I checked, such as saved passwords in Safari, Bookmarks, and the like were unchanged. Mail asked to import already existing emails and did this without any side effects. However, some Adobe programs had trouble with the licensing, so I had to uninstall (inclusively removing the settings in ~/Library) and reinstall them. Word 2011 wanted the CD key again (probably because the Hardware ID changed). The processor load was quite high after the installation due to the Spotlight indexing process. The next Time Machine backup, which I did directly after the migration, had a size of 75GB.

Some SSD related settings

As they are some differences between SSDs and HDDs, here some further things you may want to do:

Disable sudden motion sensor, which protects the disk mechanics if you drop your notebook. As SSDs have no mechanical parts, disable it in the terminal: sudo pmset -a sms 0
Enable TRIM support. Lion enables TRIM for Apple SSDs, but not for Vertex 2. I don’t like to present a solution on this site because this issue and its solution is a quite dynamic and not long time tested affaire at the moment. One of the referred discussions is http://notebooksnews.com/apple/enable-trim-mac-os-x-lion/. I have no idea if this will work for future versions, so search the internet for the actual solutions!
Disable hard drive sleep: It’s no advantage to put SSDs into sleep mode. You can switch this off in the System preferences section “Energy Saver” by unticking the “Put hard disks into sleep when possible” checkbox for both Battery and Power tabs.
You can free some disk space by disabling the hibernation mode. (This is not directly related to the handling of the SSDs, but general disk usage). Setting the sleep mode settings from 3 to 0 does this: sudo pmset -a hibernatemode 0. You can then remove the sleep image: sudo rm /var/vm/sleepimage.

Summa Summarum: After determining what to do, the whole migration took effectively about 2.5 hours of my lifetime – which is less than fixing the last compilation issue with MacPorts …

Mantis installation script for Ubuntu 10.04

stfwi — Thu, 25 Aug 2011 18:52:54 +0000

The MantisBT is a PHP/MySQL based issue tracking system, licensed under the GPL and quite popular in the open source community to deal with software bugs. There are different ways to install MantisBT on your Ubuntu 10.04 server (e.g. aptitude), but if you want a one-shot preconfigured system in your /var/www/ folder, take a look at this small blog article.

Sequence:

If not yet installed, install GIT using sudo aptitude install git (GIT is good anyway :) ). This is needed because the script gets the latest repository snapshot with all the nice bug fixed.
Download and extract the ZIP archive in your server home directory or /tmp/”,
Run in the shell ./mantis-setup/setup install (I used myself database name=”mantisbt”, database user=mantisbt). Well, please don’t choose a user name or database name that already exists, I did not check what happens then. It’s anyway better to have all database stuff this separated.

What happens then?

The script downloads MantisBT with the plugins source-integration and meta using GIT,
modifies the config_inc.php file of the MantisBT,
adapts the file/directory permissions for Apache2 (www-data, if you have another user/group, then modify the script file header, ou can’t miss it)
generates the database and the database user (the database contents are copied from the SQL file “copytables.sql”),
generates an individual SALT value for your BT system encryption
moves the whole folder structure to /var/www/mantisbt.

Result

You can access the bugtracker using http://yourserver.wtf/mantisbt
Login: “administrator”, password: “root”. Don’t forget to change it directly.
Installed plugins: “meta” and “source-integration”

Installation script source code

#!/bin/bash

#########################################################################################
## Settings
#########################################################################################

APTITUDE='/usr/bin/aptitude'
WWW_ROOT="/var/www"
APACHE_USER="www-data"
APACHE_GROUP="www-data"
TEMP_DIR="/tmp/mantis-setup"
GIT="/usr/bin/git"
MANTIS_GITHUB_URL="https://github.com/mantisbt/mantisbt.git"
MANTIS_GIT_PLUGIN_SOURCE_URL="git://git.mantisforge.org/source-integration.git"
MANTIS_GIT_PLUGIN_META_URL="git://git.mantisforge.org/meta.git"
WWW_MANTIS_DIRNAME='mantis'
DB_MYSQL_ROOT_PASS="$2"
DB_NAME="$3"
DB_USER="$4"
DB_PASS="$5"
DB_HOST='localhost'
CRYPTO_SALT="$(cat /dev/urandom | head -c 64 | base64 -w 1000)"

pushd . > /dev/null
cd "$(dirname $0)"
SCRIPT_DIR="$(pwd)"
popd > /dev/null

#########################################################################################
## Program starts here
#########################################################################################

# functions
function echo_error()  { echo -e "\033[0;31m[FAILED] $@\033[0m"; }
function echo_ok()     { echo -e "\033[0;32m[OK] $@\033[0m"; }
function echo_info()   { echo -e "\033[0;33m$@\033[0m"; }

function set_php_var() {
	sudo grep -Fq "${1}" "${3}";
	if [ $? -eq 0 ]; then
		sudo sed -i "s,${1}.*,${1} = ${2};," "${3}";
	else
		sudo sed -i "\$a\\${1} = ${2};" "${3}";
	fi;
}

function print_usage() {
	echo "Usage:"
	echo ""
	echo " To install:"
	echo "   $SCRIPT_DIR install    "
	echo ""
	echo " To uninstall:"
	echo "   $SCRIPT_DIR uninstall --really"
	echo ""
	exit
}

function chmod_chown_wwwdata() {
	echo_info "Changing file modes/owner/group to make them suitable for Apache"
	sudo chown -R $APACHE_USER:$APACHE_GROUP $TEMP_DIR/mantisbt
	sudo find . -type d -exec chmod 550 {} \;
	sudo find . -type f -exec chmod 440 {} \;
}

# uninstall process
if [ "$1" = "uninstall" ]; then
	if [ "$2" != "--really" ]; then
		echo_error 'You must say "setup uninstall --really"'
		exit
	fi
	echo_error "TODO: IMPLEMENT UNINSTALLER"
	sudo echo ""
	echo_info "----------------------------------------------------------------------"
	echo_info "UNINSTALL"
	echo_info "----------------------------------------------------------------------"
	echo_info "remove mantis ..."

	if [ ! -d $WWW_ROOT ]; then
		echo_error "Web root directory not there ($WWW_ROOT)"
		exit
	elif [ ! -d $WWW_ROOT/$WWW_MANTIS_DIRNAME ]; then
		echo_error "Mantis is not installed in $WWW_ROOT/$WWW_MANTIS_DIRNAME"
		exit
	fi

	sudo rm -rf $WWW_ROOT/$WWW_MANTIS_DIRNAME

	echo_info "NOTE: DATABASE WILL NOT BE DELETED"
	echo_ok "uninstalled"
	exit
elif [ "$1" = "install" ]; then
	# mark sudo
	sudo echo ""

	if [ ! -d $WWW_ROOT ]; then
		echo_error "Web root directory not there ($WWW_ROOT)"
		exit
	elif [ "$4" = "" ]; then
		print_usage
	elif [ -d $WWW_ROOT/$WWW_MANTIS_DIRNAME ]; then
		echo_error "Mantis is already installed in $WWW_ROOT/$WWW_MANTIS_DIRNAME"
		exit
	fi

	if [ "$DB_NAME" = "" -o "$DB_USER" = "" -o "$DB_PASS" = "" ]; then
		echo_error "You must set database name, user and password."
	fi

	echo_info "Preparing temporary direcory"
	pushd . &> /dev/null
	mkdir $TEMP_DIR
	cd $TEMP_DIR

	echo_info "Cloning mantis from github"
	if [ ! -d "$TEMP_DIR/mantisbt" ]; then
		# get mantis
		$GIT clone $MANTIS_GITHUB_URL
		echo_info "(To ensure compatibility when generating the database structure,"
		echo_info " we checkout release-1.2.6, can be updated later ...)"
		cd $TEMP_DIR/mantisbt
		$GIT checkout release-1.2.6
		rm -rf .git

		# get source-integration
		cd $TEMP_DIR/mantisbt/plugins
		$GIT clone "$MANTIS_GIT_PLUGIN_SOURCE_URL"
		if [ ! -d "$TEMP_DIR/mantisbt/plugins/source-integration" ]; then
			echo_error "Failed to get source-integration plugin from $MANTIS_GIT_PLUGIN_META_URL"
		else
			mv $TEMP_DIR/mantisbt/plugins/source-integration/Source* $TEMP_DIR/mantisbt/plugins
			rm -rf $TEMP_DIR/mantisbt/plugins/source-integration
		fi

		# get meta
		cd $TEMP_DIR/mantisbt/plugins
		$GIT clone "$MANTIS_GIT_PLUGIN_META_URL"
		if [ ! -d "$TEMP_DIR/mantisbt/plugins/meta" ]; then
			echo_error "Failed to get meta plugin from $MANTIS_GIT_PLUGIN_META_URL"
		else
			mv $TEMP_DIR/mantisbt/plugins/meta/Meta $TEMP_DIR/mantisbt/plugins/
			rm -rf $TEMP_DIR/mantisbt/plugins/meta
		fi

		# finish git clone stuff
		cd $TEMP_DIR/mantisbt
	fi

	if [ ! -d "$TEMP_DIR/mantisbt" ]; then
		echo_error "Mantis was not cloned from git"
	fi

	echo_info "Processing $TEMP_DIR/mantisbt/config_inc.php"
	sudo chown -R $USER:$USER $TEMP_DIR/mantisbt
	sudo rm $TEMP_DIR/mantisbt/config_inc.php &> /dev/null
	sudo cp -f $TEMP_DIR/mantisbt/config_inc.php.sample $TEMP_DIR/mantisbt/config_inc.php
	set_php_var '$g_hostname' '"'"$DB_HOST"'"' $TEMP_DIR/mantisbt/config_inc.php
	set_php_var '$g_db_username' '"'"$DB_USER"'"'  $TEMP_DIR/mantisbt/config_inc.php
	set_php_var '$g_db_password' '"'"$DB_PASS"'"'  $TEMP_DIR/mantisbt/config_inc.php
	set_php_var '$g_database_name' '"'"$DB_NAME"'"'  $TEMP_DIR/mantisbt/config_inc.php
	set_php_var '$g_allow_signup' 'false'  $TEMP_DIR/mantisbt/config_inc.php
	set_php_var '$g_allow_anonymous_login' 'false'  $TEMP_DIR/mantisbt/config_inc.php
	set_php_var '$g_crypto_master_salt' '"'"$CRYPTO_SALT"'"'  $TEMP_DIR/mantisbt/config_inc.php
	#sudo cat $TEMP_DIR/mantisbt/config_inc.php

	echo_info "Changing file modes/owner/group to make them suitable for Apache"
	sudo chown -R $APACHE_USER:$APACHE_GROUP $TEMP_DIR/mantisbt
	sudo find . -type d -exec chmod 550 {} \;
	sudo find . -type f -exec chmod 440 {} \;

	echo_info "Generating database"
	sudo cp "$SCRIPT_DIR/dbcreate.sql" "$TEMP_DIR/dbcreate.sql"
	sudo chmod 666 "$TEMP_DIR/dbcreate.sql"
	sudo sed -i "s/@@@mantisbt_db/$DB_NAME/" "$TEMP_DIR/dbcreate.sql"
	sudo sed -i "s/@@@mantisbt_user/$DB_USER/" "$TEMP_DIR/dbcreate.sql"
	sudo sed -i "s/@@@mantisbt_pass/$DB_PASS/" "$TEMP_DIR/dbcreate.sql"
	sudo cat "$SCRIPT_DIR/copytables.sql" >> "$TEMP_DIR/dbcreate.sql"
	sudo cat "$SCRIPT_DIR/dbcreate-finish.sql" >> "$TEMP_DIR/dbcreate.sql"

	echo_info "Running mysql, you must enter the mysql root password now"
	#cat "$TEMP_DIR/dbcreate.sql"
	if [ "$DB_MYSQL_ROOT_PASS" = "" ]; then
		mysql --user="root" -p < "$TEMP_DIR/dbcreate.sql"
	else
		mysql --user="root" --password="$DB_MYSQL_ROOT_PASS" < "$TEMP_DIR/dbcreate.sql"
	fi
	sudo rm "$TEMP_DIR/dbcreate.sql"

	# Finish install
	echo_info "Moving to www root"
	sudo mv $TEMP_DIR/mantisbt $WWW_ROOT/$WWW_MANTIS_DIRNAME
	echo_info "Renaming mantis admin path ($WWW_ROOT/$WWW_MANTIS_DIRNAME/admin)"
	sudo mv $WWW_ROOT/$WWW_MANTIS_DIRNAME/admin $WWW_ROOT/$WWW_MANTIS_DIRNAME/.admin
	popd &> /dev/null
	echo_info "Removing temp directory"
	sudo rm -rf $TEMP_DIR &> /dev/null

	echo_info "NOTE: You can now login as administrator under /$WWW_MANTIS_DIRNAME/index.php"
	echo_info "      login name: administrator"
	echo_info "      login pass: root"
	echo_info "      AND YOU SHOULD CHANGE THIS PASSWORD IMMEDIATELY"

	echo_ok "Installed"
else
	echo 'You mus say "install" or "uninstall"'
	exit
fi

Output

The script output should look similar to this (just in color):

foo@host:~/ubuntu-setup-scripts/mantis$ ./setup install "*******************" mantisbt mantisbt "****************"

Preparing temporary direcory
Cloning mantis from github
Initialized empty Git repository in /tmp/mantis-setup/mantisbt/.git/
remote: Counting objects: 64350, done.
remote: Compressing objects: 100% (11204/11204), done.
remote: Total 64350 (delta 52967), reused 63836 (delta 52508)
Receiving objects: 100% (64350/64350), 22.87 MiB | 1.10 MiB/s, done.
Resolving deltas: 100% (52967/52967), done.
(To ensure compatibility when generating the database structure,
 we checkout release-1.2.6, can be updated later ...)
Note: checking out 'release-1.2.6'.

You are in 'detached HEAD' state. You can look around, make experimental
changes and commit them, and you can discard any commits you make in this
state without impacting any branches by performing another checkout.

If you want to create a new branch to retain commits you create, you may
do so (now or later) by using -b with the checkout command again. Example:

  git checkout -b new_branch_name

HEAD is now at 89738d5... Bump
Initialized empty Git repository in /tmp/mantis-setup/mantisbt/plugins/source-integration/.git/
remote: Counting objects: 2442, done.
remote: Compressing objects: 100% (651/651), done.
remote: Total 2442 (delta 1693), reused 2442 (delta 1693)
Receiving objects: 100% (2442/2442), 369.03 KiB, done.
Resolving deltas: 100% (1693/1693), done.
Initialized empty Git repository in /tmp/mantis-setup/mantisbt/plugins/meta/.git/
remote: Counting objects: 9, done.
remote: Compressing objects: 100% (7/7), done.
remote: Total 9 (delta 0), reused 9 (delta 0)
Receiving objects: 100% (9/9), 12.59 KiB, done.
Processing /tmp/mantis-setup/mantisbt/config_inc.php
Changing file modes/owner/group to make them suitable for Apache
Generating database
Running mysql, you must enter the mysql root password now
Moving to www root
Renaming mantis admin path (/var/www/mantis/admin)
Removing temp directory
NOTE: You can now login as administrator under /mantis/index.php
      login name: administrator
      login pass: root
      AND YOU SHOULD CHANGE THIS PASSWORD IMMEDIATELY
[OK] Installed

This Article is also available in Deutsch.

Connect Drupal 7 to SabreDAV

stfwi — Thu, 25 Aug 2011 07:34:01 +0000

One of the best Apache2 compatible WebDAV server implementations is the object oriented PHP implementation SabreDAV. If you use a Drupal for your content management and like to add a WebDAV file storage, you can connect SabreDAV to the Drupal user database. You can to this by using the Drupal module DP UserConnector (http://drupal.org/project/udc, the project is used in the implementation of the Sabre_DAV_Auth_IBackend interface, as shown in this source code:

SabreDAV BasicAuth implementation and server run

dpu ? null : $this->dpu->name;
    }

    /**
     * Authenticates the user based on the current request.
     * If authentication is succesful, true must be returned.
     * If authentication fails, an exception must be thrown.
     * @throws Sabre_DAV_Exception_NotAuthenticated
     * @return bool
     */
    public function authenticate(Sabre_DAV_Server $server,$realm) {

        // Assuming we only accept https for basic auth
        if(!isset($_SERVER['HTTPS']) || $_SERVER['HTTPS'] != 'on') {
            throw new Sabre_DAV_Exception_NotAuthenticated('HTTPS only');
        }

        // Prepare SabreDav auth instances, get user & password pair
        $auth = new Sabre_HTTP_BasicAuth();
        $auth->setHTTPRequest($server->httpRequest);
        $auth->setHTTPResponse($server->httpResponse);
        $auth->setRealm($realm);
        $userpass = $auth->getUserPass();

        // Pre check
        if(!$userpass) {
            $auth->requireLogin();
            throw new Sabre_DAV_Exception_NotAuthenticated('No basic authentication headers were found');
        }

        // Assuming DRUPAL ROOT = $_SERVER['DOCUMENT_ROOT']
        require_once($_SERVER['DOCUMENT_ROOT'] . '/sites/all/modules/udc/client/DrupalUserAuth.class.inc');

        // The token used to connect to DP
        DrupalUserBase::setToken("---my---token---here---");

        // Authentification request
        $dpu = new DrupalUserAuth();
        $dpu->request(
            $userpass[0],    // user name
            $userpass[1],     // pass
            null,            // email
            true,            // active users only
            null            // no profile fields to fetch
        );

        // Validation
        if (!$dpu->valid) {
            $auth->requireLogin();
            throw new Sabre_DAV_Exception_NotAuthenticated('Username or password does not match');
        } else {
            $this->dpu = $dpu;
            return true;
        }
    }
}

// Directory structure of this sample code:
//
// drwx  - document root (www-data)
// dr-x     - webdav
// -r--        - index.php
// drwx        - davfiles
//                 (DAV FILES ARE IN HERE)
// drw-        - data
// -rw-           - locks
// dr-x        - Sabre
//
$rootDirectory = new Sabre_DAV_FS_Directory('davfiles');
$server = new Sabre_DAV_Server($rootDirectory);
$server->setBaseUri('/webdav/');
// The lock manager is reponsible for making sure users don't overwrite each others changes.
// Change 'data' to a different directory, if you're storing your data somewhere else.
$lockBackend = new Sabre_DAV_Locks_Backend_File('data/locks');
$lockPlugin = new Sabre_DAV_Locks_Plugin($lockBackend);
$server->addPlugin($lockPlugin);
$authBackend = new Sabre_DAV_Auth_Backend_Basic_DrupalConnected();
$authPlugin = new Sabre_DAV_Auth_Plugin($authBackend,'WebDAV area');
$server->addPlugin($authPlugin);
$server->exec(); // All we need to do now, is to fire up the server

This Article is also available in Deutsch.

Gitosis Installation Script For Ubuntu 10.04

stfwi — Mon, 01 Aug 2011 19:28:02 +0000

If you like programming, you might like version control as well, means you might like GIT and your own repository server at home to “sync” with your friends and fellows. That’s what I wanted as well for my Ubuntu (10.4) system, and I have to admit: Setting up gitosis can take some time, and there are some nice “pitfallish” details on the path as well, so I condensed the various tutorials in the web into a shell script, which installs gitosis, gitweb, git-daemon and optionally viewgit. The mainly used howtos are straight from the ubuntu docs (http://help.ubuntu.com/community/Git). I hope is saves you some time.

Sequence:

Download and extract the ZIP archive in your server home directory or /tmp/”,
Log into your server using SSH
Run in the shell ./gitosis-setup/setup install
Optionally before ./gitosis-setup/setup --help
Follow the instructions. You need this only if you don’t have a SSH key file, e.g. ~/.ssh/id_rsa, otherwise the script will run without asking questions

What happens then?

The script checks if the actual user has a ~/.ssh/id_rsa key file, which is required for gitosis. If not it generates one for you usind ssh-keygen (encryption 4096 bits). You will have to enter a passphrase for this keyfile.
The script installs git gitosis apache2 libapache2-mod-php5 php-geshi gitweb using aptitude
The gitosis setup generates a user “gitosis”. The script renames this user to “git”
The script initializes gitosis with your key file
The script adds the git-daemon to the services and adds an allow rule for the git port in the firewall (ufw) configuration.

Result

Your gitosis data are in /srv/gitosis.
You have a new user “git” on your machine, this user cannot login to the shell, cannot login via password and is strictly bound to the gitosis system (see /srv/gitosis/.ssh/authorized_keys, there is for each registered user the command that is executed when someone connects via SSH).
If you did not have it yet, you have now a running apache2 server with the document root /var/www/. You can access gitweb using http[s]://yourserver.whatever/gitweb, at least at http://localhost/gitweb. Note: The script does not change your document root if already existing. Gitweb is a perl construction that is added to the apache2 using a location alias.
The account you installed gitosis with is not the “admin” account of gitosis.

Now you configure gitosis with your server account, add projects and users:

cd ~/
git clone git@localhost:gitosis-admin.git
cd ~/gitosis-admin
nano gitosis.conf
cp ~/a-friends-public-key-file.pub ~/gitosis-admin/keydir/
etc.
etc.

Source code

#!/bin/bash

# locals
APTITUDE='/usr/bin/aptitude'
APTITUDE_INSTALL="$APTITUDE -q -y install"
TEMP_DIR='/tmp/setup-gitsvr'
GITHOST=localhost
ID_RSA_NAME="id_rsa"
LINE_INDENT=""
WWW_ROOT="/var/www"
APACHE_USER="www-data"
APACHE_GROUP="www-data"

# functions
function echo_error() { echo -e "\033[0;31m[FAILED] $@\033[0m"; }
function echo_ok()    { echo -e "\033[0;32m[OK] $@\033[0m"; }
function echo_info()  { echo -e "\033[0;33m$@\033[0m"; }

function echo_usage() {
	echo "Usage:"
	echo ""
	echo " To install gitosis with doxygen and gitweb:"
	echo "   $(basename $0) install"
	echo "   This will install git, gitosis. It will configure your server, so that:"
	echo ""
	echo "     - The repository is in /srv/gitosis (made by aptitude)."
	echo "     - The git user is 'git' (renamed from 'gitosis')."
	echo "     - The account you run it from is the gitosis admin (use 'sudo setup install'"
	echo "       and do not 'sudo su; setup install'."
	echo "       - If this account does not yet have an 'id_rsa' key file in ~/.ssh, we will"
	echo "         generate one during the setup process."
	echo ""
	echo "   After the setup you can directly edit the gitosis config using:"
	echo ""
	echo "       $ cd ~/ "
	echo -e "       $ \033[0;31mgit clone git@localhost:gitosis-admin.git\033[0m"
	echo "       $ cd gitosis-admin"
	echo "       $ [vim/nano] gitosis.conf"
	echo "       $ cp .pub ~/gitosis-admin/keydir/.pub"
	echo -e "       $ \033[0;31mgit commit -am 'Added , did something in the config'"
	echo -e "       $ \033[0;31mgit push origin master\033[0m"
	echo ""
	echo ""
	echo ""
	echo " To uninstall gitosis and gitweb:"
	echo "   $(basename $0) uninstall --really"
	echo "   This will remove gitosis and gitweb. Other the other packages have to be removed"
	echo "   manually using aptutude remove."
	echo ""
	echo " To install gitweb:"
	echo "   $(basename $0) install-gitweb"
	echo ""
	echo " To uninstall gitweb"
	echo "   $(basename $0) uninstall-gitweb"
	echo ""
	echo " To install viewgit:"
	echo "   $(basename $0) install-viewgit"
	echo ""
	echo " To uninstall viewgit:"
	echo "   $(basename $0) uninstall-viewgit"
	echo ""
	exit
}

# uninstall process
if [ "$1" = "uninstall" ]; then
	if [ "$2" != "--really" ]; then
		echo_error 'You must say "setup uninstall --really"'
		echo ""
		echo_usage
	fi
	sudo echo ""
	echo_info "----------------------------------------------------------------------"
	echo_info "UNINSTALL"
	echo_info "----------------------------------------------------------------------"

	echo_info "remove git-demon ..."
	if [ -f /etc/init.d/git-daemon ]; then
	echo_info "Stopping service git-daemon"
	sudo service git-daemon stop
	echo_info "Removing git port (9418) from firewall rules (ufw)"
	sudo ufw delete allow in 9418/tcp
	echo_info "Removing /etc/init.d/git-daemon"
	sudo update-rc.d -f git-daemon remove
	sudo rm /etc/init.d/git-daemon
	fi

	echo_info "remove gitosis ..."
	sudo $APTITUDE -q -y remove gitosis gitweb
	echo_info "purge gitosis ..."
	sudo $APTITUDE -q -y purge gitosis gitweb
	echo_info "remove repository ..."
	sudo rm -rf /srv/gitosis &> /dev/null
	echo_info "Ensure user/group gitosis is gone ..."
	sudo groupdel git &> /dev/null
	sudo userdel git &> /dev/null
	echo_ok "uninstalled"
	exit
elif [ "$1" = "install" ]; then
	# mark sudo
	sudo echo ""

	# initial checks
	if [ -d /srv/gitosis ]; then
		echo_error "gitosis already setup (in /srv/gitosis/)."
		exit;
	fi

	if [ `dirname $TEMP_DIR` != "/tmp" ]; then
		echo_error "temp dir is not a subdir of /tmp/"
		exit;
	fi

	if [ ! -f ~/.ssh/$ID_RSA_NAME ]; then
		echo_info "----------------------------------------------------------------------"
		echo_info "You don't have a personal user key file yet, we generate one now ..."

		if [ ! -d ~/.ssh ]; then
			mkdir ~/.ssh
			chmod 700 ~/.ssh
			echo_info "Created ~/.ssh with 700"
		fi

		echo_info "Keygen - now enter a passphrase for your private id key file ..."
		ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa
		chmod 600 ~/.ssh/id_rsa
		echo_info "~/.ssh/id_rsa set to mod 600"
		echo_info "Now we register you at the local machine for ssh keyfile login"
		echo_info "    (ssh-copy-id $USER@$GITHOST), you may need to enter your normal login password"
		echo_info '    +++ IF IT SAYS NOW "The authenticity of host ... cant be established", JUST SAY "yes" +++'
		echo ""
		ssh-copy-id $USER@$GITHOST
		echo_info "OK, let's go on with the normal gitosis installation ..."
		echo_info "----------------------------------------------------------------------"
	fi

	if [ ! -f ~/.ssh/$ID_RSA_NAME.pub ]; then
		echo_error "Public key file not there"
		exit
	fi

	# aptitude
	echo_info "Installing with aptitude: git gitosis"
	sudo $APTITUDE_INSTALL git gitosis

	# Change user to "git" as clone "git@myhost" is shorter and seems reasonable
	sudo killall -u gitosis
	sudo id gitosis
	sudo usermod -l git gitosis
	sudo groupmod -n git gitosis
	sudo id git
	sudo chown -R git:git /srv/gitosis

	# initialize gitosis
	echo_info "Initializing git (/srv/gitosis)"
	sudo -H -u git gitosis-init < ~/.ssh/$ID_RSA_NAME.pub

	# setup git daemon
	if [ ! -f /etc/init.d/git-daemon ]; then
		echo_info "Copying git-daemon to /etc/init.d/git-daemon"
		sudo cp "$(dirname $0)/git-daemon" /etc/init.d/
		sudo chmod +x /etc/init.d/git-daemon
		sudo update-rc.d git-daemon defaults
		echo_info "Allowing git port (9418) in firewall (ufw)"
		sudo ufw allow in 9418/tcp
		echo_info "Starting service git-daemon"
		sudo service git-daemon start
	fi

	echo ""
	echo_info "----------------------------------------------------------------------"
	echo_info "Now you can clone the gitosis config using: "
	echo_ok "    $ git clone git@$GITHOST:gitosis-admin.git"

elif [ "$1" = "install-gitweb" ]; then
	# mark sudo
	sudo echo ""
	echo_info "Installing with aptitude: apache2 libapache2-mod-php5 php-geshi"
	sudo $APTITUDE_INSTALL apache2 libapache2-mod-php5 php-geshi gitweb
	sudo adduser $APACHE_USER git

elif [ "$1" = "uninstall-gitweb" ]; then

	sudo $APTITUDE remove php-geshi gitweb

elif [ "$1" = "install-viewgit" ]; then

	sudo echo ""
	if [ ! -d $WWW_ROOT ]; then
		echo_error "Web root directory not there ($WWW_ROOT)"
		exit
	fi
	if [ -d $WWW_ROOT/viewgit ]; then
		echo_error "Already installed in ($WWW_ROOT/viewgit)"
		exit
	fi

	pushd &> /dev/null
	cd $WWW_ROOT
	echo_info "Getting web interface, will be then in $WWW_ROOT/viewgit"
	sudo git clone git://repo.or.cz/viewgit.git
	echo_info "Changing viewgit's user/group to $APACHE_USER:$APACHE_GROUP"
	sudo chown -R $APACHE_USER:$APACHE_GROUP viewgit
	echo_info "Preparing config file ($WWW_ROOT/viewgit/inc/localconfig.php)"
	cd $WWW_ROOT/viewgit/inc
	sudo cp config.php localconfig.php
	sudo chown $APACHE_USER:$APACHE_GROUP localconfig.php
	popd &> /dev/null
	echo_info "Adding apache user to gitosis group"
	sudo adduser $APACHE_USER git
	echo_ok "You can now edit the config file $WWW_ROOT/viewgit/inc/localconfig.php"

elif [ "$1" = "uninstall-viewgit" ]; then

	sudo echo ""
	if [ ! -d $WWW_ROOT/viewgit ]; then
		echo_error "Not yet installed in ($WWW_ROOT/viewgit)"
		exit
	fi
	pushd &> /dev/null
	sudo rm -rf $WWW_ROOT/viewgit &>/dev/null
	sudo adduser $APACHE_USER git
	popd &> /dev/null

else
	echo ""
	echo_usage
	exit
fi

Daemon script

This script is one to one the daemon on the Ubuntu gitosis manual page.

# Taken from here: http://pastie.org/227647

PATH=/usr/local/sbin:/usr/local/bin:/sbin:/bin:/usr/sbin:/usr/bin
NAME=git-daemon
PIDFILE=/var/run/$NAME.pid
DESC="the git daemon"
DAEMON=/usr/lib/git-core/git-daemon
DAEMON_OPTS="--base-path=/srv/gitosis/repositories --export-all --verbose --syslog --detach --pid-file=$PIDFILE --user=gitosis --group=nogroup"

test -x $DAEMON || exit 0

[ -r /etc/default/git-daemon ] && . /etc/default/git-daemon

. /lib/lsb/init-functions

start_git() {
  start-stop-daemon --start --quiet --pidfile $PIDFILE \
    --startas $DAEMON -- $DAEMON_OPTS
}

stop_git() {
  start-stop-daemon --stop --quiet --pidfile $PIDFILE
  rm -f $PIDFILE
}

status_git() {
  start-stop-daemon --stop --test --quiet --pidfile $PIDFILE >/dev/null 2>&1
}

case "$1" in
  start)
  log_begin_msg "Starting $DESC"
  start_git
  log_end_msg 0
  ;;
  stop)
  log_begin_msg "Stopping $DESC"
  stop_git
  log_end_msg 0
  ;;
  status)
  log_begin_msg "Testing $DESC: "
  if status_git
  then
    log_success_msg "Running"
    exit 0
  else
    log_failure_msg "Not running"
    exit 1
  fi
  ;;
  restart|force-reload)
  log_begin_msg "Restarting $DESC"
  stop_git
  sleep 1
  start_git
  log_end_msg 0
  ;;
  *)
  echo "Usage: $0 {start|stop|restart|force-reload|status}" >&2
  exit 1
  ;;
esac

exit 0

This Article is also available in Deutsch.

RSS 2.0 rendering class

stfwi — Sat, 04 Sep 2010 19:53:05 +0000

It can be so simple to generate RSS 2.0 feeds in PHP. The Rss2Feed class allows to render one or more channels in one RSS feed. All you have to do is to “feed” it with you data by overloading the onLoad() method. The results can be saved in a .rss file or directly sent to the Browser. The example show how:

Sample source code

 sys_get_temp_dir(),
));

// Our class to customize the feed channel
class MyRss2Feed extends Rss2Feed {

    // That's the method we have to overload:
    protected function onLoad($identifier='', $numOfItems='') {
        // Instead of loading items from a database, we generate
        // a static array for this example:
        return array(
            'title' => 'CHANNEL TITLE',
            'description' => 'Channel description',
            'link' => '', // will be replaced with your $_SERVER[HTTP_HOST]
            'items' => array(
                array(
                    'title' => 'Item 1 title',
                    'description' => 'Item 1 description',
                    'link' => 'http://item1.link/',
                ),
                array(
                    'title' => 'Item 2 title &', // this will be escaped ("&")
                    'description' => 'Item 2 description',
                    'link' => 'http://item2.link/',
                ),
                array(
                    'title' => 'Item 2 title with an "ü"',
                    'description' => '', // No content
                    'link' => '', // link will be replaced
                ),
            )
        );
    }
}

// Generate the feed with 100 items, only the default channel
try {
    $rss = new MyRss2Feed();
    $xml = $rss->renderFeed(array(), 100);
} catch(Exception $e) {
    $exception = $e;
}

// Script output
if(!isset($exception) && isset($_GET['rss'])) {
    // View the RSS in a reader
    OutputBuffer::purge();
    Tracer::disable();
    print $xml;
} else {
    // View the RSS XML code in the browser
    print '';
    print htmlspecialchars($xml);
    print '';
}
?>

Output



 
  CHANNEL TITLE
  http://wp.localhost/
  
  swlib
  60
  
   Item 1 title
   Item 1 description
   http://item1.link/
  
  
   <![CDATA[Item 2 title &]]>
   Item 2 description
   http://item2.link/
  
  
   <![CDATA[Item 2 title ü]]>
   
   http://wp.localhost/

Class source code

 '',              // Main title if the feed, should contain the website url
        'link' => '',               // Link to the main web page of the channel
        'description' => '',        // Text description of the feed
        'category' => '',           // One or more category names
        'language' => '',           // Channel language
        'copyright' => '',          // Copyright information
        'generator' => 'swlib',     // Feed generator
        'managingeditor' => '',     // Email address of he managing editor
        'webMaster' => '',          // Email address of the admin
        'pubDate' => '',            // RFC822 time when the content was published
        'lastbuilddate' => '',      // RFC822 time when the channel was modified
        'docs' => '',               // RSS specification documentation link
        'cloud' => '',              // Cloud service interface provider
        'ttl' => '60',              // Time to live
        'image' => array(           // Channel image:
            'url' => '',            // Url to GIF, JPEG or PNG
            'title' => '',          // Like alt tag in HTML
            'link' => '',           // Page link (use link of the channel itself)
            'width' => '',          // Optional width, mad 144
            'height' => '',         // Optional height, mad 400
            'description' => '',    // Optional like HTML title=""
        ),
        'rating' => '',             //
        'textinput' => array(       // Input text box:
            'title' => '',          // The label of the Submit button in the text input area.
            'description' => '',    // Explains the text input area
            'name' => '',           // The name of the text object in the text input area
            'link' => ''            // The URL of the CGI script that processes text input requests
        ),
        'skiphours' => '',          // Hours to skip update: int 0 to 23
        'skipdays' => '',           // Days to skip update: Monday, Tuesday, Wednesday, ...
        'items' => array(),         // THESE ARE THE ITEMS OF THE CHANNEL
    );

    /**
     * That's how the item specfication looks like:
     * @staticvar array
     */
    private static $itemTemplate = array(
        'title' => '',              // Title of the Item
        'link' => '',               // Link to the related HTML page
        'description' => '',        // Text description
        'author' => '',             // Author of the item
        'category' => '',           // Item category
        'comments' => '',           // URI to item comments
        'source' => '',             // RSS channel where the content of this item is taken from
        'enclosure' => array(       // Attached media data (array contents are XML attributes)
            'url' => '',            // Link to the resource
            'type' => '',           // MIME type
            'length' => ''          // Content length in bytes
        ),
        'guid' => '',               // Global unique identifier
        'pubDate' => '',            // RFC822 time when the item was published
    );

    /**
     * The text encoding of the feed
     * @var string
     */
    private $encoding = "UTF-8";

    /**
     * The channel data retrieved from the database or other sources
     * @var array
     */
    private $data = array();    

    /**
     * Items, extracted form the data array returned by onLoad.
     * @var array
     */
    public $items = array();

    /**
     * Loads the data which are necessary to render an RSS feed.
     * OVERLOAD THIS FUNCTION TO CUSTOMIZE YOUR RSS CHANNELS.
     * Returns a reference to the result array, which must contain the
     * keys "title", "description" and "item"
     *
     * @param mixed $identifier
     * @param int $numOfItems
     * @return array
     */
    protected function onLoad($identifier='', $numOfItems=0) {
        return array();
    }

    /**
     * XML text escaping
     * @param string $text
     * @return string
     */
    private static function xmlEscape($text) {
        if(empty($text) || trim($text) == '') { // !empty for array()/null
            return '';
        } else if(!preg_match('/([^\x01-\x7f]|[&<>])/', $text)) {
            return $text;
        } if(strpos($text, ']]>') === false) {
            return "";
        } else {
            return str_replace(array('&','"',"'",'<','>'), array('&','"',''','<','>'), $text);
        }
    }

    /**
     * Constructor
     * @param string $encoding
     */
    public function __construct($encoding="UTF-8") {
        $this->encoding = $encoding;
    }

    /**
     * Data access get
     * @param string $name
     * @return mixed
     */
    public function & __get($name) {
        $name = strtolower($name);
        return isset($this->data[$name]) ? $this->data[$name] : '';
    }

    /**
     * Data access set
     * @param string $name
     * @param mixed $value
     */
    public function __set($name,  $value) {
        $name = strtolower($name);
        if(!isset($this->data[$name])) {
            throw new Exception('No such RSS property to set');
        } else {
            $this->data[$name] = $value;
        }
    }

    /**
     * Loads the data using the overloadable onLoad() method.
     * @param mixed $identifier
     * @param int $numOfItems
     */
    public function load($identifier='', $numOfItems=0) {
        $this->items = null;
        $this->data = array_change_key_case(array_merge(self::$dataTemplate, $this->onLoad($identifier, $numOfItems)), CASE_LOWER);
        $this->items = &$this->data['items'];
        unset($this->data['items']);

        if($this->title == '') {
            throw new Exception('RSS channel title must be specified');
        }

        if(empty($this->link)) {
            $this->link = "http://{$_SERVER['HTTP_HOST']}/";
        }

        foreach($this->items as $key => $item) {
            $this->items[$key] = array_change_key_case($item, CASE_LOWER);
            if(empty($item['title'])) {
                Tracer::trace("RSS item $key removed, no title");
                $this->items[$key] = false;
            } else if(empty($item['link'])) {
                Tracer::trace("RSS item $key ({$item['title']}) added channel link");
                $this->items[$key]['link'] = $this->link;
            }
        }

        if(count($this->items) == 0) {
            throw new Exception('No RSS channel items defined');
        }
    }

    /**
     * Renders the channel
     * @return string
     */
    public function renderChannel($numOfItems=0) {
        $o = " \n";

        foreach($this->data as $tag => $value) {
            if(!empty($value) || $tag == 'title' || $tag == 'description' || $tag == 'link') {
                if(!is_array($value)) {
                    $o .= "  <$tag>" . self::xmlEscape($value) . "\n";
                } else if(strlen(trim(implode('', $value), " \n\r\t")) > 0) {
                    $o .= " <$tag>";
                    foreach($value as $itag => $ivalue) {
                        $o .= "   <$itag>" . self::xmlEscape($ivalue) . "\n";
                    }
                    $o .= " ";
                }
            }
        }

        $count = 0;
        foreach($this->items as $item) {
            if($numOfItems > 0 && ++$count > $numOfItems) {
                break;
            } else {
                $o .= "  \n";
                foreach($item as $tag => $value) {
                    if(!is_array($value)) {
                        $o .= "   <$tag>" . self::xmlEscape($value) . "\n";
                    } else if(strlen(trim(implode('', $value), " \n\r\t")) > 0) {
                        if($tag == 'enclosure') {
                            $o .= "";
                        } else if(!empty($value) || $tag == 'title' || $tag == 'description' || $tag == 'link') {
                            $o .= "  <$tag>";
                            foreach($value as $itag => $ivalue) {
                                $o .= "    <$itag>" . self::xmlEscape($ivalue) . "\n";
                            }
                            $o .= "  \n";
                        }
                    }
                }
                $o .= "  \n";
            }
        }
        $o .= " \n";
        return $o;
    }

    /**
     * Renders a list of channels in one feed
     * @param array $channelIdentifiers
     * @param int $numOfItems
     * @return string
     */
    public function renderFeed(array $channelIdentifiers=array(), $numOfItems=0) {
        $o =  'encoding . '" ?>'
            . "\n" . '\n";
        foreach($channelIdentifiers as $identifier) {
            try {
                $this->load($identifier, $numOfItems);
                $o .= $this->renderChannel($numOfItems);
            } catch(Exception $e) {
                Tracer::traceException($e);
            }
        }
        $o .= '';
        return $o;
    }
}
?>

This Article is also available in Deutsch.

User verification image class

stfwi — Wed, 01 Sep 2010 17:37:34 +0000

To prevent bots form submitting online-forms, it is a commonly used technique to verify “human user” with a code that has to be entered by reading letters and numbers in a noisy image. This class is a simple way to do this:

Sample source code

 sys_get_temp_dir(),
));

// This is the entry key we use for the $_SESSION for this sample code
$sessionKey = 'swlib-verification-image';

if(isset($_GET['img'])) {
    //
    // This section sends the imgage (we use the same script for sending HTML
    // and the binary image.
    //
    Tracer::disable();
    OutputBuffer::purge();

    // Check referrer and valid session
    if(isset($_SERVER['HTTP_REFERER']) && strpos(strtolower($_SERVER['HTTP_REFERER']),
            strtolower($_SERVER['HTTP_HOST'])) !== false
            && isset($_SESSION[$sessionKey])
            && is_array($_SESSION[$sessionKey])
            && isset($_SESSION[$sessionKey]['text'])
            && strlen(trim($_SESSION[$sessionKey]['text'])) > 0
    ){
        // Retrieve the data saved in the session and set the corresponding
        // instance properties
        $cfg = &$_SESSION[$sessionKey];
        $vi = new UserVerificationImage(trim($cfg['text']));
        if(isset($cfg['width'])) try { $vi->setWidth($cfg['width']); } catch(Exception $e) { ; }
        if(isset($cfg['height'])) try { $vi->setHeight($cfg['height']); } catch(Exception $e) { ; }
        if(isset($cfg['noise'])) try { $vi->setNoise($cfg['noise']); } catch(Exception $e) { ; }

        // Finally send the image as binay code to the browser and exit.
        $vi->sendImage();
    }

    /*
     *
     * Alternatively, you can use the static function to create an image
     * and save the corresponding SHA1 hash code in a cookie:
     *
     *      UserVerificationImage::sendValidationImageAndExit();
     *
     *  This method is much easier to use, but less configurable.
     *
     */

    // exit if the $vi->sendImage() method did not do this yet.
    exit();
}

////////////////////////////////////////////////////////////////////////////////
// This section is the normal HTML script:
//

// Create the instance
$vi = new UserVerificationImage();

// Check if the user has entered the code
if(isset($_GET['input'])) {

    try {
        // Verify the code saved in the session with the entered code.
        $vi->setText($_SESSION[$sessionKey]['text']);
        if($vi->verifyInput($_GET['input'])) {
            $inputCorrect = "Input is correct";
        } else {
            $inputCorrect = "Input is not correct";
        }
    } catch(Exception $e) {
        $inputCorrect = "Exception:" . $e->getMessage();
    }

    /*
     * Alternatively:
     *
     *  if(UserVerificationImage::verifyValidationImage($_GET['input'])) {
     *      $inputCorrect = "Input is correct";
     *  } else {
     *      $inputCorrect = "Input is not correct";
     *  }
     *
     * Use this static function to verify images sent using the function
     * UserVerificationImage::sendValidationImageAndExit();
     */
}

// Set a new random code with 8 characters from the character list
$vi->setRandomText(8, 'ABCDEFGHIJ0123456789klmnopqr?-');

// Write the session for the image lookup
$_SESSION[$sessionKey] = array('text' => $vi->getText());

// And print it all ...
$text = $vi->getText();

print <<
    
        
            Original text $text
            Image 
            Enter here 
            
                
                
            
            
            Last value was ok: $inputCorrect
        
    
HERE;
?>

Output

The output will be a simple table, which contains the plain text code, the image (showing the same code), a form where you can enter the code and a row, which shows if the entered code was correct.

Class source code

setWidth($_SESSION[$k]['width']);
                if(isset($_SESSION[$k]['height'])) $vi->setHeight($_SESSION[$k]['height']);
                if(isset($_SESSION[$k]['noise'])) $vi->setNoise($_SESSION[$k]['noise']);
                $vi->setRandomText($textLength);
                setcookie("swlibvimage", sha1(strtoupper($vi->getText())), time() + 30);
                $vi->sendImage();
                $key = strtolower(__CLASS__);
                if($saveInSession) {
                    $_SESSION[$key] = $vi->getText();
                } else if(isset($_SESSION[$key])) {
                    unset($_SESSION[$key]);
                }
            } catch(Exception $e) {
                // Send error image?
            }
        }
        exit();
    }

    /**
     * Hard-validates the text of a validation image that the user has entered.
     * There is no tolerance according to O<-->0 etc. The function uses cookies.
     * @param string $input
     * @return book
     */
    public static function verifyValidationImage($input) {
        if(!isset($_COOKIE['swlibvimage']) || empty($_COOKIE['swlibvimage'])) {
            Tracer::trace("No cookie set (swlibvimage)");
            return false;
        } else if($_COOKIE['swlibvimage'] == sha1(strtoupper(trim($input)))) {
            Tracer::trace("Cookie validation OK (swlibvimage)");
            return true;
        } else {
            $key = strtolower(__CLASS__);
            if(isset($_SESSION[$key])) {
                $vi = new self();
                $vi->setText($_SESSION[$key]);
                unset($_SESSION[$key]);
                return $vi->verifyInput($input);
                Tracer::trace("Session saved vcode is: $text");
            } else {
                Tracer::trace("No alternative session key saved ($key)");
            }
        }
        return false;
    }

    /**
     * Constructor
     * @param string $text
     */
    public function __construct($text='') {
        if(!empty($text)) $this->setText(trim($text));
    }

    /**
     * Returns the image width
     * @return int
     */
    public function getWidth() {
        return $this->width;
    }

    /**
     * Sets the image width
     * @param int $width
     */
    public function setWidth($width) {
        if(!is_numeric($width)) {
            throw new Exception("Invalid image width: '$width'" );
        } else {
            $width = intval($width);
            if($width < 10 || $width > 500) $width = 0;
            $this->width = $width;
        }
    }

    /**
     * Returns the image height
     * @return int
     */
    public function getHeight() {
        return $this->height;
    }

    /**
     * Sets the image height
     * @param int $height
     */
    public function setHeight($height) {
        if(!is_numeric($height)) {
            throw new Exception("Invalid image height: '$height'" );
        } else if(intval($height) < 20) {
            throw new Exception("Invalid image height: '$height' (min width is 20)" );
        } else {
            $this->height = intval($height);
        }
    }

    /**
     * Returns the image text
     * @return string
     */
    public function getText() {
        if(empty($this->text)) {
            $this->setRandomText();
        }
        return $this->text;
    }

    /**
     * Sets the text to display
     * @param string $text
     */
    public function setText($text) {
        if(!is_scalar($text)) {
            throw new Exception("Invalid image text (must be a scalar value)");
        } else if(empty($text) || strlen(trim($text)) == 0) {
            $this->text = '';
        } else {
            $this->text = strval($text);
        }
    }

    /**
     * Returns the noise factor
     * @return double
     */
    public function getNoise() {
        return $this->noise;
    }

    /**
     * Sets the noise factor
     * @param double $noise
     */
    public function setNoise($noise) {
        if(!is_numeric($noise)) {
            throw new Exception('Invalid image noise (not numeric)');
        } else if($noise > 1 || $noise < 0) {
            throw new Exception('Invalid image noise (must be between 0 and 1)');
        } else {
            $this->noise = $noise;
        }
    }

    /**
     * Sets a random text
     * @param int $size
     * @param string charset
     */
    public function setRandomText($size=8, $charset='abcdefghkmnpqrtwxyzABCDEFGHIJKLMNPRTUVWXYZ2346789') {
        $charset = preg_replace('/[\s]/', '', $charset);
        if(!is_numeric($size)) {
            throw new Exception('Invalid random text size ("' . $size . '")');
        } else if(empty($charset)) {
            throw new Exception('Invalid character set for random text (empty string)');
        } else {
            $l = strlen($charset)-1;
            $o = '';
            while(strlen($o) < $size) {
                $o .= substr($charset, rand(0, $l), 1);
            }
            $this->text = $o;
            return $o;
        }
    }

    /**
     * Generates the png image, returns the local file path
     * @return string
     */
    public function generateImage() {
        $yPositionRange = 2;
        $fontSize = $this->getHeight() - (2 * $yPositionRange);
        $charWidth = imagefontwidth($fontSize) + 3;
        $charHeight = imagefontheight($fontSize);
        $textWidth = $charWidth * strlen($this->getText());
        if($this->getWidth() == 0) $this->width = $textWidth + (2 * $yPositionRange);
        $this->width = 10 * ceil($this->width / 10);
        $noisePixels = $this->getWidth() * $this->getHeight() * $this->getNoise();
        $x0 = ceil(($this->getWidth() - $textWidth) / 2);
        $y0 = ceil(($this->getHeight() - $charHeight) / 2);

        $img = imagecreatetruecolor($this->getWidth(), $this->getHeight());
        imagefill($img, 0, 0, 0xffffff);

        // Noise
        $w = $this->getWidth()-1;
        $h = $this->getHeight()-1;
        for($i=0; $i<$noisePixels; $i++) {
            $c = 0x000000;
            imagesetpixel($img, rand(0, $w), rand(0, $h), $c);
        }

        $text = $this->getText();
        for($i=0; $igenerateImage();
        if(!empty($file)) {
            header('Content-type: image/png');
            header('Content-Length: ' . FileSystem::getFileSize($file));
            header('Cache-Control:no-store, no-cache, must-revalidate, post-check=0, pre-check=0');
            header('Pragma:no-cache');
            header('Connection:Close');
            Tracer::disable();
            OutputBuffer::purge();
            try { print FileSystem::readFile($file); } catch(Exception $e) { ; }
            try { FileSystem::delete($file);  } catch(Exception $e) { ; }
        }
    }

    /**
     * Checks the input against the $text instance variable. One spelling
     * error is accepted for characters like O<-->0 and S<-->5.
     * @param string $input
     * @return bool
     */
    public function verifyInput($input) {
        $input = strtoupper(trim($input, " \n\r\t"));
        $text  = strtoupper(trim($this->getText(), " \n\r\t"));
        if(empty($input)) {
            Tracer::trace('Verification failed: No input');
            return false;
        } else if(strlen($input) != strlen($text)) {
            Tracer::trace('Verification failed: Text lengths differ');
            return false;
        } else if($input == $text) {
            Tracer::trace('Verification OK: Texts are equal');
            return true;
        } else if(levenshtein($input, $text) > 1) {
            Tracer::trace('Verification failed: More than one character difference');
            return false;
        } else {
            $t1 = $text;
            $t2 = $input;
            $t1 = str_replace(array('0','Q','5'), array('O','O','S'), $t1);
            $t2 = str_replace(array('0','Q','5'), array('O','O','S'), $t2);
            if($t1 == $t2) {
                Tracer::trace('Verification OK, after compensation of optical redundant characters');
                return true;
            } else {
                Tracer::trace('Verification failed: Even after correction of optical redundant characters');
                return false;
            }
        }
        return false;
    }

}
?>

This Article is also available in Deutsch.

Version checking and publishing class

stfwi — Tue, 24 Aug 2010 09:37:05 +0000

Version checks and auto-updates become more and more important for PHP applications and CMS. The class presented in this article contains methods and static functions to parse and structure (Java-Style) documentation comments of class- and interface definitions. Furthermore, MD5 and SHA1 checksums are built for all files, as well as the (comment/whitespace) stripped source codes. This allows to determine if an update is really necessary or if only changes in comments were made.
These features are used in two static main functions: Versioning::publishModule() and Versioning::checkModuleVersion(). Versioning::publishModule() compresses a package/module/library (located in a specified folder) to a ZIP archive located in a publishing path. With this download-archive, other information files are saved in the target directory, such as checksums, the version file, the readme and license info file. E.g. the “repository” folder of the SwLibrary (URI http://www.atwillys.de/repository/swlib/) contains the following files:

swlib.zip: Package contents (download file)
swlib.zip.md5: MD5 checksum of the ZIP file
swlib.zip.sha1: SHA1 checksum of the ZIP file
swlib.checksum: Checksums of all recognized source codes in the package
swlib.version: Copy of the file “version”
swlib.license: Copy of the file “license”
swlib.readme: Copy of the file “readme”
swlib.content: Details the package contents in JSON format

Other packages have other file names, respectively. These information are used by the function Versioning::checkModuleVersion(), which performs a remote (HTTP) lookup in a published repository to check for updates. First the package checksum is checked and compared with the checksum of the local package. If the checksum is different, then other files, such as the version file and the contents-JSON, are checked to determine if an update is “urgently” necessary or if only changes in documentation or white-spaces are made.

Sample source code

 sys_get_temp_dir(),
        'tmp_path' => sys_get_temp_dir(),
    ));
}

print '';

// Instantiate the object
$ver = new Versioning();

// Get all files in library path of the SwLibrary (we use the swlib as example,
// there are plenty of classes in this path :)
$files = FileSystem::find(swlib::getLibPath());
// ... But we use only the first three files - it's the same for all other files
$files = array($files[0], $files[1], $files[2]);

// Scan all the files that you can scan
$ver->readFiles($files, swlib::getLibPath());

// Print the results we obtained:
print 'Classes = ' . print_r($ver->getClasses(), true) . "\n";
print 'SHA1 checksums = ' . print_r($ver->getFileSha1s(), true) . "\n";
print 'MD5 checksums = ' . print_r($ver->getFileMd5s(), true) . "\n";
print 'Stripped code checksums MD5) = ' . print_r($ver->getSourceCodeMd5s(), true) . "\n";
print 'File details = ' . print_r($ver->getFileDetails(), true) . "\n\n<\n>";

// Example for publishing a package:
Versioning::publishModule('swlib', swlib::getLibPath(), dirname(__FILE__) . '/swlib');

// Check a version of a package
print_r(Versioning::checkModuleVersion('swlib', swlib::getLibPath(), 'http://htx.my/htx/tmp'));

// This is the function provided in the swlib core class, which uses this class.
print_r(swlib::checkForUpdates());

print '';
?>

Output

Class source code

files;
    }

    /**
     * Returns the classes that were found in the searched files
     * @return array
     */
    public final function getClasses() {
        return $this->versions;
    }

    /**
     * Returns the SHA1 checksum of all scanned code files (*.php).
     * @return string
     */
    public final function getChecksum() {
        return $this->checksum;
    }

    /**
     * Returns the file-MD5 checksums of the scanned files as associative array,
     * where the keys are the file paths/sub-paths and the values the checksums.
     * @return array.
     */
    public final function getFileMd5s() {
        $cs = array();
        foreach($this->files as $file => $desc) {
            $cs[$file] = $desc['file_md5'];
        }
        return $cs;
    }

    /**
     * Returns the file-SHA1 checksums of the scanned files as associative array,
     * where the keys are the file paths/sub-paths and the values the checksums.
     * @return array.
     */
    public final function getFileSha1s() {
        $cs = array();
        foreach($this->files as $file => $desc) {
            $cs[$file] = $desc['file_sha1'];
        }
        return $cs;
    }

    /**
     * Returns the MD5 checksums of the whitespace-strupped codes of the scanned
     * files as associative array, where the keys are the file paths/sub-paths
     * and the values the checksums.
     * @return array.
     */
    public final function getSourceCodeMd5s() {
        $cs = array();
        foreach($this->files as $file => $desc) {
            $cs[$file] = $desc['source_md5'];
        }
        return $cs;
    }

    /**
     * Returns the information about a selected class.
     * @return array
     */
    public final function getClass($class) {
        return isset($this->versions[$class]) ? $this->versions[$class] : array();
    }

    /**
     * Returns information about classes and interfaces in an assoc. array.
     * The class names (lower case) are saved in the array keys, the array
     * values are the information about the class:
     * array(
     *  'type' =>   Can be 'class' or 'interface'
     *  'name' =>   The name of the class or interface
     *   =>  Dynamic entries dependent on the @-comments (like @author or
     *              @final etc). These values are automatically extended from
     *              the class/interface definition line, e.g:
     *
     *                  final class B extends A implements I1, I2
     *
     *              would generate automatically without special comments:
     *
     *              array (
     *                  'type' => 'class'
     *                  'name' => 'B'
     *                  'final' => true
     *                  'extends' => 'A'
     *                  'implements' => array('i1'=>'I1', 'i2'=>'I2')
     *              )
     * )
     * @param string $source
     * @return array
     */
    public final function getPhpClassDocumentations($source) {
        // Conditionize
        $source = str_replace(array("\r", "\t"), array("\n", ' '), $source);
        while(strpos($source, "\n\n") !== false) {
            $source = str_replace("\n\n", "\n", $source);
        }

        // Parse the source
        $DOC_START = '/**';
        $DOC_END = '*/';
        $documented = array();
        $p0 = strpos($source, $DOC_START);
        while($p0 !== false) {
            $p1 = strpos($source, $DOC_END, $p0+1);
            if($p1 <= $p0) break; // on not found
            $doc = substr($source, $p0+strlen($DOC_START), $p1-$p0-strlen($DOC_START)-strlen($DOC_END));
            $doc = trim(preg_replace('/[\n\s]*\*([^\n]*)[\n]?/i', "$1\n", $doc), "\n ");
            $p2 = $p1 + strlen($DOC_END);
            while($p2 < strlen($source) && ctype_space(substr($source, $p2, 1))) $p2++;
            if($p2 >= strlen($source)) break; // on end of text
            $p3 = strpos($source, "\n", $p2+1);
            if($p3 <= $p2) break; // on not found
            $ref = trim(substr($source, $p2, $p3-$p2+1), "\n ");
            $documented[] = array(
                'for' => $ref,
                'doc' => $doc
            );
            $p0 = strpos($source, $DOC_START, $p1+1);
        }

        // Filter information
        $docs = array();

        foreach($documented as $key => $entry) {
            $exp = array('text' => '');

            // Parse the comment
            $doc = explode("\n", str_replace("\r", "\n", $entry['doc']));
            foreach($doc as $line) {
                $line = trim($line, "\t\n\r ");
                if(!empty($line)) {
                    if(strpos($line, '@') === 0) {
                        $line = explode(' ', $line, 2);
                        $docKey = trim(strtolower(reset($line)), '@ ');
                        $docValue = count($line) > 1 ? trim(end($line)) : '';
                        switch($docKey) {
                            case 'uses':
                                if(!isset($exp[$docKey])) {
                                    $exp[$docKey] = array();
                                }
                                $exp[$docKey][strtolower($docValue)] = $docValue;
                                break;
                            case 'see':
                            case 'todo':
                                if(!isset($exp[$docKey])) {
                                    $exp[$docKey] = array();
                                }
                                $exp[$docKey][] = $docValue;
                                break;
                            default:
                                $exp[$docKey] = $docValue;
                        }

                    } else {
                        $exp['text'] .= $line . "\n";
                    }
                }
            }
            $exp['text'] = trim($exp['text'], "\n\r\t ");

            // Parse the line
            $for = $entry['for'];
            if(strpos($for, '(') > 1) {
                $for = substr($for, 0, strpos($for, '('));
            }
            $check = preg_split('/[\W]+/i', trim(strtolower($for), " ;{"), -1, PREG_SPLIT_NO_EMPTY);
            $for = preg_split('/[\W]+/i', trim($for, " ;{"), -1, PREG_SPLIT_NO_EMPTY);

            if(in_array('interface', $check)) {
                $exp['type'] = 'interface';
                $exp['name'] = end($for); // overwrite @name if specified
            } else if(in_array('class', $check)) {
                $exp['type'] = 'class';
                while(!empty($for)) {
                    $desc = strtolower(array_shift($for));
                    switch($desc) {
                        case 'abstract':
                        case 'final':
                            $exp[strtolower($desc)] = true;
                            break;
                        case 'class';
                            $exp['name'] = array_shift($for); // overwrite @name if specified
                            break;
                        case 'extends':
                            $exp['extends'] = array_shift($for);
                            break;
                        case 'implements':
                            $exp['implements'] = array();
                            while(!empty($for)) {
                                $desc = trim(array_shift($for), ' ,');
                                $exp['implements'][strtolower($desc)] = $desc;
                            }
                            break;
                        default:
                            Tracer::trace("Unrecognized descriptor: $desc");
                    }
                }

            }

            // Add
            if(isset($exp['name'])) {
                $docs[strtolower($exp['name'])] = $exp;
            }
        }
        return $docs;
    }

    /**
     * Searches the files for documented classes and extracts information from
     * the documentation. Undocumented classes will be ignored as they cannot
     * be explicitly versioned. The method generates md5 and sha1 checksums for
     * all file contents, where the documentations are ignored (as they do not
     * influence the functionality.
     * @param array $files
     * @param string $rootDirectory
     */
    public final function readFiles(array $files, $rootDirectory='') {
        $rootDirectory = trim(rtrim($rootDirectory, ' /'));
        $rootDirectory = rtrim($rootDirectory != '' ? $rootDirectory : $_SERVER['DOCUMENT_ROOT'], ' /') . '/';

        $this->files = array();
        $this->versions =  array();
        $this->exceptions = array();
        $this->checksum = '';

        foreach($files as $file) {
            $this->files[str_replace($rootDirectory, '', $file)] = array();
            $f = &$this->files[str_replace($rootDirectory, '', $file)];

            if(FileSystem::isFile($file) && FileSystem::isReadable($file)) {
                $f['file_sha1'] = sha1_file($file);
                $f['file_md5'] = md5_file($file);
                $f['source_md5'] = md5(@php_strip_whitespace($file));
                $f['classes'] = array();
                $this->checksum .= basename($file) . $f['file_sha1'];
                try {
                    if(FileSystem::getExtension($file) == 'php') {
                        $f['classes'] = $this->getPhpClassDocumentations(FileSystem::readFile($file));
                        foreach($f['classes'] as $class => $desc) {
                            $this->versions[$class] = isset($desc['version']) ? $desc['version'] : '';
                        }
                    }
                } catch(Exception $e) {
                    $this->exceptions[$file] = $e->getMessage();
                }
            } else if(!FileSystem::isFile($file)) {
                $this->exceptions[$file] = 'File does not exist';
            } else {
                $this->exceptions[$file] = 'File is not readable';
            }
        }
        $this->checksum = sha1($this->checksum);
    }

    /**
     * Returns information about version, readme, license, main checksum, file
     * checksums, and file and class details.
     * @param string $sourceDirectory
     * @return array
     */
    public static final function readLocalModuleVersion($sourceDirectory) {
        $sourceDirectory = trim(rtrim($sourceDirectory, ' /'));
        if(!FileSystem::isDirectory($sourceDirectory)) {
            throw new Exception('Source directory read does not exist: ' . $sourceDirectory);
        } else {
            $ver = new self();
            $ver->readFiles(FileSystem::find($sourceDirectory), $sourceDirectory);
            $return = array(
                'version' => '0.0',
                'readme' => '',
                'license' => '',
                'checksum' => $ver->getChecksum(),
                'details' => $ver->getFileDetails()
            );

            if(FileSystem::isFile("$sourceDirectory/version")) {
                $return['version'] = trim(FileSystem::readFile("$sourceDirectory/version"), "\n\r\t ");
            } else if(FileSystem::isFile("$sourceDirectory/VERSION")) {
                $return['version'] = trim(FileSystem::readFile("$sourceDirectory/VERSION"), "\n\r\t ");
            }
            if(FileSystem::isFile("$sourceDirectory/readme")) {
                $return['readme'] = trim(FileSystem::readFile("$sourceDirectory/readme"), "\n\r");
            } else if(FileSystem::isFile("$sourceDirectory/README")) {
                $return['readme'] = trim(FileSystem::readFile("$sourceDirectory/README"), "\n\r");
            }
            if(FileSystem::isFile("$sourceDirectory/license")) {
                $return['license'] = trim(FileSystem::readFile("$sourceDirectory/license"), "\n\r");
            } else if(FileSystem::isFile("$sourceDirectory/LICENSE")) {
                $return['license'] = trim(FileSystem::readFile("$sourceDirectory/LICENSE"), "\n\r");
            }
        }
        return $return;
    }

    /**
     * Creates a zip file containing all files in the source directory. The zip
     * has the name $moduleName.zip. Additionally
     *      -   a file $moduleName.version is created, which contains the main
     *          SHA1 checksum over all single files checksums
     *      -   a file $moduleName.content is written, which contains details
     *          about documented PHP classes in JSON format
     *      -   a file $moduleName.zip.sha1 is written, which contains the SHA1
     *          checksum of the zip file
     *      -   a file $moduleName.zip.md5 is written, which contains the MD5
     *          checksum of the zip file
     *
     * @param  $moduleName
     * @param  $sourceDirectory
     * @param  $publicDirectory
     */
    public static final function publishModule($moduleName, $sourceDirectory, $publicDirectory) {
        $sourceDirectory = trim(rtrim($sourceDirectory, ' /'));
        $publicDirectory = trim(rtrim($publicDirectory, ' /'));
        $moduleName = strtolower(trim($moduleName));
        if(empty($moduleName) || strpos($moduleName, '/') !== false || strpos($moduleName, ' ') !== false) {
            throw new Exception('Module name is invalid: "' . $moduleName . '"');
        } else if(empty($sourceDirectory)) {
            throw new Exception('No source directory specified to publish');
        } else if(!FileSystem::isDirectory($sourceDirectory)) {
            throw new Exception('Source directory to publish does not exist: ' . $sourceDirectory);
        } else if(empty($publicDirectory)) {
            throw new Exception('No public directory specified to publish');
        } else if(!FileSystem::isDirectory($publicDirectory)) {
            throw new Exception('No such publishing directory: ' . $publicDirectory);
        } else if(!FileSystem::isWritable($publicDirectory)) {
            throw new Exception('Directory to publish in is not writable: ' . $publicDirectory);
        } else if(strpos($publicDirectory, $_SERVER['DOCUMENT_ROOT']) === false) {
            throw new Exception('Directory to publish in is not a sub-directory of this web server htdocs: ' . $publicDirectory);
        } else {
            $libzip  = $publicDirectory . '/' . $moduleName . '.zip';
            $chksum  = $publicDirectory . '/' . $moduleName . '.checksum';
            $version = $publicDirectory . '/' . $moduleName . '.version';
            $content = $publicDirectory . '/' . $moduleName . '.content';
            $license = $publicDirectory . '/' . $moduleName . '.license';
            $readme  = $publicDirectory . '/' . $moduleName . '.readme';

            // Remove actual published files
            if(FileSystem::isFile($libzip)) FileSystem::delete($libzip);
            if(FileSystem::isFile($chksum)) FileSystem::delete($chksum);
            if(FileSystem::isFile($content)) FileSystem::delete($content);
            if(FileSystem::isFile($version)) FileSystem::delete($version);
            if(FileSystem::isFile($license)) FileSystem::delete($license);
            if(FileSystem::isFile($readme)) FileSystem::delete($readme);

            // Write source folder contents as zip, checksum file, details and
            // zip file verification checksums (for auto updater)
            $ver = new self();
            $ver->readFiles(FileSystem::find($sourceDirectory), $sourceDirectory);
            ZipFile::compress($sourceDirectory, $libzip);
            FileSystem::writeFile("$libzip.sha1", sha1_file($libzip));
            FileSystem::writeFile("$libzip.md5", md5_file($libzip));
            FileSystem::writeFile($chksum, $ver->getChecksum());
            FileSystem::writeFile($content, json_encode($ver->getFileDetails()));

            // Copy info file contents
            if(FileSystem::isFile("$sourceDirectory/version")) {
                FileSystem::writeFile($version, FileSystem::readFile("$sourceDirectory/version"));
            } else if(FileSystem::isFile("$sourceDirectory/VERSION")) {
                FileSystem::writeFile($version, FileSystem::readFile("$sourceDirectory/VERSION"));
            }
            if(FileSystem::isFile("$sourceDirectory/license")) {
                FileSystem::writeFile($license, FileSystem::readFile("$sourceDirectory/license"));
            } else if(FileSystem::isFile("$sourceDirectory/LICENSE")) {
                FileSystem::writeFile($license, FileSystem::readFile("$sourceDirectory/LICENSE"));
            }
            if(FileSystem::isFile("$sourceDirectory/readme")) {
                FileSystem::writeFile($readme, FileSystem::readFile("$sourceDirectory/readme"));
            } else if(FileSystem::isFile("$sourceDirectory/README")) {
                FileSystem::writeFile($readme, FileSystem::readFile("$sourceDirectory/README"));
            }
        }
    }

    /**
     * Compares the version of a specified module with the version information
     * files on a rempte server ("repository") using HTTP lookup request. The
     * $sourceDirectory is the local folder containing the module source files,
     * the $referenceUri is the URL where the module is published (conform to the
     * Versioning::publishModule(...) method). Furthermore, a diff stat and
     * details about all documented files is generated, each for local and remote.
     * The following result types are possible:
     *
     *  (1) Versions are identical
     *  (2) Update available. (If new files are added at the remote server or only
     *      documentation/whitespace has changed, but not the algorighms
     *  (3) Update recommended. At least one file is different in the interpreted
     *      source code - which could be a security bug fix.
     *
     *  Results are presented in an associative array(
     *       'checked' => true if version was successfully checked
     *       'identical' => true if all files are identical
     *       'code_identical' => true if the local algorighms are up to date
     *       'text' => String representation of the result
     *       'diff' => Array containing all files (keys) information if they are
     *                 different
     *       'local' => array containing details about the local versions
     *       'remote' => array containing details about the remote versions
     *  )
     *
     * @param string $moduleName
     * @param string $sourceDirectory
     * @param string $referenceUri
     * @return array
     */
    public static final function checkModuleVersion($moduleName, $sourceDirectory, $referenceUri) {
        $moduleName = strtolower(trim($moduleName));
        $sourceDirectory = trim(rtrim($sourceDirectory, ' /'));
        $return = array(
            'checked' => false,
            'version_identical' => false,
            'update_recommended' => false,
            'update_available' => false,
            'new_features_available' => false,
            'local_untracked_features' => false,
            'identical' => false,
            'code_identical' => false,
            'text' => 'Checksum not checked: ',
            'diff' => array(),
            'local'  => array('checksum' => '', 'version' => '0.0', 'details' => array()),
            'remote' => array('checksum' => '', 'version' => '0.0', 'details' => array())
        );
        if(!FileSystem::isDirectory($sourceDirectory)) {
            throw new Exception("Local source directory does not exist: $sourceDirectory");
        } else if(empty($moduleName)) {
            throw new Exception("You did not specify a module name");
        } else {

            // Get the local statistics
            $return['local'] = self::readLocalModuleVersion($sourceDirectory);

            // Process checksum file
            $rq = new HttpRequest();
            if($rq->request("$referenceUri/$moduleName.checksum")->getResponseCode() != 200) {
                $return['text'] .= 'HTTP lookup failed: ' . "$referenceUri/$moduleName.checksum";
            } else {
                $return['remote']['checksum'] = trim($rq->getOutput(), "\n\r\t ");
                if($return['remote']['checksum'] == $return['local']['checksum']) {
                    $return['checked'] = true;
                    $return['identical'] = true;
                    $return['code_identical'] = true;
                    $return['version_identical'] = true;
                    $return['text'] = 'Versions are identical';
                    $return['remote']['details'] = $return['local']['details'];
                    $return['remote']['version'] = $return['local']['version'];
                } else if($rq->request("$referenceUri/$moduleName.content")->getResponseCode() != 200) {
                    $return['checked'] = true;
                    $return['identical'] = false;
                    $return['code_identical'] = false;
                    $return['text'] .= 'HTTP lookup failed:"' . "$referenceUri/$moduleName.content";
                } else {
                    $return['checked'] = true;
                    $return['identical'] = false;
                    $return['code_identical'] = false;
                    $return['text'] = 'Update available';
                    $return['remote']['details'] = @json_decode($rq->getOutput(), true);
                }
                unset($ver, $rq);

                if($return['checked']) {
                    // Build diff
                    $fkeys = array_merge(array_keys($return['local']['details']), array_keys($return['remote']['details']));
                    $files = array();
                    foreach($fkeys as $f) { $files[strtolower($f)] = $f; }
                    unset($fkeys);

                    $local = array_change_key_case($return['local']['details'], CASE_LOWER);
                    $remote = array_change_key_case($return['remote']['details'], CASE_LOWER);
                    $return['text'] = 'No update required';

                    if(!empty($remote) && !empty($local)) {
                        // Match local file against the remote files, shrink the
                        // arrays for each match
                        while(!empty($local)) {
                            reset($local);
                            $file = key($local);
                            $return['diff'][$files[$file]] = array(); // Use the original file name
                            $f = &$return['diff'][$files[$file]];
                            $f['local'] = true;
                            if(!isset($remote[$file])) {
                                $return['local_untracked_features'] = true;
                                $f['remote'] = false;
                                $f['identical'] = false;
                                $f['code_identical'] = false;
                                $f['text'] = 'Only local';
                            } else if($remote[$file]['file_sha1'] == $local[$file]['file_sha1']) {
                                $f['remote'] = true;
                                $f['identical'] = true;
                                $f['code_identical'] = true;
                                $f['text'] = 'Files are identical';
                            } else if($remote[$file]['source_md5'] == $local[$file]['source_md5']) {
                                $return['update_available'] = true;
                                $f['remote'] = true;
                                $f['identical'] = false;
                                $f['code_identical'] = true;
                                $f['text'] = 'Source codes are identical, but docs/whitespaces different';
                            } else {
                                $return['update_available'] = true;
                                $return['update_recommended'] = true;
                                $f['remote'] = true;
                                $f['identical'] = false;
                                $f['code_identical'] = false;
                                $f['text'] = 'Files are different';
                            }
                            unset($f); // unlink reference
                            array_shift($local); // implicit next local
                            if(isset($remote[$file])) unset($remote[$file]);
                        }

                        // All other files are only remote ("new files")
                        foreach($remote as $file => $desc) {
                            $return['update_available'] = true;
                            $return['new_features_available'] = true;
                            $return['diff'][$files[$file]] = array(
                                'local' => false,
                                'remote' => true,
                                'identical' => false,
                                'code_identical' => false,
                                'text' => 'Only remote'
                            );
                        }
                        unset($local, $remote, $f, $file, $desc);

                        // On updates check the remote version file
                        if($return['update_available']) {
                            // Get version file
                            $rq = new HttpRequest();
                            if($rq->request("$referenceUri/$moduleName.version")->getResponseCode() == 200) {
                                $return['remote']['version'] = trim($rq->getOutput(), "\n\r\t ");
                                if($return['remote']['version'] == $return['local']['version']) {
                                    $return['version_identical'] = true;
                                }
                            }
                        }

                        // Final text specification
                        if($return['update_recommended']) {
                            $return['text'] = "Update recommended to version " . $return['remote']['version'];
                        } else if($return['update_available']) {
                            $t = array();
                            if(!$return['code_identical']) {
                                $t[] = 'some changes in documentation/whitespace';
                            }
                            if($return['new_features_available']) {
                                $t[] = 'new features added';
                            }
                            if($return['local_untracked_features']) {
                                $t[] = 'features removed or you added stuff locally';
                            }
                            $t = implode(', ', $t);
                            if(!empty($t)) $t = "($t)";
                            $return['text'] = trim("Update available (remote version {$return['remote']['version']}), $t");
                        } else if($return['local_untracked_features']) {
                            $return['text'] = "No update required (Version is {$return['remote']['version']}, only a remote file was removed or you added a file locally)";
                        } else if($return['identical']) {
                            $return['text'] = "No update available (Version is {$return['local']['version']}. The modules are absolutely identical)";
                        } else {
                            $return['text'] = "No update available (Version is {$return['local']['version']})";
                        }
                    }
                }
            }
        }
        return $return;
    }
}
?>

This Article is also available in Deutsch.

HTTP request class

stfwi — Tue, 24 Aug 2010 07:59:31 +0000

This is a simple class that sends a HTTP request to web server and fetches the response headers and the content of the response. You can decide if exceptions shall be thrown if the server responds with an error message (e.g. 404). The sample code explains more than a thousand words:

Sample source code

 true,
    // use session, automatically start (this is default)
    'use_session' => true,
    // path to library var directory, we use an one one
    // The var path must be writable for the server, it is NOT the
    // directory "/var" on Unix-Like systems, but a directory to serialize
    // "variables" in.
    'var_path' => sys_get_temp_dir(),
    // path to library tmp directory, we use an one one
    // The tmp path must be writable for the server
    'tmp_path' => sys_get_temp_dir(),
    // extensions for variable export/import files (this is default)
    'var_extension' => '.tmp',
    // The include paths to search for classes
    'include_paths' => array()
));

Tracer::setLevel(5);

print '';

// Create a request object
$rq = new HttpRequest();

// Set the timeout to 5 seconds, default is 10 seconds
$rq->setTimeout(5);

// Set the port (80 is already the default port)
$rq->setPort(80);

// We want an exceptino on 404 etc.
$rq->setThrowExceptionOnErrorResponse(true);

try {
    // Let's get a page, in this case the version file of the library
    $rq->request('http://www.atwillys.de/repository/swlib/swlib.version');

    // This would be the check if exceptions are switched off.
    if(!$rq->isResponseOk()) {
        throw new Exception("...");
    }

    // Print the headers
    print "Headers:\n";
    foreach($rq->getResponseHeaders() as $header => $value) {
        print "   $header=$value\n";
    }

    // Print the content output:
    print "Content:\n";
    print htmlspecialchars($rq->getOutput());

} catch(Exception $e) {
    print $e->getMessage();
}

print '';
?>

Output

Headers:
   date=Tue, 24 Aug 2010 08:54:46 GMT
   server=Apache
   last-modified=Fri, 20 Aug 2010 10:39:21 GMT
   etag="2861c7a0-3-48e3ee9601b18"
   accept-ranges=bytes
   content-length=3
   connection=close
   content-type=text/plain; charset=UTF-8

Content:
1.0

Class source code

port;
    }

    /**
     * Sets the port to connect to
     * @param int $port
     */
    public function setPort($port) {
        if(!settype($port, 'integer')) {
            throw new Exception('Port no integer: "' . $port . '"');
        } else {
            $this->port = $port;
        }
    }

    /**
     * Returns the URL to connect to
     * @return string
     */
    public function getUri() {
        return $this->uri;
    }

    /**
     * Sets the URL to connect to
     * @param string $uri
     */
    public function setUri($uri) {
        $uri = trim($uri);
        if(empty($uri)) {
            throw new Exception('URI is empty');
        } else {
            $this->uri = parse_url($uri);
            if($this->uri['path'] == '') {
                $this->uri['path'] = '/';
            }
        }
    }

    /**
     * Returns the connection and stream timeout in seconds
     * @return int
     */
    public function getTimeout() {
        return $this->timeout;
    }

    /**
     * Sets the connection and stream timeout in seconds
     * @param int $seconds
     */
    public function setTimeout($seconds) {
        if(!settype($seconds, 'integer')) {
            throw new Exception('Timeout no integer: "' . $seconds . '"');
        } else {
            $this->timeout = $seconds > 0 ? $seconds : 0;
        }
    }

    /**
     * Set if an exception shall be thrown by request() if the server
     * responds with an error message, such as 404
     * @param bool $throw
     */
    public function setThrowExceptionOnErrorResponse($throw) {
        $this->throwExceptionOnErrorResponse = (bool) $throw;
    }

    /**
     * Returns if an exception shall be thrown by request() if the server
     * responds with an error message, such as 404
     * @return bool
     */
    public function getThrowExceptionOnErrorResponse() {
        return $this->throwExceptionOnErrorResponse;
    }

    /**
     * Returns the response without headers
     * @return string
     */
    public function getOutput() {
        return $this->output;
    }

    /**
     * Returns an associative array containing the
     * response headers.
     * @return array
     */
    public function getResponseHeaders() {
        return $this->responseHeaders;
    }

    /**
     * Returns the server response code.
     * (200=OK ...)
     * @return int
     */
    public function getResponseCode() {
        return $this->responseCode;
    }

    /**
     * Returns if the request was successful
     * @return bool
     */
    public function isResponseOk() {
       return floor($this->responseCode / 100) == 2 || in_array($this->responseCode, array(302, 307));
    }

    /**
     * Start the request, parse the response.
     * You can also specify the URL by using
     * setURI(...) instead of using the optional
     * parameter $uri.
     * @param string $uri
     * @param int $port
     */
    public function request($uri=null, $port=null) {
        $this->output = '';
        $this->responseHeaders = array();
        $this->responseCode = 0;
        $this->request = '';
        if(!empty($uri)) $this->setURI($uri);
        if(!empty($port)) $this->setPort($port);
        $uri = $this->uri;
        $errno = 0;
        $errstr = '';
        $socket = fsockopen($uri['host'], $this->port, $errno, $errstr, 5);
        if(!$socket) {
            throw new Exception('Failed to connect to server ' . $uri['host'] . ':' . $errstr);
        } else {
            $this->requestHeaders['Host'] = $uri['host'];
            $this->requestHeaders['Connection'] = 'close';
            $this->request = 'GET ' . $uri['path'] .
                (!empty($uri['query']) ? ('?' . $uri['query']) : '' ) .
                (!empty($uri['fragment']) ? ('#' . $uri['fragment']) : '' ) .
                " HTTP/1.1";
            $request = $this->request . "\r\n";
            foreach($this->requestHeaders as $key => $value) {
               $request .= $key . ': ' . $value . "\r\n";
            }
            $request .= "\r\n";
            stream_set_timeout($socket, $this->timeout);
            fputs($socket, $request);
            while(!feof($socket)) {
                $this->output .= fgets($socket, 4096);
            }
            fclose($socket);

            if($this->output != '') {
                $header = explode("\r\n\r\n", $this->output, 2);
                $this->output = end($header);
                $header = array_filter(explode("\n", str_replace("\r","\n", reset($header))));
                if(count($header) > 0) {
                    $this->responseCode = explode(' ', array_shift($header));
                    $responseCodeMessage = array_pop($this->responseCode);
                    $this->responseCode = intval(array_pop($this->responseCode));
                    foreach($header as $rc) {
                        $rc = explode(':', $rc, 2);
                        if(count($rc) == 2) {
                            $this->responseHeaders[strtolower(trim($rc[0]))] = trim($rc[1]);
                        } else {
                            $this->responseHeaders[strtolower(trim($rc[0]))] = '';
                        }
                    }
                    if(isset($this->responseHeaders['transfer-encoding']) && $this->responseHeaders['transfer-encoding'] == 'chunked') {
                        if(strlen( ltrim($this->output)) > 0) {
                            $nl = "\r\n";
                            $t = $this->output;
                            $this->output = '';
                            do {
                                $t = ltrim($t);
                                $p = strpos($t, $nl);
                                if($p === false) {
                                    throw new Exception('Chunked HTTP response content invalid.');
                                } else {
                                    $l = hexdec(substr($t, 0, $p));
                                    if(!is_numeric($l) || $l < 0) {
                                        throw new Exception('Chunked HTTP response content invalid.');
                                    } else {
                                        $this->output .= substr($t, ($p + strlen($nl)), $l);
                                        $t  = substr($t, ($l + $p + strlen($nl)));
                                    }
                                }
                            }
                            while(strlen(trim($t)) > 0);
                            unset($t);
                        }
                    }
                }
            }
        }

        if($this->throwExceptionOnErrorResponse && !$this->isResponseOk()) {
            throw new Exception("HTTP request failed: $responseCodeMessage", $this->responseCode);
        }
        return $this;
    }
}
?>

This Article is also available in Deutsch.

MySQL administration class

stfwi — Thu, 05 Aug 2010 16:15:56 +0000

I implemented this class for administrative MySQL tasks. It is based on MySql and provides additional functionalities like retrieving CREATE and DROP queries for existing tables or the database. These functions are used by to “main methods”: backup() and restore(). backup() writes the whole database (or only a part of it) in a zip file, including the creation queries and a backup info file. restore() can read and interpret these files and regenerates the database structure including the contents. The table backup/restore works with direct file I/O of the MySQL server, so if you have a webspace that has a distributed system of web server and MySQL server, then the web server might not be able to access the generated files (as they are not stored in the local file system of the web server). Simply check it if it works (maybe I will have published a modified version of this class soon to address this possible issue).

Sample source code

$dba = new MySqlAdministration('test', 'root', '', 'localhost');

// Get the name of the database
$r = $dba->getDatabaseName();
print '$db->getDatabaseName() = ' . print_r($r, true) . '
';

// This would be the query to delete the database
$r = $dba->getDatabaseDropQuery('test');
print '$db->getDatabaseDropQuery() = ' . print_r($r, true) . '
';

// This would be the query to delete the table "test"
$r = $dba->getTableDropQuery('test');
print '$db->getTableDropQuery(...) = ' . print_r($r, true) . '
';

// This would be the query to create the database
$r = $dba->getDatabaseCreationQuery();
print '$db->getDatabaseCreationQuery() = ' . print_r($r, true) . '
';

// This would be the query to create all the tables (structure) as they are now
$r = $dba->getTableCreationQuery();
print '$db->getTableCreationQuery() = ' . print_r($r, true) . '
';

// This would be the query to create the table 'test'
$r = $dba->getTableCreationQuery('test');
print '$db->getTableCreationQuery("test") = ' . print_r($r, true) . '
';

// Lock the table, so that we can query multiple requests
$readlock = array('test');
$writelock = array('test2');
$dba->lock($readlock, $writelock);
// ... Here we do some stuff ...
// Unlock the table, this will be automatically done on destruction
$dba->unlock();

// Get table information (this is a method derived from MySql)
$r = $dba->getTableStatus('test');
print '$db->getTableStatus(...) = ' . print_r($r, true) . '
';

// Make a backup of the database in a zip file
$tablePrefix = '';  // We don't have a table prefix here
$tables = null;     // null or array() means ALL tables
$comments = 'This is my backup BLA BLA ...'; // A comment for the info file
$dropTablesBeforeInsert = true; // We drop the tables before we recreate them
$dropAndRecreateDatabase = false; // We do not drop the whole database

$r = $dba->backup($tablePrefix, $tables, $comments, $dropTablesBeforeInsert, $dropAndRecreateDatabase);
print '$db->backup(...) = ' . print_r($r, true) . '
';

// This is the file you can download then
$zipArchive = $r['zipfile']; 

// Restore the database:
$tablePrefix = '';  // We don't change the table prefix, but we could
$r = $dba->restore($zipArchive, $tablePrefix);
print '$db->restore(...) = ' . print_r($r, true) . '
';

// Delete the zip file ...
FileSystem::delete($zipArchive);

Output


$db->getDatabaseName() = test

$db->getDatabaseDropQuery() = DROP DATABASE IF EXISTS `test`;

$db->getTableDropQuery(...) = DROP TABLE IF EXISTS `test`;

$db->getDatabaseCreationQuery() = CREATE DATABASE IF NOT EXISTS `test` /*!40100 DEFAULT CHARACTER SET utf8 */;

$db->getTableCreationQuery() = CREATE TABLE IF NOT EXISTS `test` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `rid` int(11) NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=MyISAM AUTO_INCREMENT=30 DEFAULT CHARSET=utf8;

CREATE TABLE IF NOT EXISTS `test2` (
  `id` int(11) NOT NULL AUTO_INCREMENT COMMENT 'The primary key',
  `name` varchar(128) NOT NULL COMMENT 'Name of the person',
  `email` text NOT NULL COMMENT 'email address of the person',
  PRIMARY KEY (`id`),
  KEY `name` (`name`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8 COMMENT='An example table for emails';

$db->getTableCreationQuery("test") = CREATE TABLE IF NOT EXISTS `test` (
  `id` int(11) NOT NULL AUTO_INCREMENT,
  `rid` int(11) NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=MyISAM AUTO_INCREMENT=30 DEFAULT CHARSET=utf8;

$db->getTableStatus(...) = Array (
    {test} => Array (
        {name} => test
        {engine} => MyISAM
        {version} => 10
        {row_format} => Fixed
        {rows} => 0
        {avg_row_length} => 0
        {data_length} => 0
        {max_data_length} => 2533274790395903
        {index_length} => 1024
        {data_free} => 0
        {auto_increment} => 30
        {create_time} => 2010-08-05 16:34:55
        {update_time} => 2010-08-05 16:34:55
        {check_time} =>
        {collation} => utf8_general_ci
        {checksum} =>
        {create_options} =>
        {comment} =>
    )
    {test2} => Array (
        {name} => test2
        {engine} => MyISAM
        {version} => 10
        {row_format} => Dynamic
        {rows} => 0
        {avg_row_length} => 0
        {data_length} => 0
        {max_data_length} => 281474976710655
        {index_length} => 2048
        {data_free} => 0
        {auto_increment} => 1
        {create_time} => 2010-08-05 16:34:55
        {update_time} => 2010-08-05 16:34:55
        {check_time} => 2010-08-05 16:34:55
        {collation} => utf8_general_ci
        {checksum} =>
        {create_options} =>
        {comment} => An example table for emails
    )
)

$db->backup(...) = Array (
    {zipfile} => /Applications/XAMPP/xamppfiles/temp/2010-8-5-MySqlBackup.zip
    {backupinfo} => /mysqlbackup.test.1281022607.create.sql
    {comments} => This is my backup BLA BLA ...
    {time} => 2010-08-05 15:36:47 GMT
    {database} => test
    {prefix} =>
    {create} => /mysqlbackup.test.1281022607.create.sql
    {tables} => Array (
        {test} => Array (
            {name} => test
            {file} => /mysqlbackup.test.1281022607.test.tdata
        )
        {test2} => Array (
            {name} => test2
            {file} => /mysqlbackup.test.1281022607.test2.tdata
        )
    )
)

$db->restore(...) =

Class source code

getTableNames();
        } else if((!is_array($readLockTables) && !empty($readLockTables) ) || ( !is_array($writeLockTables)) && !empty($writeLockTables) ) {
            // No array and not null, array(), false: invalid.
            throw new MySqlException('The arguments for the tables to lock is incorrect.');
        }

        // conditionize
        if(!empty($readLockTables)) {
            foreach($readLockTables as $key => $table) {
                $readLockTables[$key] = !in_array($table, $writeLockTables) ? self::escape(trim($table)) : false;
            }
            $readLockTables = array_filter($readLockTables);
            $readLockTables = !empty($readLockTables) ? (implode(' READ,', $readLockTables) . ' READ') : '';
        } else {
            $readLockTables = '';
        }
        if(!empty($writeLockTables)) {
            foreach($writeLockTables as $key => $table) {
                $writeLockTables[$key] = self::escape(trim($table));
            }
            $writeLockTables = '' . implode(' WRITE,', $writeLockTables) . ' WRITE';
        } else {
            $writeLockTables = '';
        }

        self::trace("Lock tables");
        $this->query('LOCK TABLES ' . $readLockTables . (($readLockTables!='' && $writeLockTables!='') ? ',' : '') . $writeLockTables);
    }

    /**
     * Unlocks all table locks
     */
    public final function unlock() {
        self::trace('Unlock all tables');
        try {
            $this->query("UNLOCK TABLES");
        } catch(MySqlException $e) {
            self::trace('Falied to unlock tables');
        }
    }

    /**
     * Returns the SQL query for creating the database in the same
     * manner as the actual one is. The query always includes an
     * "IF NOT EXISTS" clause.
     * @return string
     */
    public final function getDatabaseCreationQuery() {
       $r = reset($this->query("SHOW CREATE DATABASE `" . $this->getDatabaseName() . "`" ));
       $r = array_change_key_case($r, CASE_LOWER);
       $r = explode("\n", $r['create database'] . ';', 2);
       $r[0] = str_ireplace('CREATE DATABASE', 'CREATE DATABASE IF NOT EXISTS', $r[0]);
       $r = implode("\n", $r);
       return $r;
    }

    /**
     * Returns the SQL query for creating a table that is identical
     * to the existing table. If no table is specified, the method
     * generates a creation query for alltables in the database.
     * @param string $table
     * @param bool $ifNotExists
     * @return string
     */
    public final function getTableCreationQuery($table=null, $ifNotExists=true) {
       if(is_null($table)) {
           $tables = $this->getTableNames();
       } else {
           $tables = array(self::escape($table));
       }

       $queries = array();
       foreach($tables as $table) {
           $r = reset($this->query("SHOW CREATE TABLE `" . $table . "`" ));
           $r = array_change_key_case($r, CASE_LOWER);
           $r = $r['create table'] . ';';
           if($ifNotExists) {
               $r = explode("\n", $r, 2);
               $r[0] = str_ireplace('CREATE TABLE', 'CREATE TABLE IF NOT EXISTS', $r[0]);
               $r = implode("\n", $r);
           }
           $queries[] = $r;
           $queries[] = '';
       }

       return implode("\n", $queries);
    }

    /**
     * Returns the SQL query for removing a table from database
     * @param string $table
     * @return string
     */
    public function getTableDropQuery($table) {
        return "DROP TABLE IF EXISTS `" . self::escape($table) . "`;";
    }

    /**
     * Returns the SQL query for deleting the whole database
     * @return string
     */
    public function getDatabaseDropQuery() {
        return "DROP DATABASE IF EXISTS `" . self::escape($this->getDatabaseName()) . "`;";
    }

    /**
     * Backups the table structure as SQL file and all tables as query output,
     * if the $tablePrefix (if spexified) matches the begin of the table name
     * (case insensitive). Returns an array containing information about the
     * backup files of all tables, the prefixes, and the table names without
     * prefix, as well as a boolean flag that indicated weather the table was
     * backuped or not.
     * @param string $tablePrefix
     * @param array $tables
     * @param string $comments
     * @param bool $dropTablesBeforeInsert
     * @param bool $dropAndRecreateDatabase
     * @return array
     */
    public final function backup($tablePrefix='', $tables=null, $comments='', $dropTablesBeforeInsert=true, $dropAndRecreateDatabase=false) {
        // Conditionize and check arguments
        if(empty($tables)) {
            $tables = $this->getTableNames();
        } else if(!is_array($tables)) {
            throw new MySqlException('If specified, then the tables (names) to backup must be pass as array');
        }

        if(!settype($comments, 'string')) {
            throw new MySqlException('Comment must be a string');
        }

        $date = new UtcDate();
        $backupFolder = FileSystem::getTempDirectory() . "/mysqlbackup";

        $return = array(
            'zipfile' => '',
            'backupinfo' => '',
            'comments' => $comments,
            'time' => $date->toString(),
            'database' => $this->getDatabaseName(),
            'prefix' => $tablePrefix,
            'create' => '',
            'tables' => array()
        );

        // Delete backup folder to have a new folder with proper write conditions
        if(FileSystem::exists($backupFolder)) {
            FileSystem::delete($backupFolder) ;
        }
        FileSystem::mkdir($backupFolder);
        $filebase =  $backupFolder . '/mysqlbackup.' . $this->getDatabaseName() . '.' . $date->getTimeStamp() . '.';

        // Main backup in critical section surrounded by lock(), try {} catch() {}, unlock()
        $ee = null;
        {
            // Lock all tables READ/WRITE
            $structureData = '';
            $this->lock();
            try {
                // Backup structure
                if($dropAndRecreateDatabase) {
                    $structureData .= str_ireplace('`' . $this->getDatabaseName() . '`', '<>', $this->getDatabaseDropQuery()) . "\n\n";
                }
                $structureData .=  str_ireplace('`' . $this->getDatabaseName() . '`','<>', $this->getDatabaseCreationQuery()) . "\n\n";

                // Iterate tables
                foreach($tables as $table) {
                    $table = trim($table);
                    if(empty($tablePrefix) || stripos($table, $tablePrefix) === 0) {
                        $name = empty($tablePrefix) ? $table : str_ireplace($tablePrefix, '', $table);
                        $file =  $filebase . $name . '.tdata';
                        $this->query("SELECT * FROM `" . self::escape($table) . "` INTO OUTFILE '$file'");
                        // Save data for further usage
                        $return['tables'][$name] = array(
                            'name' => $name,
                            'file' => str_ireplace($backupFolder, '', $file)
                        );

                        // If desired, drop original table
                        if($dropTablesBeforeInsert) {
                            $dt = $this->getTableDropQuery($table);
                            if(!empty($tablePrefix)) {
                                $dt = str_replace($table, '<>'. $name, $dt);
                            }
                            $structureData .= $dt . "\n\n";
                            unset($dt);
                        }

                        // Create table:
                        $ct = $this->getTableCreationQuery($table);
                        if(!empty($tablePrefix)) {
                            $ct = explode("\n", $ct, 2);
                            $ct[0] = str_replace($table, '<>'. $name, $ct[0]);
                            $ct = implode("\n", $ct);
                        }
                        $structureData .=  $ct . "\n\n";
                        unset($ct);
                    }

                    // Export structure to file
                    $file = $filebase . "create.sql";
                    if(@file_put_contents($file, $structureData) === false) {
                        throw new Exception('Could not write structure file');
                    } else {
                        $return['create'] = str_ireplace($backupFolder, '', $file);;
                    }
                }

                // Generate backup info
                $return['backupinfo'] = str_ireplace($backupFolder, '', $file);
                $backupInfo = json_encode($return);
                $file = $filebase . "backup.json";
                if(@file_put_contents($file, $backupInfo) === false) {
                    throw new Exception('Could not write backup info file');
                }
            } catch(Exception $e) {
                Tracer::traceException($e);
                $ee = $e;
            }
            // unlock the tables
            $this->unlock();
        }

        // Exception handling after unlock()
        if(!is_null($ee)) {
            try {
                FileSystem::delete($backupFolder);
            } catch(Exception $e) {
            }
            throw $ee;
        }
        // Compress backup folder
        $zip = FileSystem::getTempDirectory() . '/' . $date->getYear() . '-' . $date->getMonth() .  '-' . $date->getDay() . '-MySqlBackup.zip';
        ZipFile::compress($backupFolder, $zip);
        FileSystem::delete($backupFolder);
        $return['zipfile'] = $zip;
        return $return;
    }

    /**
     * Restores the database content from zip archive. If $tablePrefix
     * is not spexified, the argument will be read from the backup info file in
     * the zip archive. The database is the database actually selected in this
     * object.
     * @param string $zipArchive
     * @param string $tablePrefix
     */
    public final function restore($zipArchive, $tablePrefix=null) {
        $backupFolder = FileSystem::getTempDirectory() . "/mysqlbackup";
        if(FileSystem::exists($backupFolder)) {
            FileSystem::delete($backupFolder);
        }
        try {
            ZipFile::extract($zipArchive,  FileSystem::getTempDirectory());
            if(!FileSystem::exists($backupFolder)) {
                throw new Exception('Backup folder does not exist after extracting zip archive');
            } else {
                $info = FileSystem::find($backupFolder, "*.backup.json");
                if(count($info) == 0) {
                    throw new Exception('Could not find a backup info file in zip archive');
                } else if(count($info) > 1) {
                    throw new Exception('Threr are more than one backup info files in zip archive. Do not know which to use');
                } else {
                    // Get arguments or default arguments from info file
                    $info = json_decode(FileSystem::readFile(reset($info)), true);

                    if(is_null($tablePrefix)) {
                        if(isset($info['prefix']) && strlen(trim($info['prefix'])) > 0) {
                            $tablePrefix = $info['prefix'];
                        } else {
                            throw new Exception('No table prefix specified and no prefix in the backup info file');
                        }
                    }

                    if(!isset($info['create'])) {
                        throw new Exception('Missing "create" entry in info file');
                    } else if(!isset($info['tables']) || !is_array($info['tables'])) {
                        throw new Exception('Missing tables entry in info file');
                    } else if(empty($info['tables'])) {
                        throw new Exception('Tables entry in info file empty, no tables to restore registered.');
                    } else {
                        $tablePrefix = addslashes(trim($tablePrefix));
                        $create = FileSystem::readFile($backupFolder . '/'. trim($info['create'], " /"));
                        $create = str_replace('<>', $tablePrefix, $create);
                        $create = str_replace('<>', $this->getDatabaseName(), $create);
                        $create = str_replace("\n", "", str_replace("\r","", $create));
                        $tables = array();
                        Tracer::trace_r($info['tables'], '$info["tables"]');
                        foreach($info['tables'] as $table) {
                            $tables[$tablePrefix . $table['name']] = $backupFolder . '/'. trim($table['file'], " /");
                        }

                        Tracer::trace_r($tables, '$tables');
                        foreach(explode(';', $create) as $query) {
                            $query = trim($query);
                            if(!empty($query)) {
                                Tracer::trace($query);
                                $this->query($query);
                            }
                        }
                        foreach($tables as $tableName => $tableFile) {
                            @chmod($tableFile, 0777);
                            $query = "LOAD DATA INFILE '$tableFile' INTO TABLE `" . self::escape($tableName) . "`";
                            if(!empty($query)) {
                                Tracer::trace($query);
                                $this->query($query);
                            }
                        }
                    }
                }
            }
        } catch(Exception $e) {
            FileSystem::delete($backupFolder);
            throw $e;
        }
        FileSystem::delete($backupFolder);
    }
};
?>

This Article is also available in Deutsch.

MySQL wrapper class

stfwi — Thu, 05 Aug 2010 13:46:37 +0000

One of the older classes, but nonetheless worth to publish as it may be of use. The MySQL wrapper contains methods to obtain information about the database, tables, as well as normal queries, queries to objects or arrays and key-value based requests. Multiple instances are possible, as each object has an own link to its database connection. The instances automatically connect to the database and throw exceptions (MySqlException) on error. It is also the base class for a MySQL administration class, which is published on this site as well.

Sample source code

getStatus();
print '$db->getStatus() = ' . print_r($r, true) . '
';

// Returns information about the status and fields of all tables
$r = $db->getTableStatus();
print '$db->getTableStatus() = ' . print_r($r, true) . '
';

// Returns information about the fields of a table
$r = $db->getTableFields('test');
print '$db->getTableFields() = ' . print_r($r, true) . '
';

// Query an insert, where the fields are defined as array keys and the values
// as the array values. The return value is the id if the just inserted row.
$id = $db->queryInsertInto('test', array('rid' => rand(0, 1000)));
print '$db->queryInsertInto(...) = ' . print_r($id, true) . '
';

// Query the fields of one entry. This method returns directly the content
// if the filter is an ID (numeric). Otherwise it returns an array containing
// the rows with associative values (even if there is only one matching row).
$r = $db->queryFields('test', array('id','rid'), $id);
print '$db->queryFields(' . $id . ') = ' . print_r($r, true) . '
';

// This method works with SQL syntax and returns an array of objects
$r = $db->queryObjects('SELECT * FROM test WHERE id=' . $id);
print '$db->queryObjects(...) = ' . print_r($r, true) . '
';

// This method works with SQL syntax and returns an array of field-arrays
$r = $db->queryArrays('SELECT * FROM test WHERE id=' . $id);
print '$db->queryArrays(...) = ' . print_r($r, true) . '
';

// Change a row
$r = $db->queryUpdateTable('test', array('id' => $id, 'rid' => rand(0, 1000)));
print '$db->queryUpdateTable(...) = ' . print_r($r, true) . '
';

// Delete the row
$r = $db->queryDeleteFrom('test', $id);
?>

Output

Class source code



 'localhost',
        'database' => '',
        'user' => '',
        'password' => ''
    );

    /**
     * SQL connection link /id
     * @var unknown
     */
    private $link;

    /**
     * Server connection, usual localhost
     * @var string
     */
    private $server;

    /**
     * SQL server login user
     * @var string
     */
    private $user;

    /**
     * SQL login password
     * @var string
     */
    private $password;

    /**
     * SQL database
     * @var string
     */
    private $database;

    /**
     * Connected flag
     * @var bool
     */
    private $connected;

    /**
     * Defines class defaults
     * @param string $database
     * @param string $user
     * @param string $password
     * @param string $server
     */
    public static final function config($database=null, $user=null, $password=null, $server=null) {
        if(!is_null($database)) self::$config['database'] = (empty($database) ? 'localhost' : $database);
        if(!is_null($server)) self::$config['server'] = trim($server);
        if(!is_null($user)) self::$config['user'] = trim($user);
        if(!is_null($password)) self::$config['password'] = $password;
    }

    /**
     * Escapes the value of a mysql query value text (so that no injection
     * possible and normal text values do not cause an unexpected error)
     * Null is escaped with NULL
     * @param string $query_value
     * @return string
     */
    public static final function escape($query_value) {
        if(empty($query_value)) {
            return is_null($query_value) ? 'NULL' : '';
        } else {
            return mysql_real_escape_string($query_value);
        }
    }

    /**
     * MySQL wrapper class constructor
     * @param string $database
     * @param string $user
     * @param string $password
     * @param string $server
     */
    public function __construct($database='', $user='', $password='', $server='') {
        self::trace("($database, $user, (pwd), $server)");
        $this->server      = $server != '' ? $server : self::$config['server'];
        $this->user        = $user	!= '' ? $user : self::$config['user'];
        $this->password    = $password != '' ? $password : self::$config['password'];
        $this->database    = $database != '' ? $database : self::$config['database'];
        $this->connected   = false;
        $this->link        = null;
        try { $this->connect(); } catch(Exception $e) { Tracer::traceException($e); }
    }

    /**
     * MySQL wrapper class destructor
     */
    public function __destruct() {
        self::trace("Disconnect ...");
        $this->disconnect(true);
    }

    /**
     * Server connected inicator
     * @return bool
     */
    public final function isConnected() {
        return $this->connected;
    }

    /**
     * Returns the name of the database
     * @return string
     */
    public final function getDatabaseName() {
        return $this->database;
    }

    /**
     * Connect to server
     */
    public final function connect() {
        if(!$this->connected) {
            self::trace("Connecting");
            $this->link = @mysql_connect($this->server, $this->user, $this->password);
            if(!$this->link) {
                throw new MySqlException("Connecting to database failed");
            } else if(!mysql_select_db($this->database)) {
                @mysql_close($this->link);
                throw new MySqlException("Failed to select database");
            } else {
                if(function_exists('mysql_set_charset')) {
                    @mysql_set_charset('utf8', $this->link);
                } else {
                    @mysql_query("SET NAMES 'utf8'", $this->link);
                }
                $this->connected = true;
            }
        }
    }

    /**
     * Disconnect MySQL server
     */
    public final function disconnect() {
        @mysql_close($this->link);
        $this->link = null;
        $this->connected = false;
    }

    /**
     * Returns the database structure and status as assoc. array.
     * @return array
     */
    public final function getStatus() {
        $database = array(
            'name' => $this->getDatabaseName(),
            'tables' => array()
        );
        $tables = $this->getTableStatus();
        foreach($tables as $table) {
            $name = $table['name'];
            $table['fields'] = $this->getTableFields($name);
            $database['tables'][$name] = $table;
        }
        return $database;
    }

    /**
     * Returns the list of table names in the database
     * @return array
     */
    public final function getTableNames() {
        if(!$this->isConnected()) {
            $this->connect();
        }
        $result = array();
        $tables = $this->query("SHOW TABLES FROM " . $this->database);

        foreach($tables as $table) {
            $table = reset($table);
            $result[] = $table;
        }
        return $result;
    }

    /**
     * Returns an assoc. array with information about all tables
     * @return array
     */
    public final function getTableStatus() {
        $tables = array();
        $r = $this->query("SHOW TABLE STATUS FROM " . $this->getDatabaseName() . ";");
        foreach($r as $table) {
            $table = array_change_key_case($table, CASE_LOWER);
            $tables[$table['name']] = $table;
        }
        return $tables;
    }

    /**
     * Returns the field specifications of the database fields
     * @param string $table
     * @return array
     */
    public final function getTableFields($table) {
        $result = array();
        $table = self::escape($table);
        $fields = $this->query("SHOW FULL COLUMNS FROM `$table`");
        foreach($fields as $field) {
            $field = array_change_key_case($field, CASE_LOWER);
            $result[$field['field']] = $field;
        }
        return $result;
    }

    /**
     * Returns the resource to the query. The result resource has to be
     * set free manually.
     * @param string $query
     * @return resource
     */
    public final function queryResource($query) {
        self::trace("query=$query");
        if(empty($query)) {
            throw new MySqlException("Query failed: no query rule specified.");
        } else if(!$this->isConnected()) {
            $this->connect();
        }
        $result = @mysql_query($query, $this->link);

        if($result === false) {
            Tracer::trace('MySql ERROR=' . mysql_error());
            throw new MySqlException('MySql query failed');
        } else {
            return $result;
        }
    }

    /**
     * Perform query. Returns array of assoc arrays
     * @param string $query
     * @return array&
     */
    public final function & query($query) {
        $result = $this->queryResource($query);
        $data = array();
        if(is_resource($result)) {
            while($row = mysql_fetch_assoc($result)) {
                $data[] = $row;
            }
            @mysql_free_result($result);
        }
        return $data;
    }

    /**
     * Query SELECT form the table, where all fields specified by the field names
     * array are fetched into a structure (assoc. array).
     * @param string $table
     * @param array $fieldNames
     * @param string $idOrFilter
     * @param int $numRows
     * @param int $fromRow
     * @return void
     */
    public final function & queryFields($table, $fieldNames=array(), $idOrFilter='', $numRows=0, $fromRow=0) {
        $fromRow = intval($fromRow);
        $numRows = intval($numRows);
        $table = '`' . self::escape(trim($table)) . '`';

        if(empty($fieldNames)) {
            $fields = '*';
        } else if(!is_array($fieldNames)) {
            throw new MySqlException('Specified field names must be passed as array');
        } else {
            $fields = array();
            foreach($fieldNames as $key => $f) {
                $fields[] = '`' . self::escape($f) . '`';
            }
            $fields = implode(',', $fields);
        }

        $query = "SELECT $fields FROM $table";

        if(is_numeric($idOrFilter)) {
            $query .= ' WHERE id=' . intval($idOrFilter);
        } else if(!empty($idOrFilter)) {
            $query .= " WHERE $idOrFilter";
        }

        if($numRows > 0) {
            $query .= ($fromRow > 0) ? (" LIMIT $fromRow, $numRows") : (" LIMIT $numRows");
        }

        $r = $this->query($query);

        return $r;
    }

    /**
     * Query into a result instance.
     * @return array
     */
    public final function & queryArrays($query) {
        $result = $this->queryResource($query);
        $data = array();
        while($row = mysql_fetch_array($result)) $data[] = $row;
        @mysql_free_result($result);
        return $data;
    }

    /**
     * Query into a result instance.
     * @return array
     */
    public final function & queryObjects($query, $class=null) {
        $result = $this->queryResource($query);
        if(!is_null($class) && !class_exists($class) && !swlib::hasClass($class)) {
            throw new MySqlException('Class does not exist:' . $class);
        } else {
            $data = array();
            if(is_null($class)) {
                while($o = mysql_fetch_object($result)) {
                    $data[] = $o;
                }
            } else {
                while($o = mysql_fetch_object($result, $class)) {
                    $data[] = $o;
                }
            }
            @mysql_free_result($result);
            return $data;
        }
    }

    /**
     * Query UPDATE table, where the SET ='' are the array key/value pairs.
     * $filter is according to "WHERE id=" or "WHERE name="test" LIMIT 1";
     * @param string $table
     * @param array $keyValuePairs
     * @param string $filter
     * @param int $limit
     * @return void
     */
    public final function queryUpdateTable($table, array $keyValuePairs, $filter='', $limit=1) {
        $table = self::escape($table);
        $limit = (is_numeric($limit) && $limit > 0) ? " LIMIT " . intval($limit) : '';
        if(empty($filter)) {
            if(isset($keyValuePairs['id'])) {
                $filter = "WHERE id=" . self::escape($keyValuePairs['id']);
                unset($keyValuePairs['id']);
            } else {
                throw new MySqlException('You must set a filter (WHERE anyfield=anyvalue) if you do not have the filed "id"');
            }
        }
        foreach($keyValuePairs as $key => $value) {
            $keyValuePairs[$key] = "`$key`='" . self::escape($value) . "'";
        }
        $keyValuePairs = implode(',', $keyValuePairs);
        $query = "UPDATE `$table` SET $keyValuePairs $filter $limit";
        $this->query($query);
    }

    /**
     * Query INSERT INTO table, where the SET ='' are the array key/value pairs.
     * Returns the complete just inserted row.
     * @param string $table
     * @param array $keyValuePairs
     * @return array
     */
    public final function queryInsertInto($table, array $keyValuePairs) {
        $table = trim($table);
        if(empty($table)) {
            throw new MySqlException('Cannot append data in database without a specified table (empty string)');
        } else {
            $table = '`' . self::escape($table)  . '`';
            $keys = $values = array();

            if(isset($keys['id']) && empty($keys['id'])) {
                $keys['id'] = null;
            }
            foreach($keyValuePairs as $key => $value) {
                if(empty($key)) {
                    throw new MySqlException('Database field key is empty');
                } else {
                    $keys[] = '`' . self::escape(trim($key)) . '`';
                    $values[] = "'" . self::escape($value) . "'";
                }
            }
            $keys = implode(',', $keys);
            $values = implode(',', $values);
            $query = "INSERT INTO $table ($keys) VALUES ($values);";
            $this->query($query);
            $r = $this->query('SELECT LAST_INSERT_ID();');
            if(empty($r)) {
                throw new MySqlException('Could not get autoincrement id of insert action');
            } else {
                $r = reset($r);
                return reset($r);
            }
        }
    }

    /**
     * Query DELETE FROM table. If $idOrFilter is numeric, then the filter
     * will be automatically set to "WHERE id=$idOrFilter", if filter is a
     * text, then the filter text will be used.
     * @param string $table
     * @param array $idOrFilter
     * @return void
     */
    public final function queryDeleteFrom($table, $idOrFilter) {
        $idOrFilter = trim($idOrFilter);
        if(is_numeric($idOrFilter)) {
            $idOrFilter = "id='$idOrFilter'";
        } else if(empty($idOrFilter)) {
            throw new MySqlException('No id/filter given to indicate the row to delete');
        }
        $this->query("DELETE FROM $table WHERE $idOrFilter");
    }

    /**
     * Saves the a BLOB in the database in a file in the file system. Write
     * the condition like "id=1". The WHERE is added by the method.
     * @param string $file
     * @param string $table
     * @param string $field
     * @param string $condition
     */
    public final function queryBlobToFile($file, $table, $field, $condition) {
        $file = trim($file);
        $table = self::escape(trim($table));
        $field = self::escape(trim($field));
        $condition = str_replace(';', '', $condition); // no multiple commands allowed.
        if(file_exists($file)) {
            throw new MySqlException('The file to write the BLOB in already exists');
        } else if(!is_dir(dirname($file))) {
            throw new MySqlException('Parent directory of the file to save does not exist');
        } else if(!is_writable(dirname($file))) {
            throw new MySqlException('Parent directory of the file to save is not writable for you');
        } else {
            $query = "SELECT `$field` FROM `$table` WHERE $condition LIMIT 1 INTO DUMPFILE '$file'";
            self::trace($query);
            $this->query($query);
        }
    }

    /**
     * Performs a query to write a BLOB field in the database from a
     * existing file in the file system.
     * @param string $file
     * @param string $table
     * @param string $field
     */
    public final function queryFileToBlob($file, $table, $field, $condition) {
        // All the submethods throw exceptions if something goes wrong.
        $file = trim($file);
        $table = self::escape(trim($table));
        $field = self::escape(trim($field));
        $condition = str_replace(';', '', $condition); // no multiple commands allowed.
        $data = self::escape(FileSystem::readFile($file));
        self::trace("UPDATE `$table` SET `$field`='[BLOB of " . (strlen($data) >> 10) . "kb]' WHERE $condition");
        $this->query("UPDATE `$table` SET `$field`='$data' WHERE $condition");
    }

    /**
     * Private tracing method
     * @param string $text
     * @param int $level
     */
    protected function trace($text, $level=1) {
        if(!Tracer::tracedClass(__CLASS__)) return;
        Tracer::trace($text, $level);
    }
};
?>

This Article is also available in Deutsch.

Configuration access wrapper class

stfwi — Thu, 05 Aug 2010 11:20:59 +0000

During a chat with a friend about the convenience of object-style access to PHP configuration, which are defined as structured associative arrays, we came to a lightweight wrapper class that addresses these issues. As the configuration array is already in use by other modules, it should not be changed, and a copy to objects would lead to a higher memory usage. So the solution is based on cascaded references to the configuration array. The example shows what it is about:

Sample source code

 'no',
    'database' => array(
        'server' => 'unlocalhost',
        'user' => 'me',
        'password' => 'none',
        'database' => 'Example database',
        'tables' => array(
            'contacts' => array(
                'id', 'name', 'email'
            ),
            'cache' => array(
                'id', 'uri', 'chksum', 'expires', 'etag', 'lastmodified'
            ),

        )
    ),
    'aNumber' => 10,
    'a_text' => 'nothing in there'
);

// This is the instance of the wrapper class, which "points" to
// the root node of the array
$cfg = new ConfigAccess($theConfigurationStructure);

// Access to a scalar config entry
print 'config.aNumber = ' . $cfg->aNumber . '
';

// Access to a scalar config entry in a sub-configuration
print 'config.database.user = ' . $cfg->database->user . '
';

// Access to an array config entry in a sub-configuration
// Note here we have to escape, because the class returns an object
// instead of an array. If we went the array instead, we call the toArray()
// escape function
print 'config.database.tables.cache = ' . print_r($cfg->database->tables->cache->toArray(), true) . '
';
?>

Class source code

__r = &$cref;
    }

    /**
     * Returns the content of the condiguration array (or sub-array) with the
     * key $p. If this is an array, then a ConfigAccess object will be returned
     * instead, which "points" to the sub-branch of the configuration.
     * @param string $p
     * @return mixed
     */
    public final function __get($p) {
        if(!isset($this->__r[$p])) {
            throw new Exception("Config entry '$p' does not exist");
        }
        return is_array($this->__r[$p]) ? new self(&$this->__r[$p]) : $this->__r[$p];
    }

    /**
     * Config setter, this is NOT allowed. Hence, the method throws an exception.
     * @param string $p
     * @param string $v
     */
    public final function __set($p,  $v) {
        throw new Exception('You cannot modify the configuration');
    }

    /**
     * This method is an escape for the case that the content of a configuration
     * is an array and shall not be represented with a ConfigAccess object.
     * @return array
     */
    public final function toArray() {
        return $this->__r;
    }
}
?>

This Article is also available in Deutsch.

Calendar class library

stfwi — Mon, 02 Aug 2010 15:39:11 +0000

Because there are already thousands of calendars in the net, I added my own one as well ;-). This is a highly maintainable and easily extendable bunch of classes to display month and day calendars with events. It consists the following classes:

The main calendar class GregorianCalendar, which organizes the bundle and provides the interface to the application/script.
the renderers GregorianMonthCalendarRenderer and GregorianDayCalendarRenderer, which are the base for the visualization. They are fed with preprocessed data.
The events are managed by the GregorianCalendarEventController. This class is to load, filter and save events in files or a data base, or every possible source (that’s why it is a separate class).
The class GregorianCalendarEvent is the base class for your own events, managed by the controller and used by the other classes.

That’s all. The sample code illustrates that you don’t need to do much to have a functioning calendar, and that it is very easy to extend it.
The class sources are normally split in more class files and here collected in one block. Normally every class is in a file with the same name as the class and the extension “.class.php”.

Sample source code



getParent()->getHourDivision();
        $t1 = new LocalDate($event->getStart());
        $t2 = new LocalDate($event->getEnd());
        $o  = $event->name . " (" . $event->id . ")";
        $o .= '
' . sprintf("%02d:%02d", $t1->getHour(), $t1->getMinute()) .
                ' to ' . sprintf("%02d:%02d", $t2->getHour(), $t2->getMinute());
        $t1 = $tick * floor($event->getStart() / $tick);
        $t2 = $tick * floor($event->getEnd() / $tick);
        $t1 = new LocalDate($t1);
        $t2 = new LocalDate($t2);
        $o .= '
' . sprintf("%02d:%02d", $t1->getHour(), $t1->getMinute()) .
                ' to ' . sprintf("%02d:%02d", $t2->getHour(), $t2->getMinute());
        return $o;
    }
}
?>

unserialize($nameOrDBArray);
        }
    }

    /**
     * Returns an associatove array to save the event in a database. The
     * data are JSON encoded
     * @return string
     */
    public function serialize() {
        $r = array(
            'id' => $this->id,
            'name' => $this->name,
            'begin' => $this->start,
            'end' => $this->end,
            'type' => $this->type,
            'data' => $this->data
        );
        unset($r['data']['resource']);
        $r['data'] = json_encode($r['data'], JSON_FORCE_OBJECT);
        return $r;
    }

    /**
     * Sets all object variables corresponding to the assoc array returned by
     * serialize().
     * @param array $r
     */
    public function unserialize(array $r) {
        $this->id = $r['id'];
        $this->name = $r['name'];
        $this->start = $r['begin'];
        $this->end = $r['end'];
        $this->type = $r['type'];
        $this->data = empty($r['data']) ? array() : json_decode($r['data'], true);
    }
}
?>

 'samplecalendar',
        'user' => 'cal',
        'password' => 'cal',
        'server' => 'localhost'
    );

    /**
     * Database
     * @return MySql
     */
    protected function db() {
        if(is_array($this->database)) {
            $this->database = new MySql($this->database['database'],
            $this->database['user'], $this->database['password'],
            $this->database['server']);
        }
        return $this->database;
    }

    /**
     * Returns all events that start and end between a given period.
     * @param mixed $from
     * @param mixed $to
     * @return SampleEvent[]
     */
    public function getEventsBetween($from, $to) {
        $from = new LocalDate($from);
        $to = new LocalDate($to);
        $r = $this->db()->query('SELECT * FROM events WHERE begin >= ' .
                Mysql::escape($from->getTimeStamp(), true)  . ' && end <' .
                MySql::escape($to->getTimeStamp(), true) . ' && NOT FIND_IN_SET(\'d\', flags)' );
        foreach($r as $k => $v) $r[$k] = new SampleEvent($v);
        return $r;
    }

    /**
     * Returns all events that do not end before and do not start after the given
     * time period.
     * @param mixed $from
     * @param mixed $to
     * @return SampleEvent[]
     */
    public function getEventsWhichMatch($from, $to) {
        $from = new LocalDate($from);
        $to = new LocalDate($to);
        $r = $this->db()->query('SELECT * FROM events WHERE NOT end < ' .
                Mysql::escape($from->getTimeStamp(), true)  . ' && NOT begin >' .
                MySql::escape($to->getTimeStamp(), true) . ' && NOT FIND_IN_SET(\'d\', flags)' );
        foreach($r as $k => $v) $r[$k] = new SampleEvent($v);
        return $r;
    }

    /**
     * Returns the event by id, null if not found
     * @param int $id
     */
    public function getEvent($id) {
        $r = $this->db()->query('SELECT * FROM events WHERE id= ' .
                Mysql::escape($id, true) . ' LIMIT 1');
        if(!empty($r)) {
            $event = new SampleEvent();
            $event->unserialize(reset($r));
            return $event;
        } else {
            return null;
        }
    }

    /**
     * Saves an event
     * @param SampleEvent $event
     */
    public function saveEvent(SampleEvent $event) {
        $r = $event->serialize();
        if(!empty($r['id']) && is_numeric($r['id'])) {
            $this->db()->queryUpdateTable('events', $r);
        } else if(empty($r['id'])) {
            $r['id'] = null;
            $this->db()->queryInsertInto('events', $r);
        } else {
            throw new Exception('Sample event id is invalid: ' . $id);
        }
    }

}
?>

 true,
    'use_session' => true,
    'var_path' => '/tmp',
    'tmp_path' => '/tmp',
    'var_extension' => '.tmp',
    'include_paths' => array(
        dirname(__FILE__) . '/include'
    )
));

// Let's set another time zone for local dates
date_default_timezone_set('Europe/London');

try {

    // Instantize our event controller
    $rec = new SampleEventController();

    // Instantize the main calendar object and make settings ...
    $cal = new GregorianCalendar();
    $cal->setEventController($rec);         // Set our own event controller
    $cal->setDayDisplayFrom("06:00:00");    // The day cal will ignore 05:59
    $cal->setDayStartsAt("08:00:00");       // From 06:00 to 07:59 is grayed
    $cal->setDayEndsAt("19:59:59");         // From 20:00 to 22:59 is grayed
    $cal->setDayDisplayTo("22:59:59");      // From 23:00 to 23:59 is ignored
    $cal->setHourDivision(900);             // One tick is 15 minutes (resolution)

    // These are our renderers:
    $monthCal = new SampleMonthCalendarRenderer();
    $dayCal = new SampleDayCalendarRenderer();

} catch(Exception $e) {
    print "exception:" . $e->getMessage();
    Tracer::traceException($e);
}

try {
    // The day to show in the month calendar, note that you should
    // SANATIZE this before ...
    if(isset($_GET['month-calendar-show'])) {
        $_SESSION['month-calendar-show'] = $_GET['month-calendar-show'];
    }
    if(isset($_SESSION['month-calendar-show'])) {
        $cal->setDateToShow($_SESSION['month-calendar-show']);
    }
} catch(Exception $e) {
    Tracer::traceException($e);
    $cal->setDateToShow( $cal->getToday() );
}

try {
    // The selected day in the month/day calendar, note that you should
    // SANATIZE this before ...
    if(isset($_GET['month-calendar-select'])) {
        $_SESSION['month-calendar-select'] = $_GET['month-calendar-select'];
    }
    if(isset($_SESSION['month-calendar-select'])) {
        $cal->setSelectedDate($_SESSION['month-calendar-select']);
    }
} catch(Exception $e) {
    Tracer::traceException($e);
    $cal->setSelectedDate( $cal->getDateToShow() );
}

if(false)
{
    // Here a piece of code that creates some events in your database
    MySql::traced(true);

    // We round the timestamp to half an our
    $from = new LocalDate(); // new local date without argument is now.
    $from->setTimeStamp(round($from->getTimeStamp()/1800)*1800);
    $to = $from->add(9 * 3600); // events takes place for 9 hurs
    $ev = new SampleEvent('Overlapping 0', $from, $to, array('who' => uniqid(),
        'test1' => rand(0, 10)), 'sample' );
    $rec->saveEvent($ev); // save it in the database
    Tracer::trace("Overlapping 0 = $ev"); // and trce it ...

    $from = $from->add(5*1800);
    $to = $from->add(5*1800);
    $ev = new SampleEvent('Overlapping 1', $from, $to, array('who' => uniqid(),
        'test1' => rand(0, 10)), 'sample' );
    $rec->saveEvent($ev);
    Tracer::trace("Overlapping 1 = $ev");

    $from = $from->add(2435);
    $to = $from->add(9873);
    $ev = new SampleEvent('Overlapping 2', $from, $to, array('who' => uniqid(),
        'test1' => rand(0, 10)), 'sample' );
    $rec->saveEvent($ev);
    Tracer::trace("Overlapping 2 = $ev");

    $from = $from->add(234);
    $to = $from->add(4827);
    $ev = new SampleEvent('Overlapping 3', $from, $to, array('who' => uniqid(),
        'test1' => rand(0, 10)), 'sample' );
    $rec->saveEvent($ev);
    Tracer::trace("Overlapping 3 = $ev");

    $from = $from->add(4321);
    $to = $from->add(12345);
    $ev = new SampleEvent('Overlapping 4', $from, $to, array('who' => uniqid(),
        'test1' => rand(0, 10)), 'sample' );
    $rec->saveEvent($ev);
    Tracer::trace("Overlapping 4 = $ev");

}

// The view starts here:

?>

Sample calendar





';
    print '';
    print "\n" . $cal->renderMonthCalendar($monthCal) . "\n";
    print $testout . "\n";
    print '';
    print '';
    print "\n" . $cal->renderDayCalendar($dayCal) . "\n";
    print '';
    print '';
} catch(Exception $e) {
    print "exception:" . $e->getMessage();
    Tracer::traceException($e);
}
?>

Output

As the output is not that small, I made a html snapshot of one page, which you can find it here.

Class source code

 $dayDisplayedTo to '23:59:59' will not be displayed
     * @var int
     */
    private $dayDisplayedTo = '23:59:59';

    /**
     * Reference to the event controller object
     * @var GregorianCalendarEventController
     */
    private $eventController = null;

    /**
     * Constructor
     * @param IDate $dateToShow
     * @param IDate $today
     * @param string $dateClass
     */
	public function  __construct($dateToShow=null, $today=null, $dateClass='LocalDate') {
        $this->dateClass = $dateClass;
        $this->setToday($today);
        $this->setDateToShow($dateToShow);
        $this->setWeekStartsOnSunday(false);
        $this->setDayStartsAt($this->dayStartsAt);
        $this->setDayEndsAt($this->dayEndsAt);
        $this->setDayDisplayFrom($this->dayDisplayedFrom);
        $this->setDayDisplayTo($this->dayDisplayedTo);
        $this->setSelectedDate($this->getToday());
	}

    /**
     * Returns of a time $t is/takes place at the day $day. The day must be normed
     * to 00:00:00h.
     * @param IDate $day
     * @param IDate $t
     * @return bool
     */
    protected final function isSameDay(IDate $day, IDate $t) {
        return ($t->getTimeStamp() >= $day->getTimeStamp()) && ($t < $day->getTimeStamp() + 86400);
    }

    /**
     * Returns the date specified as today (which is normally today, but can
     * be specified for historic date referencing)
     * @return IDate
     */
    public final function getToday() {
        return $this->today;
    }

    /**
     * Returns the date specified as selected (e.g. for displaying a day calendar)
     * @return IDate
     */
    public final function getSelectedDate() {
        return $this->dateSelected;
    }

    /**
     * Returns the date which has to be displayed. This can be a time with hours
     * minues and seconds. The renderers have to adjust the displayed interval.
     * For a month calendar, the calenar will e.g. render the month July 2010 if
     * $dateToShow is 2010-07-15 03:05:30.
     */
    public final function getDateToShow() {
       return $this->dateToShow;
    }

    /**
     * Returns if the week shall start on Sunday (or Monday)
     * @return bool
     */
    public final function getWeekStartsOnSunday() {
        return $this->weekStartsWithSunday;
    }

    /**
     * Returns the week day index dependent on $weekStartsWithSunday, either
     * [0,1,2,3,4,5,6] (if Sun first day) or [1,2,3,4,5,6,0] (if Mon first day)
     * @return bool
     */
    public final function getWeekDayIndex() {
        return $this->weekDayIndex;
    }

    /**
     * Returns the week day abbreviation depending on $weekStartsWithSunday
     * @param int $index
     * @return string
     */
    public final function getWeekDayAbbreviation($index) {
        $index -= 1;
        if(!isset($this->weekDayIndex[$index])) {
            throw new Exception("No such week day index: $index");
        } else {
            return $this->weekDayAbbr[$this->weekDayIndex[$index]];
        }
    }

    /**
     * Retuens the time period of on division in a day calendar (in seconds).
     * @return int
     */
    public function getHourDivision() {
        return $this->hourDivision;
    }

    /**
     * Returns when the day starts for the calendar
     * @return int
     */
    public final function getDayStartsAt() {
        return $this->dayStartsAt;
    }

    /**
     * Returns when the day ends for the calendar
     * @return int
     */
    public final function getDayEndsAt() {
        return $this->dayEndsAt;
    }

    /**
     * Every time between 00:00:00 and getDayDisplayedFrom()
     * will not be displayed
     * @return int
     */
    public final function getDayDisplayedFrom() {
        return $this->dayDisplayedFrom;
    }

    /**
     * Every time > getDayDisplayedTo() to '23:59:59' will not be displayed
     * @return int
     */
    public final function getDayDisplayedTo() {
        return $this->dayDisplayedTo;
    }

    /**
     * Returns a reference to the event controller, creates a standard controller
     * of no controller instantiated/set.
     * @return GregorianCalendarEventController
     */
    public final function getEventController() {
        if(!$this->eventController instanceof GregorianCalendarEventController) {
            $this->eventController = new GregorianCalendarEventController();
        }
        return $this->eventController;
    }

    /**
     * Returns the date specified as today (which is normally today, but can
     * be specified for historic date referencing)
     * @param mixed $today
     */
    public final function setToday($today) {
        $today = is_null($today) ? (new $this->dateClass()) : (new $this->dateClass(strval($today)));
        if(!($today instanceof IDate)) {
            throw new Exception('Date classes used here must implement IDate');
        }
        $this->today = $today;
        $this->today->setSerial(null, null, null, 0, 0, 0);
    }

    /**
     * Sets the date specified as selected (e.g. for displaying a day calendar)
     * @return IDate
     */
    public final function setSelectedDate($selected) {
        $selected = is_null($selected) ? (new $this->dateClass()) : (new $this->dateClass(strval($selected)));
        if(!($selected instanceof IDate)) {
            throw new Exception('Date classes used here must implement IDate');
        }
        $this->dateSelected = $selected;
    }

    /**
     * Stets the date which has to be displayed. This can be a time with hours
     * minues and seconds. The renderers have to adjust the displayed interval.
     * For a month calendar, the calenar will e.g. render the month July 2010 if
     * $dateToShow is 2010-07-15 03:05:30.
     * @param mixed $dateToShow
     */
    public final function setDateToShow($dateToShow) {
        $dateToShow = !is_null($dateToShow) ? (new $this->dateClass(strval($dateToShow))) : (($this->today instanceof IDate) ?  clone $this->today : new $this->dateClass());
        if(!($dateToShow instanceof IDate)) {
            throw new Exception('Date classes used here must implement IDate');
        }
        $this->dateToShow = $dateToShow;
    }

    /**
     * Sets if the week shall start on Sunday (or Monday)
     * @param bool $bool
     */
    public final function setWeekStartsOnSunday($bool) {
        $this->weekStartsWithSunday = $bool ? true : false;
        $this->weekDayIndex = $this->weekStartsWithSunday ? array(0,1,2,3,4,5,6) : array(1,2,3,4,5,6,0);
    }

    /**
     * Sets when the day starts for the calendar
     * @param mixed $time
     */
    public final function setDayStartsAt($time) {
        $time = new $this->dateClass($time);
        $this->dayStartsAt = 3600*$time->getHour() + 60*$time->getMinute() + $time->getSecond();
    }

    /**
     * Sets when the day ends for the calendar
     * @param mixed $time
     */
    public final function setDayEndsAt($time) {
        $time = new $this->dateClass($time);
        $this->dayEndsAt = 3600*$time->getHour() + 60*$time->getMinute() + $time->getSecond();
    }

    /**
     * Every time between 00:00:00 and $time (les than $time)
     * will not be displayed
     * @param mixed $time
     */
    public final function setDayDisplayFrom($time) {
        $time = new $this->dateClass($time);
        $this->dayDisplayedFrom = 3600*$time->getHour() + 60*$time->getMinute() + $time->getSecond();
    }

    /**
     * Every time > $time to '23:59:59' will not be displayed
     * @param mixed $time
     */
    public final function setDayDisplayTo($time) {
        $time = new $this->dateClass($time);
        $this->dayDisplayedTo = 3600*$time->getHour() + 60*$time->getMinute() + $time->getSecond();
    }

    /**
     * Sets a new event controller
     * @param GregorianCalendarEventController $controller
     */
    public final function setEventController($controller) {
        if(is_null($controller) || $controller instanceof GregorianCalendarEventController) {
            $this->eventController = $controller;
        } else {
            throw new Exception('Calendar event controllers must be null (to unset) or GregorianCalendarEventController');
        }
    }

    /**
     * Sets the time period of on division in a day calendar (in seconds).
     * @param int $period
     */
    public function setHourDivision($period) {
        if(!is_numeric($period)) {
            throw new Exception('Day division period must be numeric');
        } else {
            $period = intval($period);
            if($period <= 0) {
                throw new Exception('Day division period must be > 0');
            } else if(3600 % $period != 0) {
                throw new Exception('An special amount of division periods must fit exactly 1 hour (3600 MOD period = 0)');
            } else {
                $this->hourDivision = $period;
            }
        }
    }

    /**
     * Returns a rendered representation of a month calendar
     * @param GregorianMonthCalendarRenderer $renderer
     * @return array
     */
	public final function renderMonthCalendar(GregorianMonthCalendarRenderer $renderer) {
        if(!$renderer instanceof GregorianMonthCalendarRenderer) {
            throw new Exception('You must use a GregorianMonthCalendarRenderer to render this');
        }
        $renderer->setParent($this);
        $monthStart = new LocalDate($this->dateToShow->getYear() . "-" . $this->dateToShow->getMonth() . "-01");
        $monthEnd   = $monthStart->getNext('month');
        $monthEnd->setTimeStamp($monthEnd->getTimeStamp()-1);
        $calStart   = $monthStart->getLast($this->weekStartsWithSunday ? 'sunday' : 'monday');
        $calEnd     = $monthEnd->getNext($this->weekStartsWithSunday ? 'sunday' : 'monday');

        if($calEnd->inWeeks() - $calStart->inWeeks() < 6) {
            $calEnd = $calEnd->getNext($this->weekStartsWithSunday ? 'sunday' : 'monday');
        }
        $calEnd->setTimeStamp($calEnd->getTimeStamp()-1);

        $selected = clone $this->getSelectedDate();
        $selected->setSerial(null,null,null,0,0,0);
        $selected = $selected->getTimeStamp();

        Tracer::trace('TZ           = ' . $monthEnd->getTimeZoneName());
        Tracer::trace('Date to show = ' . $this->dateToShow . '/' . $this->dateToShow->getWeekDay());
        Tracer::trace('Month start  = ' . $monthStart . '/' . $monthStart->getWeekDay());
        Tracer::trace('Month end    = ' . $monthEnd . '/' . $monthEnd->getWeekDay());
        Tracer::trace('Cal start    = ' . $calStart . '/' . $calStart->getWeekDay());
        Tracer::trace('Cal end      = ' . $calEnd . '/' . $calEnd->getWeekDay());
        Tracer::trace('Cal selected = ' . $this->getSelectedDate() . '/' . $selected);
        Tracer::trace("Num of weeks = " . ($calEnd->inWeeks() - $calStart->inWeeks()));

        $today = clone $this->today;
        $ts_s = $monthStart->getTimeStamp();
        $ts_e = $monthEnd->getTimeStamp();
        $wday = $week = 0;

        $events = array();
        $dayPeriod = 24*3600-1;

        $renderer->onStart();
        $renderer->onWeekStart(0);
        for($day = new LocalDate($calStart); $day->getTimeStamp() <= $calEnd->getTimeStamp(); $day = $day->getNext('day')) {
            if($wday > 6) {
                $wday = 0;
                $renderer->onWeekEnd($week++);
                $renderer->onWeekStart($week);
            }
            $events = $this->getEventController()->getEventsWhichMatch($day, $day->getTimeStamp()+$dayPeriod);
            $ts = $day->getTimeStamp();
            $renderer->onDay(clone $day, $ts < $ts_s || $ts > $ts_e, $ts==$selected, $events);
            $wday++;
        }
        $renderer->onEnd();
		return $renderer->getOutput();
	}

    /**
     * Returns a rendered representation of a day calendar
     * @param GregorianDayCalendarRenderer $renderer
     * @param $date=null
     */
    public final function renderDayCalendar(GregorianDayCalendarRenderer $renderer, $date=null) {
        if(!$renderer instanceof GregorianDayCalendarRenderer) {
            throw new Exception('You must use a GregorianDayCalendarRenderer to render this');
        }
        if(!is_null($date)) {
            $date = new $this->dateClass($date);
        } else {
            $date = clone $this->getSelectedDate();
        }

        $renderer->setParent($this);
        $dayStart = new $this->dateClass($date);
        $dayEnd   = new $this->dateClass($date);
        $dayStart->setSerial(null, null, null, 0, 0, 0);
        $dayEnd->setSerial(null, null, null, 23, 59, 59);
        $dayStartsAt = $dayStart->getTimeStamp() + $this->getDayStartsAt();
        $dayEndsAt   = $dayStart->getTimeStamp() + $this->getDayEndsAt();
        $displayFrom = $dayStart->getTimeStamp() + $this->getDayDisplayedFrom();
        $displayTo   = $dayStart->getTimeStamp() + $this->getDayDisplayedTo();
        $tick        = $this->getHourDivision();

        Tracer::trace('Date to show = ' . $date);
        Tracer::trace('Day start    = ' . $dayStart . '/' . $dayStart->toTimeString());
        Tracer::trace('Day end      = ' . $dayEnd . '/' . $dayEnd->toTimeString());
        Tracer::trace('Cal start    = ' . $dayStartsAt . '/' . ($this->getDayStartsAt()/3600));
        Tracer::trace('Cal end      = ' . $dayEndsAt . '/' . ($this->getDayEndsAt()/3600));

        $events = $this->getEventController()->getEventsWhichMatch($displayFrom, $displayTo);
        $map    = array();

        if(!empty($events)) {
            // Conditionize events: Sort the events by timestamp, assure that keys
            // are the the start timestamps.
            function lmb_sortCallback($a,$b) { return $a->getStart() > $b->getStart() ? 1 : -1; }
            usort($events, lmb_sortCallback);
            $ev = $events;
            $events = array();
            foreach($ev as $event) {
                $events[$event->getId()] = $event;
            }
            unset($ev);

            foreach($events as $event) Tracer::trace("EVENT: $event");

            // Generate a 2D map, where the row keys are the tick timestamps
            $map = array();
            for($i=$displayFrom; $i<=$displayTo; $i+=$tick) {
                $map[$i] = array();
            }

            // Place the events in the map, beginning in column 0, first all events
            // that do not overlap (to shrink the loop after that)
            $ev = $events;
            while(!empty($ev)) {
                $event = array_shift($ev);
                $row = $tick * floor($event->getStart() / $tick);

                if($row < $displayFrom) {
                    $row = $displayFrom;
                    $events[$row] = $event;
                }

                $end = $tick * ceil($event->getEnd() / $tick);
                $id  = $event->getId();
                $col = 0;
                // Loop over all known columns to check if there is space ...
                while(isset($map[$row][$col])) {
                    // Check if ther is space ...
                    $fits = true;
                    for($i=$row; $i<=$end; $i+=$tick) {
                        if($map[$i][$col]) {
                            // Not here, try next column
                            $fits = false;
                            break;
                        }
                    }
                    if($fits) {
                        break;
                    } else {
                        $col++;
                    }
                }
                // New column required, create it for the whole day
                if(!isset($fits) || !$fits) {
                    for($i=$displayFrom; $i<=$displayTo; $i+=$tick) {
                        $map[$i][$col] = false;
                    }
                }
                // Place the event in the row and column (and the rows that the
                // event takes place, mark the start row as ID, all other as
                // true (means "busy")
                $map[$row][$col] = $id;
                for($i=$row+$tick; $i<$end; $i+=$tick) {
                    $map[$i][$col] = true;
                }
            }

            // Cleanup
            unset($ev, $fits, $col, $row, $id, $end, $event, $i, $key, $nCols, $nEvents);

//            // Trace the map
//            foreach($map as $key => $row) {
//                $o = strftime("%H:%M:%S", $key) . " = ";
//                foreach($row as $id) {
//                    if($id === true) {
//                        $o .= ' busy';
//                    } else if($id === false) {
//                        $o .= ' free';
//                    } else {
//                        $o .= " " . sprintf("%04d", $id);
//                    }
//                }
//                Tracer::trace_r($o);
//            }
//            unset($o, $key, $row, $id);
        }

        $renderer->onStart($date, $tick, $displayFrom, $dayStartsAt, $dayEndsAt, $displayTo, &$events);
        for($time = $dayStart->getTimeStamp(); $time <= $dayEnd->getTimeStamp(); $time += $tick) {
            $renderer->onTick(new $this->dateClass($time), $tick, $time < $dayStartsAt || $time > $dayEndsAt, $time < $displayFrom || $time > $displayTo, &$events, &$map);
        }
        $renderer->onEnd();
		return $renderer->getOutput();
    }
}
?>

parent = $parentGregorianCalendar;
    }

    /**
     * Sets the parent of the calendar
     * @param GregorianCalendar $calendar
     */
    public final function setParent(GregorianCalendar $calendar) {
        if(!is_null($this->parent) && $this->parent !== $calendar) {
            throw new Exception('You cannot re-assign the parent calendar instance');
        } else {
            $this->parent = $calendar;
        }
    }

    public final function getParent() {
        return $this->parent;
    }

    /**
     * Returns the output of the rendering process
     * @return string
     */
    public final function getOutput() {
        return $this->output;
    }

    /**
     * Callback to start the calendar - every HTML content before the weeks
     * (and days in the weeks). Normally a table, thead, th with weekday names.
     * @return void
     */
    public function onStart() {
        $date = $this->getParent()->getDateToShow();
        $o = '';
        $o .= '';
        $o .= '';
        for($i=1; $i<=7; $i++) {
            $o .= '';
        }
        $o .= '';
        foreach($this->getParent()->getWeekDayIndex() as $i) {
            $o .= '';
        }
        $o .= '';
        $this->output .= $o;
    }

    /**
     * All HTML to close the table, table footer etc.
     * @return void
     */
    public function onEnd() {
        $this->output .= '';
        $o .= '' . ' ' . '';
        $o .= '' . ' ' . '';
        $o .= '' . ucfirst(strftime("%B %Y", $date->getTimeStamp())) . '';
        $o .= '' . strtoupper(substr(gmstrftime('%A', ($i-4)*24*3600), 0, 1)) .'';
    }

    /**
     * Start a new week, normally a  or an additional  with the
     * calendar week (e.g. CW45) etc.
     * @return void
     */
    public function onWeekStart($weekId) {
        $this->output .= '';
    }

    /**
     * Finish a new week, normally a 
     * @return void
     */
    public function onWeekEnd($weekId) {
        $this->output .= "\n";
    }

    /**
     * Renders a day in the week (normally a $dateDayOfMonthTwoDigits
     * @param IDate $day
     * @param bool isPadding
     * @param bool isSelected
     * @param GregorianMonthCalendarRenderer[] $events
     * @return mixed
     */
    public function onDay(IDate $day, $isPadding, $isSelected, $events) {
        $class = array();
        $class[] = $this->getParent()->getWeekDayAbbreviation($day->getWeekDay());
        switch(Math::signz($day->getTimeStamp() - $this->getParent()->getToday()->getTimeStamp())) {
            case -1: $class[] = 'passed'; break;
            case 0 : $class[] = 'today'; break;
        }
        if(!empty($events)) $class[] = 'has-events';
        if($isPadding) $class[] = 'padding';
        if($isSelected) $class[] = 'selected';
        $class = 'class="' . implode(' ', $class) . '"';
        $title = 'title="' . ucwords(strftime("%A, %B %e, %Y", $day->getTimeStamp())) . (count($events) == 0 ? '' : ' (' . count($events) . ' events)').  '"';
        $date = '' . sprintf("%02d", $day->getDay()) . '';
        $day->isPadding = $isPadding;
        $this->output .= "$date";
    }
}
?>

parent = $parentGregorianCalendar;
    }

    /**
     * Sets the parent of the calendar
     * @param GregorianCalendar $calendar
     */
    public final function setParent(GregorianCalendar $calendar) {
        if(!is_null($this->parent) && $this->parent !== $calendar) {
            throw new Exception('You cannot re-assign the parent calendar instance');
        } else {
            $this->parent = $calendar;
        }
    }

    /**
     * Returns the parent Calendar object (which the renderer is for)
     * @return GregorianCalendar
     */
    public final function getParent() {
        return $this->parent;
    }

    /**
     * Sets the id of the table that contains the day calendar
     * @param string $id
     */
    public final function setTableId($id) {
        if(empty($id)) {
            $this->tableId = '';
        } else {
            $this->tableId = trim($id);
        }
    }

    /**
     * Returns the id of the table that contains the day calendar
     * @return string
     */
    public final function getTableId() {
        return $this->tableId;
    }

    /**
     * Returns the output of the rendering process
     * @return string
     */
    public final function getOutput() {
        return $this->output;
    }

    /**
     * Callback to start the calendar - every HTML content before the weeks
     * (and days in the weeks). Normally a table, thead, th with weekday names.
     * @param IDate $date
     * @param int $tick
     * @param int $displayFrom
     * @param int $dayStartsAt
     * @param int $dayEndsAt
     * @param int $displayTo
     * @param GregorianCalendarEvent[] &$events
     * @return void
     */
    public function onStart($date, $tick, $displayFrom, $dayStartsAt, $dayEndsAt, $displayTo, &$events) {
        $id = empty($this->tableId) ? '' : ('id="' . str_replace('#', '', $this->tableId) . '" ');
        $o = '';
        $o .= '';
        $o .= '';
        $this->output .= "$o\n";
    }

    /**
     * All HTML to close the table, table footer etc.
     * @return void
     */
    public function onEnd() {
        $this->output .= "' . ucwords(strftime("%A, %B %e, %Y", $date->getTimeStamp())) . '\n";
        $this->events = array();
    }

    /**
     * Renders one tick with the division period, padding means that the day
     * of the calendar has either not started yet or already ended (according
     * to $dayStartsAt and $dayEndsAt)
     * @param IDate $date
     * @param int $tick
     * @param bool $isPadding
     * @param bool $hidden
     * @param GregorianCalendarEvent[] &$events
     * @param array() &$eventMap
     * @return void
     */
    public function onTick(IDate $date, $tick, $isPadding, $hidden, &$events, &$eventMap) {
        if($hidden) return;
        $class = array();
        if($isPadding) $class[] = 'padding';
        if($date->getMinute() == 0) {
            $class[] = 'full-hour';
            $fullHourTime = sprintf("%02d:%02d", $date->getHour(), $date->getMinute());
        } else {
            $fullHourTime = ' ';
        }        

        $time = sprintf("%04d-%02d-%02d %02d:%02d", $date->getYear(), $date->getMonth(), $date->getDay(), $date->getHour(), $date->getMinute());

        if(!empty($events)) {
            $ts = $date->getTimeStamp();
            $row = &$eventMap[$ts];
            $td = '';
            $td .= '' . "\t";
            foreach($row as $index => $col) {
                if($col === true) {
                    $td .= '' . "\t";
                    $td .= ''; // event running, managed by rowspan
                } else if(is_null($col)) {
                    $td .= ''; // event running, managed by colspan
                } else if($col === false) {
                    $td .= '' . "\t";
                    $td .= ' '; // an empty cell
                } else if(is_numeric($col)) {
                    $td .= '' . "\t";
                    $event = $events[$col]; // by ID

                    // $rows = (ceil($event->getEnd() / $tick) - ($ts / $tick));
                    $cols = count($row) - $index; // index starts at 0 --> min cols=1, max=count(...)
                    $rows = 1;
                    for($i=$ts; $i < $ts + ($tick * count($eventMap)); $i+=$tick) {
                        if(isset($eventMap[$i+$tick][$index]) && $eventMap[$i+$tick][$index] === true) {
                            $rows++;
                        } else {
                            break;
                        }
                    }

                    for($i=$ts; $i < $ts+($tick * $rows); $i+=$tick) {
                        if(!isset($eventMap[$i][$index+1]) || $eventMap[$i][$index+1] !== false) {
                            $cols = 1;
                            break;
                        }
                    }

                    if($cols > 1) {
                        for($i=$ts; $i < $ts+($tick * $rows); $i+=$tick) {
                            for($j=$index; $j < count($row); $j++) {
                                $eventMap[$i][$j] = null;
                            }
                        }
                        $row[$index] = $event->getId();
                        // Take the spacers into account
                        $cols = 2*$cols-1;
                    }
                    $td .= $this->renderEvent($event, $rows, $cols);
                }
                $td .= "\n";
            }
        } else {
            $td = '';
        }

        $o = '';
        $o .= '' . "\n";
        $o .= "\t" . '' . $fullHourTime .  '' . "\n";
        $o .= $td;
        $o .= '' . "\n";
        $this->output .= $o;
    }

    /**
     * Returns a day calendar string representation of an event
     * @param GregorianCalendarEvent $event
     * @param int $rows
     * @params int $cols
     * @return string
     */
    protected function renderEvent(GregorianCalendarEvent $event, $rows, $cols) {
        $td = '';
        $td .= (method_exists($event, 'render')) ? $event->render($this) : '';
        $td .= "";
        return $td;
    }
}
?>

 'there',
 *      'who' => 'me',
 *      'why' => 'because'
 *  );
 *
 * Then $event->where === 'there'.
 * Note that you should choose "PHP-variable-name-conform" array keys for this,
 * alternatively you can use the data getter: $event->getData("who") === "me".
 *
 * @package de.atwillys.sw.php.swLib
 * @author Stefan Wilhelm
 * @copyright Stefan Wilhelm, 2010
 * @license GPL
 * @version 1.0
 */
class GregorianCalendarEvent {

    /**
     * A unique identifier of the event
     * @var string
     */
    protected $id = '';

    /**
     * The name of the event
     * @var string
     */
    protected $name = 'New Event';

    /**
     * The timestamp when the event starts
     * @var IDate
     */
    protected $start = 0;

    /**
     * The timestamp when the event ends
     * @var IDate
     */
    protected $end = 0;

    /**
     * The type of event
     * @var string
     */
    protected $type = '';

    /**
     *
     * @var array
     */
    protected $data = array();

    /**
     * GregorianCalendarEvent constructor
     * @param string $name=''
     * @param mixed $start=null
     * @param mixed $end=null
     * @param array $data=array()
     * @param string $type=null
     * @param mixed $id=null
     */
    public function __construct($name='', $start=null, $end=null, array $data=array(), $type=null, $id=null) {
        if($start instanceof IDate) {
            $start = $start->getTimeStamp();
        } else if(empty($start)) {
            $start = time();
        } else if(!is_numeric($start)) {
            throw new Exception('GregorianCalendarEvent start time must be an integer timestamp');
        }

        if($end instanceof IDate) {
            $end = $end->getTimeStamp();
        } else if(empty($end)) {
            $end = $start + 3600;
        } else if(!is_numeric($end)) {
            throw new Exception('GregorianCalendarEvent end time must be an integer timestamp');
        }

        if($end <= $start) {
            throw new Exception('GregorianCalendarEvent end time must be later than the start time');
        }

        $this->start = $start;
        $this->end = $end;

        if(!empty($name)) $this->name = trim($name);
        if(!empty($id)) $this->id = $id;
        if(!empty($data)) $this->data = $data;
        if(!empty($type)) $this->type = trim($type); // implicit toString
    }

    /**
     * Returns a property if the correcponding getter (get<$ame>)exists OR the
     * key exsts in the data array. Returns null if none of both exists. Note
     * that values stored in the data array are inaccessible if a the key is
     * e.g. "from", "to", "name" etc.
     * @param string $name
     */
    public function __get($name) {
        if(method_exists($this, 'get' . $name)) {
            $name = 'get' . $name;
            return $this->$name();
        } else if(isset($this->data[$name])) {
            return $this->data[$name];
        } else {
            return null;
        }
    }

    /**
     * Sets a property if the correcponding setter (set<$ame>) exists. If no
     * setter is found, then the value will be stored in the data array. Note
     * that values stored in the data array are inaccessible if a the key is
     * e.g. "from", "to", "name" etc. The setter will be called instead.
     * @param string $name
     * @param mixed $value
     * @return void
     */
    public function __set($name,  $value) {
        if(method_exists($this, 'set' . $name)) {
            $name = 'set' . $name;
            $this->$name($value);
        } else {
            $this->data[$name] = $value;
        }
    }

    /**
     * String representation
     * @return string
     */
    public function  __toString() {
        return '['
            . strftime('%Y-%m-%d %H:%M:%S %Z', $this->start)
            . ' - '
            . strftime('%Y-%m-%d %H:%M:%S %Z', $this->end)
            . '] '
            . $this->name
            . ' {id="' . $this->id . '", type="'. $this->type
            . '", data=["' . implode('", "', $this->data) . '"]'
            . '}';
    }

    /**
     * Returns the id of the event
     * @return mixed
     */
    public function getId() {
        return $this->id;
    }

    /**
     * Returns the name of the event
     * @return string
     */
    public function getName() {
        return $this->name;
    }

    /**
     * Returns when the event starts
     * @return IDate
     */
    public function getStart() {
        return $this->start;
    }

    /**
     * Returns when the event ends
     * @return IDate
     */
    public function getEnd() {
        return $this->end;
    }

    /**
     * Returns the type of event
     * @return string
     */
    public function getType() {
        return $this->type;
    }

    /**
     * Returns the data array or a valued in the data array specified using
     * $key, null if not found
     * @return mixed
     */
    public function getData($key=null) {
        if(!empty($key)) {
            return isset($this->data[$key]) ? $this->data[$key] : null;
        } else {
            return $this->data;
        }
    }

    /**
     * Sets the id of the event
     * @param mixed $id
     */
    public function setId($id) {
        if(!is_scalar($id)) {
            throw new Exception('An calendar event ID cannot be an object or array');
        } else {
            $this->id = $id;
        }
    }

    /**
     * Sets the name of the event
     * @param string $name
     */
    public function setName($name) {
        $this->name = trim($name);
    }

    /**
     * Sets the timestamp when the event starts
     * @param int $from
     */
    public function setFrom($from) {
        if(is_numeric($from)) {
            $this->start = intval($from);
        } else if($from instanceof IDate) {
            $this->start = $from->getTimeStamp();
        } else {
            throw new Exception('"from"-data is no timestamp');
        }
    }

    /**
     * Sets when the event ends
     * @param int $to
     */
    public function setTo($to) {
        if(is_numeric($to)) {
            $this->end = intval($to);
        } else if($to instanceof IDate) {
            $this->end = $to->getTimeStamp();
        } else {
            throw new Exception('"to"-data is no timestamp');
        }
    }

    /**
     * Sets the event type
     * @param string $type
     */
    public function setType($type) {
        $this->type = trim(strtolower($type));
    }

    /**
     * Sets the custom/user data array
     * @param array $data
     */
    public function setData(array $data) {
        $this->data = $data;
    }
}
?>

CSS recommendation

/**
 * Common CSS
 * @author Stefan Wilhelm
 * @package de.atwillys.php.swlib.css.std
 */

body, abbr, acronym, address, area, b, base, basefont, big, blockquote, br, button,
caption, center, cite, code, col, colgroup, dd, del, del, dfn, dir, div, dl, dt, em,
fieldset, font, form, h1, h2, h3, h4, h5, hr, i, iframe, img, input, ins, isindex,
kbd, label, li, map, menu, object, ol, option, p, pre, s, samp, select, small, span,
strike, strong, sub, sup, table, tbody, td, textarea, tfoot, th, thead, title, tr,
tt, u, ul, var, a, a:link, a:hover, a:visited, hr, img, code, pre, tt, samp, input,
textarea, select, option {
    font-family: "Helvetica", "Verdana", monospace;
    background: transparent;
    margin: 0px 0px 0px 0px;
    padding: 0px 0px 0px 0px;
    text-decoration: none;
    color: #000000;
    font-size: 11pt;
    line-height: 13pt;
    border: none 0px;
}

body {
    padding:10px 10px 10px 10px;
}

h1 {
    font-size: 17pt;
}

h2 {
    font-size: 16pt;
}

h3 {
    font-size: 14pt;
}

h4, h5 {
    font-size: 11pt;
}

a:link, a:visited {
    font-weight: bold;
    color: #000099;
}

a:hover {
    color: #990000;
}

img {
    margin: 5px 5px 5px 5px;
}

hr {
    color:black;
    background-color:black;
    border:0px none;
    border-bottom:1px solid black;
    width:100%
}

code, pre, tt, samp {
    font-family: monospace;
    color:#000000;
}

form {
    margin:0px;
    padding:2px;
    border:0px none;
}

/**
 * CSS for Gregorian month calendars
 * @author Stefan Wilhelm
 * @package de.atwillys.php.swlib.cal
*/

table.gregorian-month-calendar {
    width: 245px;
    border-collapse: collapse;
    border-spacing: 0px;
}

table.gregorian-month-calendar caption {
    margin: 0px 0px 0px 0px;
    padding: 0px 0px 0px 0px;
    background: #bbbbbb;
    color: #111111;
    vertical-align: middle;
    text-align: center;
    font-size: 14pt;
    line-height: 18pt;
    margin-bottom: 2px;
    background-color: #eeeeee;
    border: ridge 1px #666666;
    border-radius: 3px;
    -webkit-border-radius: 3px;
    -moz-border-radius: 3px;
}

table.gregorian-month-calendar caption a,
table.gregorian-month-calendar caption a:link,
table.gregorian-month-calendar caption a:visited {
    display:block;
    margin: 0px 0px 0px 0px;
    padding: 0px 0px 0px 0px;
    background: #bbbbbb;
    color: #111111;
    vertical-align: middle;
    text-align: center;
    font-size: 14pt;
    line-height: 18pt;
    background-color: #eeeeee;
    border: ridge 1px #666666;
    border-radius: 3px;
}

table.gregorian-month-calendar caption a.prev,
table.gregorian-month-calendar caption a.prev:link,
table.gregorian-month-calendar caption a.prev:visited {
    margin: 0px 10px 0px 10px;
    border: none;
    width: 10px;
    float: left;
    background: transparent;
    background-image: url("prev.png");
    background-repeat: no-repeat;
    background-position: center center;
}

table.gregorian-month-calendar caption a.next,
table.gregorian-month-calendar caption a.next:link,
table.gregorian-month-calendar caption a.next:visited {
    margin: 0px 10px 0px 10px;
    border: none;
    width: 10px;
    float: right;
    background: transparent;
    background-image: url("next.png");
    background-repeat: no-repeat;
    background-position: center center;
}

table.gregorian-month-calendar caption a.title,
table.gregorian-month-calendar caption a.title:link,
table.gregorian-month-calendar caption a.title:visited {
    width:auto;
}

table.gregorian-month-calendar th,
table.gregorian-month-calendar td {
    vertical-align: middle;
    text-align: center;
}

table.gregorian-month-calendar th a,
table.gregorian-month-calendar th a:link,
table.gregorian-month-calendar th a:visited,
table.gregorian-month-calendar th a:hover,
table.gregorian-month-calendar td a,
table.gregorian-month-calendar td a:link,
table.gregorian-month-calendar td a:visited,
table.gregorian-month-calendar td a:hover {
    display: block;
    width: 35px;
    height: 20px;
    vertical-align: middle;
    text-align: center;
    border: ridge 1px #666666;
    border-radius: 3px;
    -webkit-border-radius: 3px;
    -moz-border-radius: 3px;
}

table.gregorian-month-calendar th a,
table.gregorian-month-calendar th a:link,
table.gregorian-month-calendar th a:visited {
    padding: 2px 2px 2px 2px;
    background-color: #979887;
    margin-bottom: 2px;
}

table.gregorian-month-calendar td a,
table.gregorian-month-calendar td a:link,
table.gregorian-month-calendar td a:visited,
table.gregorian-month-calendar td a:hover {
    color: #111111;
    padding: 7px 2px 7px 2px;
    background-color: #bbbbbb;
}

table.gregorian-month-calendar td.passed a,
table.gregorian-month-calendar td.passed a:link,
table.gregorian-month-calendar td.passed a:visited {
    color: #555555;
}

table.gregorian-month-calendar td.padding a,
table.gregorian-month-calendar td.padding a:link,
table.gregorian-month-calendar td.padding a:visited {
    color: #bbbbbb;
    background-color: #eeeeee;
    border: ridge 1px #bbbbbb;
}

table.gregorian-month-calendar td.sat a,
table.gregorian-month-calendar td.sat a:link,
table.gregorian-month-calendar td.sat a:visited,
table.gregorian-month-calendar td.sun a,
table.gregorian-month-calendar td.sun a:link,
table.gregorian-month-calendar td.sun a:visited {
    background-color: #eeee66;
}

table.gregorian-month-calendar td.today a,
table.gregorian-month-calendar td.today a:link,
table.gregorian-month-calendar td.today a:visited {
    color: #ff0077;
}

table.gregorian-month-calendar td.selected a,
table.gregorian-month-calendar td.selected a:link,
table.gregorian-month-calendar td.selected a:visited {
    color: #222222;
    background-color: #66ee66;
    border: ridge 1px #666666;
}

table.gregorian-month-calendar td.has-events a,
table.gregorian-month-calendar td.has-events a:link,
table.gregorian-month-calendar td.has-events a:visited {
    background-image: url('has-events.png');
    background-repeat: no-repeat;
}

table.gregorian-month-calendar td a:hover,
table.gregorian-month-calendar td.selected a:hover,
table.gregorian-month-calendar td.has-events a:hover,
table.gregorian-month-calendar td.sat a:hover,
table.gregorian-month-calendar td.sun a:hover,
table.gregorian-month-calendar td.padding a:hover {
    color: #222222;
    background-color: #44cc44;
    border: ridge 1px #666666;
}

/**
 * CSS for Gregorian day calendars
 * @author Stefan Wilhelm
 * @package de.atwillys.php.swlib.cal
*/

table.gregorian-day-calendar {
    width: 100%;
    border-collapse: collapse;
    border-spacing: 0px;
}

table.gregorian-day-calendar caption {
    margin: 0px 0px 0px 0px;
    padding: 0px 0px 0px 0px;
    width: 99.9%;
    background: #eeeeee;
    color: #111111;
    vertical-align: middle;
    text-align: center;
    font-size: 14pt;
    line-height: 18pt;
    margin-bottom: 2px;
    border: ridge 1px #666666;
    border-radius: 3px;
    -webkit-border-radius: 3px;
    -moz-border-radius: 3px;
}

table.gregorian-day-calendar td {
    vertical-align: middle;
    padding: 0px 0px 0px 0px;
    text-align: left;
    border-top: dotted 1px #aaaaaa;
    border-bottom: dotted 1px #aaaaaa;
}

table.gregorian-day-calendar td.time {
    text-align: right;
    width: 80px;
    height: 20px;
}

table.gregorian-day-calendar tr.full-hour td.time {
    border-top: solid 1px #000000;
}

table.gregorian-day-calendar tr.padding {
    background-color: #eeeeee;
}

table.gregorian-day-calendar tr td.space {
    width: 4px;
}

table.gregorian-day-calendar tr td.data.event {
    padding: 4px 4px 4px 4px;
    vertical-align: top;
    border: 0px;
    border-collapse: collapse;
    background: #aaaaff;
    box-shadow:0 0 1px #000000;
    -webkit-box-shadow:0 0 1px #000000;
    -moz-box-shadow:0 0 1px #000000;
    border-radius: 10px;
    -webkit-border-radius: 10px;
    -moz-border-radius: 10px;
}

table.gregorian-day-calendar tr td.event div {
}

This Article is also available in Deutsch.

Growl UDP notification class

stfwi — Sat, 10 Jul 2010 13:24:17 +0000

Growl is a well known, powerful tool for the Mac (and now for other platforms as well), which displays small notification messages on your screen. Any program can register itself as a source of messages and then send notifications. Additionally, Growl can listen to a UDP port for the same purpose. The PHP class in this article uses this remote messaging protocol for notifying local or remote computers. The Growl protocol is not really complex, but here a short overview how “UDP-Growling” works:

Growl wants to know which program sent an incoming notification and which type of notification was received (a warning, error, new email, new Skype message …). This allows you to set up what to do with these messages in your Growl configuration panel.
Hence, there are two major message types in the UDP protocol: Registration and Notification. The registration packets register a new application and specify which types of notification are sent from this application. The notification messages contain the messages that you want to display.
The notification messages contain title, description, priority, and if they are sticky (keep being displayed until you click them)
For security reasons, Growl has a password protection for UDP remote registrations

Risk a glance at the sample source code so see how it works:

Sample source code

';

// Sets defaults
GrowlNotifier::config(array(
    'server' => '127.0.0.1',            // default server ip (this computer)
    'password' => '',                   // default password
    'application' => 'PhpGrowler',      // default application identifier
    'register' => true,                 // send registrations?
    'notifications' => array(           // defaule registered notifications
        'message','warning', 'error',   // default enabled notifications
        'disabled notify' => false,     // explicity disabled notification
        'enabled notify' => 'true'      // explicity enabled notification
    )
));

// Instance using default config
$growl = new GrowlNotifier();
$growl->notify('Hello Growl', "This is a message for you");

// Instance using config specified in constructor
$growl = new GrowlNotifier('localhost', '');
$growl->notify('Hello localhost', "This is another message for you");

print '';
?>

Output

To see the output of this example “out of the box”, go to your Growl settings pane under “Network”, and tick the check boxes “Listen for incoming notifications” and “Allow remote application registration”. Leave the password field blank. Well – I assume that Growl is installed and your Apache server is running on your local machine. Probably a system message “Allow incoming network transfers for GrowlHelper” will be displayed – the best is to say “always allow”.

Class source code

 '127.0.0.1',            // default server ip
        'password' => '',                   // default password
        'application' => 'PhpGrowler',      // default application identifier
        'register' => true,                 // send registrations?
        'notifications' => array(           // defaule registered notifications
            'message','warning', 'error',   // default enabled notifications
            //'something else' => false     // disabled notification
        )
    );

    /**
     * The version of the protocol
     * @const int
     */
    const PROTOCOL_VERSION = 1;

    /**
     * Packacke type registration
     * @const int
     */
    const TYPE_REGISTRATION = 0;

    /**
     * Packacke type notification
     * @const int
     */
    const TYPE_NOTIFICATION = 1;

    /**
     * Growl UDP port
     * @const int
     */
    const UDP_PORT = 9887;

    /**
     * The Growl server/computer IP address
     * @var string
     */
    private $server = '127.0.0.1';

    /**
     * The Growl server/computer password
     * @var string
     */
    private $password = '';

    /**
     * Application, which is sent to identify the message source
     * @var string
     */
    private $application = 'PhpGrowler';

    /**
     * Available notification types
     * @var array
     */
    private $registeredNotifications = array('message');

    /**
     * Helper to achieve that the registration is only sent once.
     * @var bool
     */
    private $hasRegistered = null;

    /**
     * Class configuration. Sets the specified config settings (merges
     * with the existing). Returns the actual configuration after the
     * new array has been merged to the defaults/previous settings.
     * @param array $config
     * @return array
     */
    public static final function config($config=array()) {
        if(!is_array($config)) {
            throw new Exception('GrowlNotifier config is no array');
        } else {
            self::$config = array_merge(self::$config, $config);
        }
        return self::$config;
    }

    /**
     * Sends an UDP application registration package to the specified growl
     * server/computer. The notifications array can be either associative
     * (key is the notification name, value is a boolean value that describes
     * that the notification is enabled) or numerical indexed (key is a number,
     * value is the notification, enabled by default true). $server is the IP
     * address of the server, $password the password of the server, $application
     * the name or slug or any string identifier of the application.
     * @param string $server
     * @param string $password
     * @param string $application
     * @param array $notifications
     */
    private static function sendUdpRegistration($server, $password, $application, array $notifications) {
        $application = utf8_encode($application);
        $encoded = $defaults = '';
        $ne = $nd = 0;
        foreach($notifications as $notification => $enabled) {
            $enabled = (bool) $enabled;
            $notification = utf8_encode(trim($notification));
            $encoded .= pack('n', strlen($notification)) . $notification;
            $ne++;
            if($enabled !== false) { $defaults .= pack('c', $ne-1); $nd++; }
        }
        $data = pack(
            'c2nc2', self::PROTOCOL_VERSION, self::TYPE_REGISTRATION,
            strlen($application), $ne, $nd
        ) . $application . $encoded . $defaults;
        $data .= pack('H32', md5($data . trim($password)));
        $sock = @socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
        if($sock == false) {
            throw new Exception('Sending registration failed: ' . socket_strerror(socket_last_error()));
        }
        if(@socket_sendto($sock, $data, strlen($data), MSG_EOF, $server, self::UDP_PORT) < 0) {
            @socket_close($sock);
            throw new Exception('Sending registration failed: ' . socket_strerror(socket_last_error()));
        }
        @socket_close($sock);
    }

    /**
     * Sends an UDP application notification package to the specified growl
     * server/computer. $server is the IP address of the server, $password
     * the password of the server, $application the name or slug or any string
     * identifier of the application, $notification one of the registered
     * notification identifiers - rest of parameters are self explaining.
     * @param string $server
     * @param string $password
     * @param string $application
     * @param string $notification
     * @param string $title=''
     * @param string $description=''
     * @param int $priority=0
     * @param bool $sticky=false
     */
    private static function sendUdpNotification($server, $password, $application, $notification, $title='',
                                                $description='', $priority=0, $sticky=false) {
        $application = utf8_encode(trim($application));
        $notification = utf8_encode(trim($notification));
        $description = utf8_encode(trim($description));
        $title = utf8_encode(trim($title));
        $priority = intval($priority);
        $data = pack('c2n5', self::PROTOCOL_VERSION, self::TYPE_NOTIFICATION,
            (2*(intval($priority) & 7)) | (intval($priority) < 0 ? 8 : 0) | ($sticky==true ? 256 : 0),
            strlen($notification), strlen($title), strlen($description), strlen($application)
        ) . $notification . $title . $description . $application;
        $data .= pack('H32', md5($data . trim($password)));
        $sock = @socket_create(AF_INET, SOCK_DGRAM, SOL_UDP);
        if($sock == false) {
            throw new Exception('Sending notification failed: ' . socket_strerror(socket_last_error()));
        }
        if(@socket_sendto($sock, $data, strlen($data), MSG_EOF, $server, self::UDP_PORT) < 0) {
            @socket_close($sock);
            throw new Exception('Sending notification failed: ' . socket_strerror(socket_last_error()));
        }
        @socket_close($sock);
    }

    /**
     * Constructor
     * @param string $server
     * @param string $password
     * @param array $registeredNotifications
     */
    public function __construct($server=null, $password=null, $application=null, $registeredNotifications=array()) {
        $this->setServer(trim($server) != '' ? $server : self::$config['server']);
        $this->setPassword(!empty($password) ? $password : self::$config['password']);
        $this->setApplication(trim($application) != '' ? $application : self::$config['application']);
        $this->setRegisteredNotifications(!empty($registeredNotifications) ? $registeredNotifications : self::$config['notifications']);
    }

    /**
     * Returns the IP address of the server to send registrations/notifications to.
     * @return string
     */
    public function getServer() {
        return $this->server;
    }

    /**
     * Sets the new server IP address
     * @param string $server
     */
    public function setServer($server) {
        $this->server = trim($server);
    }

    /**
     * Returns the password of the server to send registrations/notifications to.
     * @return string
     */
    public function getPassword() {
        return $this->password;
    }

    /**
     * Sets the new server password
     * @param string $password
     */
    public function setPassword($password) {
        $this->password = strval($password);
    }

    /**
     * Returns the application identifier, under which the messages are send.
     * @return string
     */
    public function getApplication() {
        return $this->application;
    }

    /**
     * Sets the new application identified, under which messages are send.
     * @param strig $application
     */
    public function setApplication($application) {
        $this->application = trim($application);
    }

    /**
     * Returns an assoc. array containing the registered notification types
     * (or the notifications to register). Keys a the notification names, values
     * are the enabled-status (bool).
     * @return array
     */
    public function getRegisteredNotifications() {
        return $this->registeredNotifications;
    }

    /**
     * Sets the new registerd notifications..
     * Wants an assoc. array containing the registered notification types
     * (or the notifications to register). Keys a the notification names, values
     * are the enabled-status (bool). The first registered notification is the
     * default one, which will be used if the corresponding argumrnt in notify()
     * is empty.
     * @param array $notifications
     */
    public function setRegisteredNotifications($notifications) {
        if(!is_array($notifications)) {
            throw new Exception('Notifications to register must be passed as array');
        } else if(empty($notifications)) {
            throw new Exception('No notifications defined to register');
        } else {
            $sanatizedNotifications = array();
            foreach($notifications as $notification => $enabled) {
                if(is_numeric($notification) && !is_bool($enabled)) {
                    $sanatizedNotifications[trim($enabled)] = true;
                } else {
                    $sanatizedNotifications[trim($notification)] = $enabled;
                }
            }
            $this->registeredNotifications = $sanatizedNotifications;
        }
    }

    /**
     * Sends a notification to the configured server.
     * @param string $notification
     * @param string $title
     * @param string $description=''
     * @param int $priority=0
     * @param bool $sticky=false
     */
    public function notify($title, $description='', $notification=null, $priority=0, $sticky=false) {
        // Send the registration only once
        if($this->hasRegistered !== false) {
            if(is_null($this->hasRegistered)) {
                $this->hasRegistered = self::$config['register'] ? true : false;
            }
            if($this->hasRegistered) {
                try {
                    self::sendUdpRegistration($this->getServer(), $this->getPassword(),
                            $this->getApplication(), $this->getRegisteredNotifications());
                    $this->hasRegistered = true;
                } catch(Exception $e) {
                    throw new Exception('Notification registration failed:' . $e->getMessage());
                }
            }
        }

        // Default is the first registered one ...
        if(empty($notification)) {
            foreach($this->getRegisteredNotifications() as $notification => $enabled) {
                if($enabled) break;
            }
        }

        // send the notification
        self::sendUdpNotification($this->getServer(), $this->getPassword(), $this->getApplication(),
                $notification, $title, $description, $priority, $sticky);
    }

}
?>

References

Growl Network Protocol Format

This Article is also available in Deutsch.

Framework base class: swlib

stfwi — Tue, 06 Jul 2010 22:47:49 +0000

The basic tasks that I want to have included in my scripts are collected in one frame library, the swlib. This class manages the autoloading for me and initializes error exception handling, output buffering, tracer and session. Other functions are the import/export of persistent variables, as well as a safe script shutdown (means that is registers static shutdown functions that cause to print the output and trace output even if the script was stopped after an error/uncaught exception or the die() function – however, if the PHP parser aborts, then there is no way of catching this with no shutdown handling). The class requires the (on this page published) classes EException, OutputBuffer, Tracer and Session.

Sample source code

 true,
    // use session, automatically start (this is default)
    'use_session' => true,
    // path to library var directory, we use an one one
    // The var path must be writable for the server, it is NOT the
    // directory "/var" on Unix-Like systems, but a directory to serialize
    // "variables" in.
    'var_path' => dirname(__FILE__) . '/var',
    // path to library tmp directory, we use an one one
    // The tmp path must be writable for the server
    'tmp_path' => dirname(__FILE__) . '/tmp',
    // extensions for variable export/import files (this is default)
    'var_extension' => '.tmp',
    // The include paths to search for classes
    'include_paths' => array(
        dirname(__FILE__) . '/class'
    )
));

print '';

// Print some information
print "Lib path = " . swlib::getLibPath() . "\n";
print "Tmp path = " . swlib::getTmpPath() . "\n";
print "Var path = " . swlib::getVarPath() . "\n";
print "\n";

print "Has class 'Css' = " . (swlib::hasClass('Css') ? 'yes' : 'no') . "\n";
print "Has class 'Csss' = " . (swlib::hasClass('Csss') ? 'yes' : 'no') . "\n";

// We add an include path after we configured the library. This will here throw
// an exception because the directory "class2" does not exist:
try {
    swlib::addIncludePath(dirname(__FILE__) . '/class2');
} catch(Exception $e) {
    print "Include failed: " . $e->getMessage() . "\n";
}

print "\n";

// We update the classes manually here, but this is normally not necessary,
// as the library updates the classes if a class is not found. If so, the
// an Exception will be thrown as well (only one time).
// In the very end, a file is created in the var path, which is read at startup
// and contains an associative array with the class names as key and the file
// path as value. Autoloading is well defined then and redundancies can be
// detected.
try {
    swlib::updateAutoloadClasses();
} catch(Exception $e) {
    print "Could not update classes: Exceptoin" . $e->getMessage();
    Tracer::traceException($e);
}

// Print the array with autoloadable classes, class names are the keys, class
// file paths are the values.
print "Autoloadable classes = " . print_r(swlib::getAutoloadableClasses(), true) . "\n";

// Autoload some classes
$a = new A();
$b = new B();
$c = new C();

// This method shows the classes that were autoloaded by the swlib. This
// Does not include the EException, Tracer, OutputBuffer, Session, swlib
// because these classes are treated as library core.
print "Autoloaded classes = " . print_r(swlib::getAutoloadedClasses(), true) . "\n";

// Let's import/export a variable to a file in the var path. The file will be
// named "a.tmp" if it is exported.
try {
    print "Already saved dice = " . print_r(swlib::importVariable('dice'), true) . "\n";
} catch(Exception $e) {
    // We will get this exceotion the first time we call the script, because
    // the variable was not exported yet, the message is:
    // "Import file for "dice" is not readable or does not exist".
    print "" . $e->getMessage();
}

// And here's the export to "a.tmp":
swlib::exportVariable('dice', array(
    'D6'  => rand(1, 6),
    'D20' => rand(1, 20)
));

print '';
?>

Output

Lib path = /.../
Tmp path = /.../tmp
Var path = /.../var

Has class 'Css' = yes
Has class 'Csss' = no
Include failed: Directory to add to class path does not exist:/.../class2

Autoloadable classes = Array
(
    [arrayfilter] => /.../lib/ArrayFilter.class.php
    [cache] => /.../lib/Cache.class.php
    1 => /.../lib/Css.class.php
    [eexception] => /.../lib/EException.class.php
    [emailcontact] => /.../lib/EMailContact.class.php
    [filesystem] => /.../lib/FileSystem.class.php
    [httpauthentification] => /.../lib/HttpAuthentification.class.php
    [httprequest] => /.../swlib/lib/HttpRequest.class.php
    [iemailcontact] => /.../lib/IEMailContact.class.php
    [inifile] => /.../lib/IniFile.class.php
    [latexrenderer] => /.../lib/LaTexRenderer.class.php
    [mailer] => /.../lib/Mailer.class.php
    [math] => /.../lib/Math.class.php
    [mathexception] => /.../lib/MathException.class.php
    [menu] => /.../lib/Menu.class.php
    [menurenderer] => /.../lib/MenuRenderer.class.php
    [menutreerenderer] => /.../lib/MenuTreeRenderer.class.php
    [mysql] => /.../lib/MySql.class.php
    [mysqladministration] => /.../lib/MySqlAdministration.class.php
    [mysqlexception] => /.../lib/MySqlException.class.php
    [outputbuffer] => /.../lib/OutputBuffer.class.php
    [phpcode] => /.../lib/PhpCode.class.php
    [resourcefile] => /.../lib/ResourceFile.class.php
    [session] => /.../lib/Session.class.php
    [shellprocess] => /.../lib/ShellProcess.class.php
    [swlib] => /.../lib/swlib.class.php
    [tracer] => /.../lib/Tracer.class.php
    [unittest] => /.../lib/UnitTest.class.php
    [utcdate] => /.../lib/UtcDate.class.php
    [xmlconverter] => /.../lib/XmlConverter.class.php
    [zipexception] => /.../lib/ZipException.class.php
    [zipfile] => /.../lib/ZipFile.class.php
    [a] => /.../class/A.class.php
    [b] => /.../class/B.class.php
    1 => /.../class/C.class.php
)

Autoloaded classes = Array
(
    [0] => A
    [1] => B
    [2] => C
)

Already saved dice = Array
(
    [D6] => 6
    [D20] => 5
)

Class source code

 true,           // use output buffering, automatically start
        'use_session' => true,      // use session, automatically start
        'var_path' => '',           // path to library var directory
        'tmp_path' => '',           // path to library tmp directory
        'var_extension' => '.tmp',  // extensions for variable export/import files
        'include_paths' => array(), // The include paths to search for classes
        'rm_gpc_quotes' => true,    // Removes magic_quotes_gpc stuff
        'rm_gpc_globals' => true,   // Removes old HTTP_GET_VARS and the like
        'tracer' => array(),        // Tracer configuration
        'eexception' => array(),    // EException configuration
    );

    /**
     * Own instance
     * @var swlib
     */
    private static $instance = null;

    /**
     * Registered autoloadable classes
     * @var array
     */
    private static $autoloadableClasses = array();

    /**
     * Loaded autoloadable classes
     * @var array
     */
    private static $autoloadedClasses = array();

    /**
     * Library configuration. Sets the specified config settings (merges
     * with the existing). Returns the actual configuration after the
     * new array has been merged to the defaults/previous settings.
     * @param array $config
     * @return array
     */
    public static final function config($config=array()) {
        if(!is_array($config)) {
            throw new Exception('swlib config is no array');
        } else {
            self::$config = array_merge(self::$config, $config);
        }
        return self::$config;
    }

    /**
     * Library startup, optional with setting the config. See the private
     * $self::config variable for information about whar can be configured.
     * @param array $config
     * @return void
     */
    public static final function start($config=array()) {
        if(is_null(self::$instance) && !empty($config)) {
            self::config($config);
        }
        self::instance();
    }

    /**
     * Stops the library and flushes the output
     * buffers. Do not call this method, it will
     * be automatically called when the script
     * stops. (using register_shutdown_function())
     */
    public static final function stop() {
       self::$instance = null;
    }

    /**
     * Library singleton instance
     * @return SwLib
     */
    public static final function instance() {
        if(is_null(self::$instance)) {
            self::$instance = new self();
            Tracer::start(self::$config['tracer']);
        }
        return self::$instance;
    }

    /**
     * Returns the sw library path
     * @return string
     */
    public static final function getLibPath() {
        return dirname(__FILE__);
    }

    /**
     * Returns the var path
     * @return string
     */
    public static final function getVarPath() {
        return self::$config['var_path'];
    }

    /**
     * Returns the tmp path
     * @return string
     */
    public static final function getTmpPath() {
        return self::$config['tmp_path'];
    }

    /**
     * Returns registered autoload classes.
     * @return array
     */
    public static final function getAutoloadableClasses() {
        return self::$autoloadableClasses;
    }

    /**
     * Returns actual loaded autoload classes.
     * @return array
     */
    public static final function getAutoloadedClasses() {
        return self::$autoloadedClasses;
    }

    /**
     * Returns if a class exists or can be autoloaded
     * via the swlib.
     * @param string $class
     * @return bool
     */
    public static final function hasClass($class) {
        return isset(self::$autoloadableClasses[strtolower($class)]);
    }

    /**
     * Adds a directory that is recursivly searched for *.class.php files
     * in order to add the class files to the autoloaded classes
     * index. The ignore pattern is a wildcard pattern (for more pattern
     * separate with ";", e.g.
     * swlib::addIncludePath(
     *      $_SERVER['DOCUMENT_ROOT'] . '/mypath',
     *      'cache;var;tmp*;session*'
     * );
     * @param string $directory
     * @param string $ignore
     */
    public static function addIncludePath($directory, $ignore='') {
        if(!is_dir($directory)) {
            throw new Exception('Directory to add to class path does not exist:' . $directory);
        } else {
            self::$config['include_paths'][$directory] = array(
                'directory' => $directory,
                'ignore' => $ignore
            );
        }
    }

    /**
     * Imports a variable value using eval() a loaded file
     * in the var_path. Throws exception if import fails.
     * @param string $name
     * @return mixed
     */
    public static final function importVariable($name) {
        $file = self::getVarPath() . '/' . strtolower(trim($name)) . self::$config['var_extension'];
        $content = @file_get_contents($file);
        if($content === false) {
            if(!is_file($file)) {
                throw new Exception('Variable import file for "' . $name . '" does not exist');
            } if(!is_readable($file)) {
                throw new Exception('Variable import file for "' . $name . '" is not readable');
            } else {
                throw new Exception('Failed to get file contents for variable ' . $name);
            }
        } else if(strlen($content) == 0) {
            return null;
        } else {
            return eval('return ' . $content . ';');
        }
    }

    /**
     * Exports a variable value using var_export() a loaded file
     * in the var_path. Throws exception if export fails.
     * @param string $name
     * @param mixed $value
     * @return void
     */
    public static final function exportVariable($name, $value) {
        $file = self::getVarPath() . '/' . strtolower(trim($name)) . self::$config['var_extension'];
        if(@file_put_contents($file, var_export($value, true)) === false) {
            Tracer::trace('Warning: Failed to export variable ("' . $name . '" to file "' . $file . '")');
            if(!is_dir(self::getVarPath())) {
                throw new Exception('Swlib "var" path does not exist');
            } else if(!is_writable(self::getVarPath())) {
                throw new Exception('Swlib "var" path does not writable');
            } else if(is_dir($file)) {
                throw new Exception('Swlib Failed to write file in var path: ' . basename($file) . ' is already an existing directory');
            } else if(!is_file($file)) {
                throw new Exception('Swlib Failed to write file in var path: ' . basename($file));
            } else {
                throw new Exception('Swlib Failed to write file in var path: ' . basename($file) . '. Probably the file is locked at the moment');
            }
        }
    }

    /**
     * Autoloads a class
     * @param string $class
     */
    public static final function autoload($class) {
        $class = trim($class);
        if(!class_exists($class)) {
            $file = strtolower($class);

            if(!isset(self::$autoloadableClasses[$file])) {
                Tracer::trace('CLASS "' . $class . '" NOT FOUND, UPDATING CLASS INDEX ...');
                Tracer::backtrace();
                self::updateAutoloadClasses();
            }

            if(isset(self::$autoloadableClasses[$file])) {
                $file = self::$autoloadableClasses[$file];

                if(!is_readable($file)) {
                    if(!is_file($file)) {
                        self::updateAutoloadClasses();
                    }
                    throw new Exception("Failed to read class file: \"$file\" (not readable or does not exist)");
                } else {
                    try {
                        include_once $file;
                    } catch(Exception $e) {
                        Tracer::traceException($e);
                        Tracer::trace("Exception in class file '$file'");
                        throw $e;
                    }
                    self::$autoloadedClasses[] = $class;
                }
            } else {
                Tracer::trace('CLASS TO AUTOLOAD NOT FOUND: ' . $class);
                throw new Exception('Class not found: ' . $class);
            }
        } else {
            Tracer::trace('Class ' . $class . ' already included.');
        }
    }

    /**
     * Refreshes the library variable settings list of classes
     * for autoload
     * @return bool success
     */
    public static final function updateAutoloadClasses() {
        include_once('FileSystem.class.php');
        $classes = $files = $duplicates = array();
        $files = FileSystem::find(dirname(__FILE__), '*.class.php');

        if(!is_array(self::$config['include_paths'])) {
            throw new Exception('include_paths is not configured');
        }

        foreach(self::$config['include_paths'] as $acp) {
            if(is_array($acp)) {
                if(isset($acp['directory'])) {
                    $dir = $acp['directory'];
                }
                if(isset($acp['ignore'])) {
                    $ignore = $acp['ignore'];
                }
            } else {
                $dir = $acp;
                $ignore = '';
            }
            if(is_dir($dir)) {
                $files = array_merge($files, FileSystem::find($dir, '*.class.php', $ignore));
            } else {
                Tracer::trace('cannot register as class path, dir does not exist:' . $dir);
            }
        }

        foreach($files as $file) {
            $class = strtolower(basename($file, '.class.php'));
            if(isset($classes[$class]) && $classes[$class] != $file) {
                $duplicates[] = $file;
            } else {
                $classes[$class] = $file;
            }
        }

        // Throw exeption if fails
        self::exportVariable('autoload_classes', $classes);

        if(count($duplicates) > 0) {
            $duplicates = implode(', ', $duplicates);
            throw new Exception('Duplicate classes detected:' . $duplicates);
        }
        self::$autoloadableClasses = $classes;
        Tracer::trace_r(self::$autoloadableClasses, 'New autoload classes:');
        return true;
    }

    /**
     * Removes the GPC magic quotes, can remove deprecated HTTP_GET_VARS etc.
     * Performs this only once.
     * @param bool $removeHTTP_something=true
     */
    private static function compensateGpcMagicQuotes($removeHTTP_something=true) {
        if($removeHTTP_something) {
            foreach(array(
                'HTTP_ENV_VARS','HTTP_POST_VARS', 'HTTP_GET_VARS', 'HTTP_COOKIE_VARS',
                'HTTP_SERVER_VARS', 'HTTP_POST_FILES', 'HTTP_SESSION_VARS'
            ) as $var) {
                if(isset($GLOBALS[$var])) unset($GLOBALS[$var]);
            }
        }
        if(function_exists('get_magic_quotes_gpc') && get_magic_quotes_gpc()) {
            if(!function_exists('stripslashes_r')) {
                function stripslashes_r($v)  {
                    if(!is_array($v)) return isset($v) ? stripslashes($v) : null;
                    $a = array();
                    foreach($v as $k => $t) $a[stripslashes($k)] = stripslashes_r($t);
                    return $a;
                }
            }
            $_GET = stripslashes_r($_GET);
            $_POST = stripslashes_r($_POST);
            $_COOKIE = stripslashes_r($_COOKIE);
            $_FILES = stripslashes_r($_FILES);
            $_REQUEST = stripslashes_r($_REQUEST);
            if(!$removeHTTP_something) {
                if(isset($HTTP_GET_VARS)) $HTTP_GET_VARS = &$_GET;
                if(isset($HTTP_POST_VARS)) $HTTP_POST_VARS = &$_POST;
                if(isset($HTTP_COOKIE_VARS)) $HTTP_COOKIE_VARS = &$_COOKIE;
                if(isset($HTTP_POST_FILES)) $HTTP_POST_FILES = &$_FILES;
                if(isset($HTTP_REQUEST_VARS)) $HTTP_REQUEST_VARS = &$_REQUEST;
            }
        }
    }

    /**
     * Checks a (class Versioning compatible) HTTP reporitory for new versions
     * of the library. Default repository is atwilys.de
     * @param string $url
     * @param bool $returnDetails=false
     */
    public static final function checkForUpdates($url='http://www.atwillys.de/repository/swlib', $returnDetails=false) {
        try {
            $r = Versioning::checkModuleVersion('swlib', dirname(__FILE__), $url);
            return $returnDetails ? $r : $r['text'];
        } catch(Exception $e) {
            return "Version check failed due to exception: " . $e->getMessage();
        }
    }

    /**
     * Main library constructor
     */
    private final function __construct() {
        spl_autoload_register(array(__CLASS__, 'autoload'));
        register_shutdown_function(array(__CLASS__, "stop"), "inside");
        if(self::$config['var_path'] == '') self::$config['var_path'] = sys_get_temp_dir();
        if(self::$config['tmp_path'] == '') self::$config['tmp_path'] = sys_get_temp_dir();

        if(!is_writable(self::$config['var_path']) || !is_writable(self::$config['tmp_path'])) {
            Tracer::disable();
            OutputBuffer::purge();
            EException::enable(false);
            header('x', true, 500);
            die('Internal Server Error: swlib: var or tmp path is not writable');
        }

        try {
            self::$autoloadableClasses = self::importVariable('autoload_classes');
        } catch(Exception $e) {
            self::updateAutoloadClasses();
        }
        if(self::$config['use_ob']) OutputBuffer::start();
        if(self::$config['use_session']) Session::start();
        EException::config(self::$config['eexception']);
        EException::enable();
        if(self::$config['rm_gpc_quotes']) self::compensateGpcMagicQuotes(self::$config['rm_gpc_globals']);
    }

    /**
     * Main library cleanup, this method is even called on uncaught error or die();
     */
    public final function __destruct() {
        OutputBuffer::abort();
        Tracer::stop();
    }
}
?>

This Article is also available in Deutsch.

Shell execution management class

stfwi — Mon, 05 Jul 2010 21:07:47 +0000

Shell processes are normally executed using the functions exec, shell_exec, system etc – depending on which return or output is desired. proc_open and Co have the advantage that every output can be fetched: exit code, standard output (stdout) and error output (stderr). All this is managed by the ShellProcess class. You can run programs, fetch the outputs just-in-time via inherited callbacks, and send text input (stdin) to the process. The script can stop the process if the browser connection is closed.

Sample source code

';

// We overload on methods of the the ShellProcess class.
// These are used like event methods. In the example, we add the
// fetched text to variables and support methods to get these variables.
// I think you don't need no further description ...
class MyShellProcess extends ShellProcess {

    private $stdout = '';
    private $stderr = '';

    protected function onStdErr($text) {
        $this->stderr .= $text;
    }

    protected function onStdOut($text) {
        $this->stdout .= $text;
    }

    protected function onProcessStarted() {
        $this->stdout .= "[Process started]\n\n";
    }

    protected function onProcessStopped() {
        $this->stdout .= "\n\n[Process stopped]\n";
    }

    public function getOutput() {
        return $this->stdout;
    }

    public function getErrorOutput() {
        return $this->stderr;
    }
}

try {
    // Ok, lets run something:
    $sh = new MyShellProcess('ls -lsia');

    // You can set a timeout
    $sh->setTimeout(10.0);

    // That's default - if the script times out or the connection is aborted,
    // then the child process will be terminated.
    $sh->setTerminateOnAbort(true);

    // You can change the command (no need to set the command in the constructor)
    $sh->setCommand('ls -lsia *');

    // And run ...
    $sh->run();

    // Handle output ...
    if($sh->getErrorOutput() == '' && $sh->getOutput() == '') {
        // We want to see if the script worked but just has no output
        print "THERE IS NO OUTPUT\n";
    } else {
        // Check if we have errors outputs...
        if($sh->getOutput() != '') {
            print "[STDOUT]\n" . $sh->getOutput() . "\n\n";
        }

        // Check if we have errors outputs...
        if($sh->getErrorOutput() != '') {
            print "[STDERR]\n" . $sh->getErrorOutput() . "\n\n";
        }
    }

} catch(Exception $e) {
    print "EXCEPTION: " . $e->getMessage() . "\n" . $e->getTraceAsString();
}

print '';
?>

Output

Well, that’s context dependent, but for me it was:

[STDOUT]
[Process started]

ArrayFilter.class.php
Cache.class.php
Css.class.php
EException.class.php
EMailContact.class.php
FileSystem.class.php
HttpAuthentification.class.php
HttpRequest.class.php
IEMailContact.class.php
IniFile.class.php
LaTexRenderer.class.php
Mailer.class.php
Math.class.php
MathException.class.php
Menu.class.php
MenuRenderer.class.php
MenuTreeRenderer.class.php
MySql.class.php
MySqlAdministration.class.php
MySqlException.class.php
OutputBuffer.class.php
PhpCode.class.php
ResourceFile.class.php
Session.class.php
ShellProcess.class.php
Tracer.class.php
UnitTest.class.php
UtcDate.class.php
XmlConverter.class.php
ZipException.class.php
ZipFile.class.php
index.php
swlib.class.php

latex:
cache
index.php

pdfindex:
PaperParser.class.php
cache
index.php

[Process stopped]

Class source code

command = trim($command);
    }

    /**
     * Destructor
     */
    public final function __destruct() {
        if(is_resource($this->hProcess)) {
            @proc_close($this->hProcess);
        }
        if(is_array($this->pipes) && !empty($this->pipes)) {
            if(is_resource($this->pipes[0])) @fclose($this->pipes[0]);
            if(is_resource($this->pipes[1])) @fclose($this->pipes[1]);
            if(is_resource($this->pipes[2])) @fclose($this->pipes[2]);
        }
    }

    /**
     * Returns the command to be executed
     * @return string
     */
    public final function getCommand() {
        return $this->command;
    }

    /**
     * Sets the new command to be executed.
     * @param string $command
     */
    public final function setCommand($command) {
        $this->command = trim($command);
    }

    /**
     * Returns the timeout in seconds
     * @return double
     */
    public final function getTimeout() {
        return $this->timeout;
    }

    /**
     * Sets the new process timeout in seconds
     * @param double $seconds
     */
    public final function setTimeout($seconds) {
        if(!is_numeric($seconds)) {
            throw new Exception('Timeout must be an integer value in seconds.');
        } else {
            $this->timeout = intval($seconds);
        }
    }

    /**
     * Returns if the process has to be terminated (killed) if it still runs
     * after a timeout, break or connection abort.
     * @return bool
     */
    public final function getTerminateOnAbort() {
        return $this->killProcessOnAbort;
    }

    /**
     * Sets if the process has to be terminated (killed) if it still runs
     * after a timeout, break or connection abort.
     * @param bool $terminate
     */
    public final function setTerminateOnAbort($terminate) {
        if(!is_bool($terminate)) {
            throw new Exception('Terminate-on-abort must be a boolean value.');
        } else {
            $this->killProcessOnAbort = $terminate ? true : false;
        }
    }

    /**
     * Returns the process ID of the child process, -1 if not yet started.
     * @return int
     */
    public final function getPID() {
        return $this->pid;
    }

    /**
     * Returns the process exit code after the process was stopped, null if
     * process not started or still running.
     * @return int
     */
    public final function getExitCode() {
        return $this->exitcode;
    }

    /**
     * Returns the process working directory
     * @return string
     */
    public final function getWorkingDirectory() {
        return strval($this->directory);
    }

    /**
     * Sets the process working directory
     * @param string $dir
     */
    public final function setWorkingDirectory($dir) {
        $dir = trim($dir);
        if(!FileSystem::isDirectory($dir)) {
            throw new Exception("Cannot set working directory to nonexisting directory");
        }
        $this->directory = $dir;
    }

    /**
     * Writes a $text to the STDIN (terminal input) of the process
     * @param string $text
     */
    public final function sendKeys($text) {
        if(!is_resource($this->hProcess)) {
            throw new Exception('Shell command not running, cannot send characters to STDIN');
        } else if(!fwrite($this->pipes[0], $text)) {
            throw new Exception('Failed to write to STDIN pipe of shell command');
        }
    }

    /**
     * Terminates the process using the kill command.
     */
    public final function terminate() {
        // That's to ensure that the pid is ok
        $pid = $this->pid;
        if($pid > 0) {
            Tracer::trace("KILL executed process $pid");
            @exec("ps ax -o  \"%p,%P\"", $return, $exitcode);
            if(is_array($return)) {
                foreach($return as $cpid) {
                    $cpid = explode(',', $cpid);
                    if(trim($cpid[1]) == $pid) {
                        Tracer::trace("KILL child process " . $cpid[0]);
                        @exec('kill ' . $cpid[0] . ' 2>/dev/null >&- >/dev/null');
                    }
                }
            }
            @exec('kill ' . $pid . ' 2>/dev/null >&- >/dev/null');
        } else {
            throw new Exception('Could not fetch a valid pid to terminate process', 1001);
        }
    }

    /**
     * Executes the specified command line
     * @return void
     */
    public final function run() {

        $ignoreUserAbort = ignore_user_abort();
        if(!$this->abortOnConnectionClosed) {
            ignore_user_abort(false);
        }
        set_time_limit(60);
        ini_set('memory_limit','256M');
        if($this->command == '') {
            throw new Exception('No shell command specified to execute');
        } else {
            $descriptors = array(0 => array("pipe", "r"), 1 => array("pipe", "w"), 2 => array("pipe", "w"));
            $this->hProcess = proc_open("exec " . $this->command, $descriptors, $this->pipes, $this->directory, $this->environment);
            if(!is_resource($this->hProcess)) {
                $exception = new Exception('Executing shell command failed');
            } else {
                $status = proc_get_status($this->hProcess);
                if(!is_array($status)) {
                    throw new Exception("Failed to determine process status of started process");
                }
                $this->pid = $status['pid'];

                if($this->abortOnConnectionClosed) {
                    if(!is_array(self::$processToKillOnAbort)) {
                        self::$processToKillOnAbort = array();
                        register_shutdown_function(array(__CLASS__, 'shutdownTermination'), 'inside');
                    }
                    self::$processToKillOnAbort[strval($this->pid)] = $this->pid;
                }

                stream_set_blocking($this->pipes[1], 0);
                stream_set_blocking($this->pipes[2], 0);
                $stdoutOpen = $stderrOpen = true;
                $timeout = microtime(true) + $this->timeout;
                $exception = null;
                $nextOnRunningInterval = 0.1;
                $nextOnRunning = microtime(true) + $nextOnRunningInterval;

                try {
                    $this->onProcessStarted();
                } catch(Exception $e) {
                    $exception = $e;
                }

                if(!$exception) {

                    while($stdoutOpen || $stderrOpen) {
                        // Check if streams have new data
                        $stream_r = array();
                        $stream_w = null;
                        $stream_x = null;
                        if($stdoutOpen) {
                            $stream_r[] = $this->pipes[1];
                        }
                        if($stderrOpen) {
                            $stream_r[] = $this->pipes[2];
                        }

                        $stream_c = stream_select($stream_r, $stream_w, $stream_x, 100);
                        if($stream_c === false) {
                            $exception = new Exception('Failed to check STDOUT and STDERR for new data');
                            break;
                        } else if($stream_c > 0) {

                            // Check STDOUT for new data
                            if($stdoutOpen) {
                                if(!feof($this->pipes[1])) {
                                    $txt = fread($this->pipes[1], 4096);
                                    $l = strlen($txt);
                                    if($l > 0) {
                                        try {
                                            $this->onStdOut($txt);
                                        } catch(Exception $e) {
                                            $exception = $e;
                                            break;
                                        }
                                    }
                                } else {
                                    $stdoutOpen = false;
                                }
                            }

                            // Check STDERR for new data
                            if($stderrOpen) {
                                if(!feof($this->pipes[2])) {
                                    $txt = fread($this->pipes[2], 4096);
                                    $l = strlen($txt);
                                    if($l > 0) {
                                        try {
                                            $this->onStdErr($txt);
                                        } catch(Exception $e) {
                                            $exception = $e;
                                            break;
                                        }
                                    }
                                } else {
                                    $stderrOpen = false;
                                }
                            }
                        }

                        // Check if connection has been closed by the client
                        // and ignore_userabort() was set to true
                        if($this->abortOnConnectionClosed) {
                            if(connection_aborted()) {
                                $exception = new Exception('Client connection closed');
                                break;
                            }
                        }

                        // Check for script timeout
                        if($this->timeout > 0) {
                            if(microtime(true) > $timeout) {
                                $exception = new Exception('Script timed out');
                                break;
                            } else {
                                set_time_limit(20);
                            }
                        }

                        // Only to be sure not to block other proceses even if
                        // each loop results new data.
                        usleep(10);

                        if(microtime(true) >= $nextOnRunning) {
                            $nextOnRunning = microtime(true) + $nextOnRunningInterval;
                            if($this->onProcessRunning() === false) {
                                break;
                            }
                        }

                        $status = proc_get_status($this->hProcess);
                        if(!is_array($status) || $status['running'] == false) {
                            break;
                        }
                    }
                }

                // Get the status agein
                $status = proc_get_status($this->hProcess);
                if(!is_array($status)) {
                    $exception = new Exception("Failed to determine process status");
                } else if($status['running'] == true) {
                    if($this->killProcessOnAbort) {
                        try {
                            $this->terminate();
                        } catch(Exception $e) {
                            if(! $exception instanceof Exception) {
                                $exception = $e;
                            } else {
                                // ok, do it this way, not using $previous ...
                                $exception = new Exception($exception->getMessage() . ', AND ADITIONALLY: ' . $exception->getMessage());
                            }
                        }
                    }
                }

                // Get exit code
                if(is_array($status) && !$status['running']) {
                    $this->exitcode = $status['exitcode'];
                }

                // clean up
                @proc_close($this->hProcess);
                if(is_resource($this->pipes[0])) @fclose($this->pipes[0]);
                if(is_resource($this->pipes[1])) @fclose($this->pipes[1]);
                if(is_resource($this->pipes[2])) @fclose($this->pipes[2]);
                $this->hProcess = null;
                $this->pipes = array();

                try {
                    $this->onProcessStopped($this->exitcode);
                } catch(Exception $e) {
                    $exception = $e;
                }

            }

            // Unregister the process id to kill at shutdown time.
            if(isset (self::$processToKillOnAbort[strval($this->pid)])) {
                unset(self::$processToKillOnAbort[strval($this->pid)]);
            }

            // Restore the original ignore_user_abort.
            ignore_user_abort($ignoreUserAbort);

            if($exception != null) {
                throw $exception;
            }
        }
    }

    /**
     * Registered shutdown function, terminates all child processes,
     * which are registered as terminate on abort.
     * @return void
     */
    public static final function shutdownTermination() {
        if(is_array(self::$processToKillOnAbort)) {
            foreach(self::$processToKillOnAbort as $pid) {
                $return = array();
                $exitcode = -1;
                @exec("ps ax -o  \"%p,%P\"", $return, $exitcode);
                if(is_array($return)) {
                    foreach($return as $cpid) {
                        $cpid = explode(',', $cpid);
                        if(trim($cpid[1]) == $pid) {
                            Tracer::trace("KILL child process " . $cpid[0]);
                            @exec('kill ' . $cpid[0] . ' 2>/dev/null >&- >/dev/null');
                        }
                    }
                }
                @exec('kill ' . $pid . ' 2>/dev/null >&- >/dev/null');
            }
        }
    }
}
?>

This Article is also available in Deutsch.

LaTex formula rendering class

stfwi — Mon, 05 Jul 2010 19:58:58 +0000

This class renders a LaTex formula to an image with transparent background. The image files are cached, so that the shell processes are not started twice if the formula was already requested – that’s good for the performance. The sample script returns not something like >img src=”…” /%lt;, but directly the image binary. The sample source code shows how to use it. Note that this very likely won’t work if you have only a webspace. You need Latex installed, ImageMagick, and need the possibility to create restricted user accounts (for security reasons, Latex can execute shell commands).

Sample source code

I use a Mac for the development, so the paths are also MacPorts related (/opt/local/bin/something).

 $1 $2 $3 $4 $5 $6 $7 $8 $9"
        // The user is of cause NOT root, but a restricted used registered in
        // the sudoers file. The HOME directory of this user is the current one.
        $sudo = dirname(__FILE__) . '/sudo_restricted.sh ';
        LaTexRenderer::config(array(
            'cache_dir' => dirname(__FILE__) . '/cache',
            'latex_bin' => $sudo . '/usr/texbin/latex',
            'dvips_bin' => $sudo . '/usr/texbin/dvips',
            'convert_bin' => $sudo . '/opt/local/bin/convert',
            'cache_prefix' => 'texf_',
            'temp_dir' => '',
            'font_size' => 16,
            'packages' => array(
                'amsmath','amsfonts','amssymb','latexsym','color'
            )
        ));
        $render = new LaTexRenderer();
        $file = dirname(__FILE__) . '/cache/' . $render->renderFormulaToImage($_GET['f']);
        $rc = new ResourceFile($file, '/');
        $rc->download();
    } catch(Exception $e) {
        header('501 Internal Server Error');
    }
} else {
// Html header and footer
print <<
    LaTeX Equations and Graphics in PHP
    
    {$_GET['f']}

    
    
HERE;
}
?>

Class source code

 '/usr/texbin/latex',
        'dvips_bin' => '/usr/texbin/dvips',
        'convert_bin' => '/opt/local/bin/convert',
        'cache_dir' => '',
        'cache_prefix' => 'texf_',
        'temp_dir' => '',
        'font_size' => 16,
        'packages' => array(
            'amsmath','amsfonts','amssymb','latexsym','color'
        )
    );

    /**
     * Sets and returns the class configuration
     * @param array $config
     * @return array
     */
    public static function config($config=null) {
        if(!empty($config)) {
            if(!is_array($config)) {
                throw new Exception('Class '. __CLASS__ . ' must be configured using an array');
            } else {
                self::$config = array_merge(self::$config, $config);
            }
        }
        return self::$config;
    }

    /**
     * Overload this function to filter the input TeX sources, or e.g. using
     * HTTP authentication to enable it. You can return a text that renders
     * an error message.
     * @param string $tex
     * @return string
     */
    protected function onTexFilter($tex) {
        return $tex;
    }

    /**
     * Constructor, automatically initializes the undefined configuration
     * if the temp_directory is empty.
     */
    public function  __construct() {
        if(empty(self::$config['cache_dir'])) self::config(array('cache_dir' => './cache'));
        if(empty(self::$config['temp_dir'])) self::config(array('temp_dir' => '/tmp'));
    }

    /**
     * Render a formula to an image
     * @return string
     */
    public function renderFormulaToImage($tex) {
        return $this->renderToImage("\\documentclass[10pt]{article}\n\$packages\\pagestyle{empty}\n\\begin{document}\n\\begin{displaymath}\n$tex\n\\end{displaymath}\n\\end{document}\n");
    }

    /**
     * Renders a LaTeX source to an image (png) if the md5 checksum of the
     * source text already exists, a cached image representation is returned.
     * The images are located in in the cache directory.
     * @param string $tex
     * @return string
     */
    private function renderToImage($tex) {
        $tex = $this->onTexFilter($tex);
        $fileName = trim(self::$config['cache_prefix'] . md5($tex));
        $cacheFilePath = self::$config['cache_dir'] . "/$fileName.png";

        if(!is_file($cacheFilePath)) {
            $exception = null;
            try {
                $packages = self::$config['packages'];
                foreach($packages as $key => $package) {
                    $packages[$key] = "\usepackage{" . $package . "}";
                }
                $packages = implode("\n", $packages);
                $font_size = self::$config['font_size'];
                $tex = str_replace('$packages', $packages, $tex);
                $current_dir = getcwd();
                $tmpDir = self::$config['temp_dir'];
                $cacheDir = self::$config['cache_dir'];

                chdir($tmpDir);
                file_put_contents("$tmpDir/$fileName.tex", $tex);

                $output = array();
                exec(self::$config['latex_bin'] . " --interaction=nonstopmode $tmpDir/$fileName.tex", $output, $return_var);
                @unlink("$tmpDir/$fileName.tex");
                @unlink("$tmpDir/$fileName.aux");
                @unlink("$tmpDir/$fileName.log");

                if(!is_file("$tmpDir/$fileName.dvi")) {
                    $error = '';
                    foreach ($output as $line) {
                        $line = trim($line);
                        if(!empty($line)) {
                            if(substr($line, 0, 1) == '!') {
                                $error = trim($line, "!. ");
                            } else if(!empty($error)) {
                                $line = ltrim($line, ' l.0123456789');
                                throw new Exception("LaTeX: $error: $line");
                            }
                        }
                    }
                    if(!empty($error)) {
                        throw new Exception('LaTeX:' . $error);
                    } else {
                        throw new Exception('LaTeX did not generate output file');
                    }
                }

                $output = array();
                exec(self::$config['dvips_bin'] . " -E $tmpDir/$fileName.dvi -o $tmpDir/$fileName.ps", $output, $return_var);
                @unlink("$tmpDir/$fileName.dvi");
                if(!is_file("$tmpDir/$fileName.ps")) {
                    throw new Exception('LaTeX/dvips conversion failed: ' . implode("\n", $output));
                }

                $output = array();
                chmod("$tmpDir/$fileName.ps", 0666);
                exec(escapeshellcmd(self::$config['convert_bin'] . " -define registry:temporary-path=$tmpDir -density 120 $tmpDir/$fileName.ps $tmpDir/$fileName.png"));
                @unlink("$tmpDir/$fileName.ps");
                if(is_file("$tmpDir/$fileName.png")) {
                    copy("$tmpDir/$fileName.png", "$cacheDir/$fileName.png");
                    @unlink("$tmpDir/$fileName.png");
                } else {
                    throw new Exception('Conversion from to ps to png failed:' . implode("\n", $output));
                }
            } catch(Exception $e) {
                $exception = $e;
            }

            chdir($current_dir);

            // Rethrow the exception after cleanup and directory restored
            if(!empty($exception)) {
                throw $exception;
            }
        }

        return "$fileName.png";
    }
}
?>

This Article is also available in Deutsch.

Ini file handling class

stfwi — Mon, 05 Jul 2010 17:06:35 +0000

Sometimes old-fashioned ini-files have to be read or written. This class is a possible interface for these tasks. I use it because I have to convert files sometimes – with case sensitive keys.

Sample source code

';

// Path to a temporary config file
$path = FileSystem::getTempDirectory() . '/test_configfile.ini';
print "Config file pPath = '$path'\n\n";

FileSystem::writeFile($path, <<data = " . print_r($cfg->data, true) . "\n";

// Modify data ...
$cfg->data['section 3'] = array(
    'key3.1' => 2000,
    'key3.2' => 'A third text'
);

// Save the file
$cfg->save();

print "New content = " . FileSystem::readFile($path) . "\n\n";

unlink($path);
print '';
?>

Output

Config file pPath = '/Applications/XAMPP/xamppfiles/temp/test_configfile.ini'

$cfg->data = Array
(
    [section 1] => Array
        (
            [key1.1] => 1000
            [key1.2] => A text
        )

    [section 2] => Array
        (
            [key2.1] => 2000
            [key2.2] => A second text
        )

)

New content =
 [section 1]
key1.1=1000
key1.2=A text
[section 2]
key2.1=2000
key2.2=A second text
[section 3]
key3.1=2000
key3.2=A third text

Class source code

Note that only the data are saved, comments are not read or saved. The entries and sections are case sensitive.

data['section']['key']
     * @var array
     */
    public $data = array();

    /**
     * Constructor. If a file specified with the $path argument
     * exists, then the file is directly read and parsed.
     * Throws no exception if the file does not exist. Instead,
     * the path is saged in the $file instance variable for later
     * saving.
     * @param string $path
     */
    public function __construct($path=null) {
        $this->file = $path;
        if(is_file($path)) {
            // Readfile throws exceptions
            $contents = explode("\n", str_replace("\r", "\n", FileSystem::readFile($path)));
            $this->data = array();
            $actualSection = null;
            foreach($contents as $line) {
                $line = ltrim($line, " \t\v");
                // Check comments
                if(empty($line)) {
                    continue;
                } else {
                    switch(substr($line,0,1)) {
                        case '*':
                        case '#':
                        case "'":
                            continue;
                            break;
                        case '[':
                            $line = trim($line, " \t\v[]");
                            if(!isset($this->data[$line])) {
                                $this->data[$line] = array();
                            }
                            $actualSection = &$this->data[$line];
                            break;
                        default:
                            $line = explode('=', $line, 2);
                            $line[0] = trim($line[0], " \t");
                            $actualSection[$line[0]] = isset($line[1]) ? $line[1] : '';
                            $actualKey = &$actualSection[$line[0]];
                    }
                }
            }
        }
    }

    /**
     * Returns a new ConfigFile instance containing the loaded and parsed
     * data. Throws an exception if the file does not exist.
     * @param string $path
     */
    public static function load($path){
        $o = new self($path);
        if(!is_file($path)) {
            // The constructor loads a file of it exists in the file system
            // The load method must throw an exception if the file does not exist
            throw new Exception("Config file to load does not exist: '$path'");
        }
    }

    /**
     * Saves the content of the assoc. data array in the file specified by
     * $path, or by the already set $file instance variable. Note that comments
     * will be removed.
     * @param string $path
     */
    public function save($path=null) {
        if(!is_array($this->data)) {
            throw new Exception('Config file data must be an array of arrays (sections of key-value-pairs)');
        } else {
            $r = '';
            foreach($this->data as $section => $pairs) {
                if(is_array($pairs)) {
                    $section = trim($section);
                    $r .= "[$section]\n";
                    foreach($pairs as $key => $value) {
                        if(!settype($value, 'string')) {
                            throw new Exception("There must be a string representation of the value of a config entry (value of [$section][$key] )");
                        } else {
                            $r .= trim($key) . '=' . str_replace("\r", '', str_replace("\n",'', $value)) . "\n";
                        }
                    }
                } else {
                    throw new Exception('A config file section must be an assoc. array (pattern is $data[section][key]=value');
                }
            }
            $path = trim($path);
            if(strlen($path) == 0) {
                $path = $this->file;
            }
            // Will throw an exception if something's wrong
            FileSystem::writeFile($path, $r);
        }
    }
}
?>

This Article is also available in Deutsch.

PHP code info and sandboxed executing

stfwi — Mon, 05 Jul 2010 14:50:06 +0000

This is a collection of the one and other function around PHP source code handling, including sandboxing without the need to install PEAR (I just didn’t have it – if you do, then use the Sandbox class, the function here is slower). Other static functions are checking the overhead of a PHP file and getting some information about a PHP file, such as defined classes, functions or interfaces.

Sample source code

';

// Print out the documentation overhead, which is the
// ratio between stripped and original file.
print "PhpCode::documentationOverhead(...) = " . print_r(
        PhpCode::documentationOverhead(__FILE__), true
        ) . "\n\n";

// This should show one class "MySql". Note that this source code info
// does not work for file that are already loaded.
print "PhpCode::getSourceInfo(...) = " . print_r(
        PhpCode::getSourceInfo('MySql.class.php'), true
        ) . "\n\n";

$result = PhpCode::evaluate(<<getMessage();
CODE_HERE
);

// This should show the output, an exception that occured, new added
// functions, classes and interfaces.
print "PhpCode::evaluate(...) = " . print_r($result, true) . "\n\n";

// This is executed sandboxed, note that savemode must be switched off to
// to this.
$result = PhpCode::evaluateSandboxed(<<Sandboxed eval ...";
   print "Arguments = ";
   print_r(\$GLOBALS);
CODE_HERE
, array(
    // Here some arguments
    '_GET' => array(
        'key1' => 'value1',
        'key2' => 'value2',
        'key3' => 'value3'
    )
));

print "PhpCode::evaluateSandboxed(...) = " . print_r($result, true) . "\n\n";

print '';
?>

Output

The output on my localhost is:

Class source code

getOutput();
        $output['classes'] = array_diff($c2, $c1);
        self::trace("New classes: ". implode(",",$output['classes']));
        unset($c1, $c2, $buffer);
        return $output;
    }

    /**
     * Execute php code and returns its print output
     * @return array
     */
    public static function evaluate($phpSourceCode) {
        self::trace("evaluating '$phpSourceCode'");
        $c0 = get_declared_classes();
        $f0 = get_defined_functions(); $f0 = $f0['user'];
        $i0 = get_declared_interfaces();
        $t0 = Tracer::getTimer();
        $out = array();
        $out['exception'] = null;
        $ob = new OutputBuffer();
        try {
            eval($phpSourceCode);
        } catch(Exception $e) {
            $out['exception'] = $e;
        }
        $t0 = Tracer::getTimer() - $t0;
        $c1 = get_declared_classes();
        $f1 = get_defined_functions(); $f1 = $f1['user'];
        $i1 = get_declared_interfaces();
        $out['interfaces'] = array_diff($i1, $i0);
        $out['classes'] = array_diff($c1, $c0);
        $out['functions'] = array_diff($f1, $f0);
        $out['output'] = $ob->getOutput();
        self::trace("New classes: ". implode(",",$out['classes']));
        unset($c0, $c1, $ob);
        return $out;
    }

    /**
     * Executes a string independent from the actual script
     * using command line PHP. Takes more time than normal
     * execution, but cannot crash your script.
     * Normally a Sandbox could be used for this, but this
     * is an alternative also running without PEAR.
     * But again: SLOW.
     * @param string $phpSourceCode
     * @param array $args
     * @return string
     */
    public static function evaluateSandboxed($phpSourceCode, $args=null) {
        if(!empty($args) && is_array($args)) {
            $argf = tempnam('/tmp' , 'php_evaluate_args_');
            $aop = " $arg) {
                $aop .= '$' . $key . '=' . var_export($arg, true) . ';';
                $globs[] = '"' . $key . '" => &$' . $key;
            }

            $aop .= "\n?>";
            file_put_contents($argf, $aop);
            unset($aop);
            $phpSourceCode = '';
        }
        $file = tempnam('/tmp' , 'php_evaluate_');
        file_put_contents($file, $phpSourceCode);
        $out = shell_exec("php $file");
        @unlink($file);
        @unlink($argf);
        return $out;
    }

    /**
     * Returns an array containing information about the
     * "overhead" using documentation and code structuring.
     * @return array
     */
    public static function documentationOverhead($file) {
        $out = array(
            'original_size' => 0,
            'stripped_size' => 0,
            'relation_percent' => 0,
            'error' => ''
        );
        $file = trim(str_replace("\\", "/", $file)); // windows, windows ;)
        if(!file_exists($file)) $file = str_replace('//','/', $_SERVER['DOCUMENT_ROOT'] . $file);
        if(!file_exists($file)) {
            $out['error'] = "file does not exist";
        } else if(!is_readable($file)) {
                $out['error'] = "file not readable, no access";
            } else {
                $out['stripped_size'] = strlen(php_strip_whitespace($file));
                $out['original_size'] = strlen(file_get_contents($file));
                $out['relation_percent'] = intval(100 * $out['original_size'] / $out['stripped_size']);
            }
        return $out;
    }

    /**
     * Private tracing method
     * @param string $text
     * @param int $level
     */
    protected function trace($text, $level=1) {
        if(!Tracer::tracedClass(__CLASS__)) return;
        Tracer::trace($text, $level);
    }
}
?>

This Article is also available in Deutsch.

Class for upload/download management

stfwi — Sun, 04 Jul 2010 23:28:15 +0000

Here’s a class for managing the upload and download of files via PHP. It supports HTTP Range (for partial downloads and continuing), cache control, ETags, if-modified-since, and the usual suspects like forcing the dialog “Save file as” for mime types that would be directly shown in the browser (like images or text files). ResourceFile can be used directly or extended to make own constant settings. An example how the downloading works is described in the example implementation here:

Sample source code

getName();
$filesize          = $rc->getSize();
$lastModified      = $rc->getLastModified();
$withRespectToRoot = $rc->getPath();
$wholePath         = $rc->getFilePath();
$extension         = $rc->getExtension();
$parentDirectory   = $rc->getDirectory();
$fileExists        = $rc->exists();
$mime              = $rc->getMimeType();
$etag              = $rc->getETag();
$md5               = $rc->getMD5();
$cacheControl      = $rc->getCacheControl();
$expires           = $rc->getExpireTime();
$mustDownload      = $rc->getForceSaveFile();

// Ok. let's download it
$rc->download();
?>

Output

These are the request/response headers:

Request Headers
  Accept:application/xml,application/xhtml+xml,text/html;q=0.9,text/plain;q=0.8,...
  Cache-Control:max-age=0
  Referer:http://htx.localhost/tests/
  User-Agent:Mozilla/5.0 (Macintosh; U; Intel ...

Response Headers
  Accept-Ranges:bytes
  Cache-Control:private, must-revalidate, max-age=1278280363
  Connection:close
  Content-Disposition:inline; filename="file.txt"
  Content-Length:27
  Content-Range:bytes 0-16/16
  Content-Type:text/plain
  Date:Sun, 04 Jul 2010 20:52:43 GMT
  Etag:"8dc4b39f096b4b6823d6722fe0fd7bad"
  Expires:Sun, 04 Jul 2010 21:52:43 GMT
  Last-Modified:Sun, 04 Jul 2010 20:52:43 GMT
  Server:Apache/2.2.14 (Unix) DAV/2 mod_ssl/2.2.14 OpenSSL ...
  X-Powered-By:PHP/5.3.1

Class source code

So, and this is the class source code. Some annotations

Make sure that you don’t send any text before, this would mess up the download. Use an output buffer (e.g. the class OutputBuffer in this category).
I extended the class, so that the checksum, date etc are saved in the database. This makes sure that you can see if the file was modified in-between (e.g. by another process or script).

 0) $this->path = $subpath;
        if(!empty($rootPath)) $this->rootDirectory = $rootPath;
        if(!is_null($expireTime)) $this->setExpireTime($expireTime);
        if(!empty($cacheControl)) $this->setCacheControl($cacheControl);
        if(!is_null($forceSaveFile)) $this->setForceSaveFile($forceSaveFile);
    }

    /**
     * Returns the root directory of the filesystem saved
     * files (if database files it is the cache, if 'normal'
     * files it is the local directory where the resource
     * files are saved in.
     * E.g. $_SERVER['DOCUMENT_ROOT'] . '/files'
     * @return string
     */
    public function getFileRootDirectory() {
        return $this->rootDirectory;
    }

    /**
     * Returns content expire time in seconds.
     * @return int
     */
    public function getExpireTime() {
        return $this->expireTime;
    }

    /**
     * Sets the new expiry time interval in seconds.
     * This is not an absolute timestamp (which will be
     * calculated during the download).
     * @param int $seconds
     */
    public function setExpireTime($seconds) {
        if(!is_numeric($seconds)) {
            throw new Exception("Wrong expiry time specified:$seconds");
        } else {
            $this->expireTime = intval($seconds);
        }
    }

    /**
     * Returns the path with resource name and extension
     * in the local root path.
     * @return string
     */
    public final function getPath() {
        return $this->path;
    }

    /**
     * Returns the path to the server loacal saved
     * file. This is an absolute system file patb.
     * @return string
     */
    public final function getFilePath() {
        return $this->getFileRootDirectory() . '/' . trim($this->getPath(), ' /');
    }

    /**
     * Returns the resource name.
     * @return string
     */
    public final function getName() {
        return basename($this->path);
    }

    /**
     * Returns the resource extension.
     * @return string
     */
    public final function getExtension() {
        $p = strrpos($this->getName(), '.');
        if($p === false || $p == strlen($this->getName())) {
            return '';
        } else {
            return substr($this->getName(), $p+1);
        }
    }

    /**
     * Returns the resource parent directory.
     * @return string
     */
    public final function getDirectory() {
        return dirname($this->path);
    }

    /**
     * Returns the mime type by parsing the
     * extension.
     * @return string
     */
    public function getMimeType() {
        if(empty(self::$mimeTypes)) {
            self::$mimeTypes = array(
                'txt' => 'text/plain',
                'htm' => 'text/html',
                'html' => 'text/html',
                'php' => 'text/html',
                'css' => 'text/css',
                'js' => 'application/javascript',
                'json' => 'application/json',
                'xml' => 'application/xml',
                'swf' => 'application/x-shockwave-flash',
                'flv' => 'video/x-flv',
                'png' => 'image/png',
                'jpe' => 'image/jpeg',
                'jpeg' => 'image/jpeg',
                'jpg' => 'image/jpeg',
                'gif' => 'image/gif',
                'bmp' => 'image/bmp',
                'ico' => 'image/vnd.microsoft.icon',
                'tiff' => 'image/tiff',
                'tif' => 'image/tiff',
                'svg' => 'image/svg+xml',
                'svgz' => 'image/svg+xml',
                'zip' => 'application/zip',
                'rar' => 'application/x-rar-compressed',
                'exe' => 'application/x-msdownload',
                'msi' => 'application/x-msdownload',
                'cab' => 'application/vnd.ms-cab-compressed',
                'mp3' => 'audio/mpeg',
                'qt' => 'video/quicktime',
                'mov' => 'video/quicktime',
                'pdf' => 'application/pdf',
                'psd' => 'image/vnd.adobe.photoshop',
                'ai' => 'application/postscript',
                'eps' => 'application/postscript',
                'ps' => 'application/postscript',
                'doc' => 'application/msword',
                'rtf' => 'application/rtf',
                'xls' => 'application/vnd.ms-excel',
                'ppt' => 'application/vnd.ms-powerpoint',
                'odt' => 'application/vnd.oasis.opendocument.text',
                'ods' => 'application/vnd.oasis.opendocument.spreadsheet'
            );
        }
        $ext = $this->getExtension();
        if(isset(self::$mimeTypes[$ext])) {
            return self::$mimeTypes[$ext];
        } else {
            return 'application/octet-stream';
        }
    }

    /**
     * Returns the file size in bytes
     * @return int
     */
    public function getSize() {
        $s = filesize($this->getFilePath());
        if($s===false) {
            throw new Exception('Failed to get file size');
        } else {
            return $s;
        }
    }

    /**
     * Returns the unix timestamp when the resource
     * was last modified. Overload this function for
     * database usage.
     * @return int
     */
    public function getLastModified() {
        $t = @filemtime($this->getFilePath());
        if($t === false) {
            throw new Exception('Getting file last modified time failed');
        } else {
            return $t;
        }
    }

    /**
     * Returns the md5 checksum of the resource.
     * Overload this function for database usage.
     * @return int
     */
    public function getMD5() {
        $t = md5_file($this->getFilePath());
        if($t === false) {
            throw new Exception('Getting file md5 failed');
        } else {
            return $t;
        }
    }

    /**
     * Returns if the resource exists
     * @return bool
     */
    public function exists() {
        return is_file($this->getFilePath()) ? true : false;
    }

    /**
     * Returns an ETAG for http header information.
     * @return string
     */
    public function getETag() {
        return md5($this->getFilePath() . $this->getLastModified() . $this->getSize());
    }

    /**
     * Returns if the "Save file dialog" is to bs
     * shown, even if the browser is able to interprete
     * the file.
     * @return bool
     */
    public function getForceSaveFile() {
        return $this->forceSaveFile;
    }

    /**
     * Sets if the "Save file dialog" is to bs
     * shown, even if the browser is able to interprete
     * the file.
     * @param bool $enable
     */
    public function setForceSaveFile($enable) {
        $this->forceSaveFile = $enable ? true : false;
    }

    /**
     * Returns the cache control setting. Values are "public", "private"
     * or "nocache"
     * @return string
     */
    public function getCacheControl() {
        return $this->cacheControl;
    }

    /**
     * Sets the cache control setting. Values are "public", "private"
     * or "nocache"
     * @return string
     */
    public function setCacheControl($ctrl) {
        $this->cacheControl = $this->cacheControl = trim(strtolower($ctrl));
        switch ($this->cacheControl) {
            case 'public':
            case 'private':
            case 'nocache':
                break;
            default:
                self::trace("Warning: wrong cache control set: $ctrl");
        }
    }

    /**
     * Moves uploaded file to a subfolder of
     * getFileRootDirectory(). $postfile is a
     * string name of a $_FILES['$postfile'] element.
     * $targetFile is subpath and file name. The extension
     * will be automatically added.
     * @param string $postfile
     * @param string $targetFile=''
     * @param bool $overwrite=false
     */
    public function upload($postfile, $targetFile='', $overwrite=false) {
        // Initialize path to "invalid"
        $this->path = '';
        $postfile = trim(strtolower($postfile));
        $files = array_change_key_case($_FILES);

        if(!isset($files[$postfile])) {
            throw new Exception('No file with this (input form) name posted');
        } else if(!is_array($files[$postfile])) {
            throw new Exception('The the $_POST[] array is empty.');
        } else {
            $postfile = array_change_key_case($files[$postfile], CASE_LOWER);
            unset($files);
            if($postfile['name'] == '') {
                throw new Exception('No file to upload selected');
            } else if(!isset($postfile['error']) || $postfile['error'] != 0) {
                throw new Exception('The uploaded file was not uploaded completly');
            } else if(false && $postfile['size'] == 0) { // TODO: Hmm, this could also be a normal use case ... must be checked
                throw new Exception('Upload file is empty');
            } else {
                $fname = trim($postfile['name']);
                $ftype = trim($postfile['type']);
                $ftemp = trim($postfile['tmp_name']);
                $fsize = $postfile['size'];
                $fext  = FileSystem::getExtension($fname);

                if($fsize != filesize($ftemp)) {
                    throw new Exception('The file size of the uploaded file does not match the size specified by the client');
                } else {
                    if(empty($targetFile)) {
                        // Generate target file name
                        $targetFile = $this->getFileRootDirectory() . '/' . $fname;
                    } else {
                        $targetFile = $this->getFileRootDirectory() . '/' . trim($targetFile, ' /');
                    }
                    if(!$overwrite && FileSystem::exists($targetFile)) {
                        throw new Exception('The file to upload already exists in the file system');
                    } else {
                        // Move uploaded file
                        if(!move_uploaded_file($ftemp, $targetFile) === null) {
                            if(!is_writable(dirname($targetFile))) {
                                throw new Exception('Target file parent directory is not writable for you.');
                            } else {
                                throw new Exception('Failed to move uploaded file');
                            }
                        } else {
                            $this->path = trim(str_replace($this->getFileRootDirectory(), '', $targetFile), ' /');
                        }
                    }
                }
            }
        }
    }

    /**
     * Binary passthrough to the http client, if no
     * file name is specified the resource file name
     * is used. $forSaveOnLocalComputer defines if
     * always the "save file to" is displayed in
     * the browser (attachment disposition).
     * @param string $filename
     * @param bool $forSaveOnLocalComputer
     */
    public function download($fileName='') {
        if($fileName=='') {
            $fileName = $this->getName();
        }

        // Clear all actual output buffers and drop'em, cause the session
        // to write the session file (to prevent lock errors for large
        // file downloads)
        while(ob_get_level() > 0) {
            @ob_end_clean();
        }
        @session_write_close();
        @set_time_limit(5);

        if((headers_sent($hs_file, $hs_line))) {
            self::trace("Headers already sent in $hs_file:$hs_line");
            throw new Exception('Headers already sent');
        } else if(connection_status() != 0) {
            self::trace('Connection was closed');
            throw new Exception('Connection closed');
        } else if($fileName == '') {
            self::trace('File name is empty'  . $this->getFilePath());
            throw new Exception('File name is empty');
        } else if(!$this->exists()) {
            self::trace('File not found:' . $this->getFilePath());
            throw new Exception('File not found');
        } else if(substr($this->getName(), 0, 1) == '.') {
            self::trace('File is hidden (.anything)' . $this->getFilePath());
            throw new Exception('File hidden');
        } else {
            self::trace('file exists and not hidden');
            $request_headers  = array_change_key_case(apache_request_headers(), CASE_LOWER);
            $fileMdyf = $this->getLastModified();
            $fileetag = $this->getETag();

            if(isset($request_headers['if-modified-since']) && @strftime("D, d M Y H:i:s", $request_headers['if-modified-since']) == $fileMdyf) {
                self::trace('if-modified-since matched, send not modified 304');
                header('Content-Length: 0', true, 304);
            } else if(isset($request_headers['if-none-match']) && stripos($fileetag, $request_headers['if-none-match']) !== false) {
                self::trace('if-none-match matched, send not modified 304');
                header('Content-Length: 0', true,304);
            } else {
                $fileSize = $this->getSize();
                $fileMime = $this->getMimeType();
                $fileExpr = time() + $this->expireTime;
                $filePath = $this->getFilePath();

                header('HTTP/1.1 200 OK', true, 200);
                header('Connection: close', true);
                header("Last-Modified: " . @gmdate("D, d M Y H:i:s", $fileMdyf) . " GMT", true);
                header('Content-Type: ' . $fileMime, true);
                header("Content-Length: " . $fileSize, true);
                header('Expires: '. @gmdate('D, d M Y H:i:s', $fileExpr) . ' GMT', true);
                header('Etag: "' . $fileetag . '"', true);

                switch($this->cacheControl) {
                    case 'private':
                        self::trace('Cache control: private');
                        header('Cache-Control: private, must-revalidate, max-age=' . $fileExpr, true);
                        header_remove('Pragma');
                        break;
                    case 'public':
                        self::trace('Cache control: public');
                        header('Cache-Control: public, must-revalidate, max-age=' . $fileExpr, true);
                        header_remove('Pragma');
                        break;
                    default:
                        self::trace('Cache control: nocache');
                        header('Cache-Control: no-store, no-cache, must-revalidate, post-check=0, pre-check=0');
                        header('Pragma: no-cache', true);
                }

                if($this->forceSaveFile) {
                    self::trace('adding the "for local saving headers"');
                    header('Content-Disposition: attachment; filename="'. $fileName . '"', true);
                    header('Content-Transfer-Encoding: binary', true);
                } else {
                    header('Content-Disposition: inline; filename="' . $fileName . '"', true);
                }

                // Prepare send
                $fs=0;
                $fe=$fileSize;

                // HTTP Range support
                if($this->enableHttpRange) {
                    if(isset($_SERVER['HTTP_RANGE']) && preg_match('/bytes=\h*(\d+)-(\d*)[\D.*]?/i', $_SERVER['HTTP_RANGE'], $matches)) {
                        if(!empty($matches[0]) && is_numeric($matches[0])) {
                            $fst = intval($matches[0]);
                            if(!empty($matches[1]) && is_numeric($matches[1])) $fet=intval($matches[1]);
                            if($fst >= 0 && $fet > $fst && $fet <= $fileSize) {
                                header('HTTP/1.1 206 Partial Content', true, 206);
                                $fs = $fst;
                                $fe = $fet;
                            }
                        }
                    }
                    header('Accept-Ranges: bytes', true);
                    header('Content-Length:'.($fe-$fs), true);
                    header("Content-Range: bytes $fs-$fe/$fileSize", true);
                }

                // Send the file
                if(!($pfile=@fopen($filePath,'rb'))) {
                    header("HTTP/1.1 505 Internal server error", true, 505);
                    throw new Exception('Failed to open file for range download: ' . $filePath);
                } else {
                    $fileChunkSize = 1024*16;
                    self::trace('passing file ...');
                    @fseek($pfile,0,0);
                    $fp=$fs;
                    fseek($pfile,$fs,0);
                    while(!feof($pfile) && $fp < $fe && (connection_status() == NORMAL)) {
                        print @fread($pfile, min($fileChunkSize, $fe-$fp));
                        $fp+=$fileChunkSize;
                        @set_time_limit(3);
                    }
                }
            }
        }
    }

    /**
     * Private tracing method
     * @param string $text
     * @param int $level
     */
    protected function trace($text, $level=1) {
        if(!Tracer::tracedClass(__CLASS__)) return;
        Tracer::trace($text, $level);
    }
}
?>

This Article is also available in Deutsch.

FileSystem class

stfwi — Sun, 04 Jul 2010 20:11:42 +0000

Well, there is not much to say about it. Its mainly a wrapper for the normal file system functions of PHP, except that it works with exceptions and has recursive functions. Risk a glance what you can do with it. The usage example is here:

Sample source code

";
include_once('FileSystem.class.php');

try {
    $tmpDir = FileSystem::getTempDirectory() . '/testDir';
    $file0  = "$tmpDir/file0.txt";

    print "Temporaries directory = " . FileSystem::getTempDirectory() . "\n";
    print "My Temporaries directory = $tmpDir\n";
    print "\n";

    try {
        print "Create my temp dir ...\n";
        // Throws exception if already exists
        FileSystem::mkdir($tmpDir, 0777);
    } catch(Exception $e) {
        print "Exception: " . $e->getMessage() . "\n";
    }

    print "Write file ...\n";
    FileSystem::writeFile($file0, 'test data');

    print "Read file ...\n";
    print "Written was: \"" . FileSystem::readFile($file0) . "\"\n" ;

    print "File0 = $file0\n";
    print "File0 dirname = " . FileSystem::getDirname($file0) . "\n";
    print "File0 basename = " . FileSystem::getBasename($file0) . "\n";
    print "File0 extension = " . FileSystem::getExtension($file0) . "\n";
    print "File0 exists? " . (FileSystem::exists($file0) ? "yes" : "no") . "\n";
    print "File0 directory? " . (FileSystem::isDirectory($file0) ? "yes" : "no") . "\n";
    print "File0 file? " . (FileSystem::isFile($file0) ? "yes" : "no") . "\n";
    print "File0 link? " . (FileSystem::isLink($file0) ? "yes" : "no") . "\n";
    print "File0 readable? " . (FileSystem::isReadable($file0) ? "yes" : "no") . "\n";
    print "File0 writable? " . (FileSystem::isWritable($file0) ? "yes" : "no") . "\n";

    // Find files recursively ...
    print "Write other files ...\n";
    foreach(array("file1", "file2", "file3", "file4") as $file) {
        FileSystem::writeFile("$tmpDir/$file", 'test');
    }
    FileSystem::mkdir("$tmpDir/subdir");
    foreach(array("file1", "file2", "file3", "file4") as $file) {
        FileSystem::writeFile("$tmpDir/subdir/$file", 'test');
    }

    print "Find * in tmpdir = " . print_r(FileSystem::find($tmpDir, '*'), true) . "\n";

    // Remove temp directory recursively ...
    print "Delete my temp dir\n";
    FileSystem::delete($tmpDir);

} catch(Exception $e) {
    print "Exception: " . $e->getMessage() . "\n" . $e->getTraceAsString();
}

print "";
?>

Class source code

This Article is also available in Deutsch.

Tracer class

stfwi — Sun, 04 Jul 2010 19:18:52 +0000

If your developing a page and don’t have the possibility to run a debugger in your IDE, or more likely if you uploaded your project but sometimes get strange errors and have no idea why, then a tracer can help. I wrote this class at a time (once upon a long time) when the debugger capabilities where so useless that it made no sense to use them. Since that time this class was enhanced a little bit, so that I have my trace points where I want, but can get an email from the server if an exception occurs, see which files are loaded, see the defined variables at the beginning and the end of the script execution and so on. Take a look at the sample source code and the corresponding output to see what’s inside:

Sample source code

fail1(0, 'i called you');
    }

    private function fail1($arg0, $arg1) {
        $this->fail2($arg0+1, crc32($arg1));
    }

    private function fail2($arg0, $arg1) {
        $this->fail3(2*$arg0, crypt($arg1));
    }

    private function fail3($arg0, $arg1) {
        $this->fail4($arg0+10, md5($arg1));
    }

    private function fail4($arg0, $arg1) {
        throw new Exception('Well, that failed');
    }
}

// Just to have an inherited class
class B extends A {
}

// Just to have a function in no class scope
function fail(A $a) {
    $a->fail();
}

// Implicit traced with trace level 1
Tracer::trace('Over Here');

// Traced with trace level 2
Tracer::trace('Over there', 2);

// Traced with trace level 2
Tracer::trace('This is not traced, because the trace level is 2', 3);

// The class scope is traced as well ...
$a = new A();
$b = new B();

$a->traceHere(); // Shows "A::traceHere() I am B"
$b->traceHere(); // Shows "A::traceHere() I am B", not "B::traceHere() I am B"

// That's the way you trace exceptions if you caught them. The backtrace
// is with function arguments and class scope:
try {
    fail($a);
} catch(Exception $e) {
    Tracer::traceException($e);
}

// Trace a variable (like print_r) with caption "My array" and level 2
$array = array(1 => 1000, 'key' => 'value');
Tracer::trace_r($array, 'My array', 2);

// Print out some information, notice that this will be displayed above the
// trace output, because the tracer buffers its own output.
print "Tracer timer = " . Tracer::getTimer() . '
';
print "Trace level  = " . Tracer::getLevel() . '
';
?>

Output

That’s how the output looks like. My format is T- , you can change this easily in the source code.

Tracer timer = 0001.425
Trace level = 2

T01-0000.076 Over Here
T02-0000.125 Over there
T01-0000.179 A::traceHere() I am A
T01-0000.221 A::traceHere() I am B
T00-0001.314 Exception("Well, that failed") in /tests/index.php@40
  /tests/index.php@36            A::fail4(12,"0055a4361bf12d7d138d649ee555f6cf")
  /tests/index.php@32            A::fail3(2,"$1$GQfJKSxD$giKXwEGXvqK3jLRqSE07H.")
  /tests/index.php@28            A::fail2(1,-4462706)
  /tests/index.php@24            A::fail1(0,"i called you")
  /tests/index.php@53            A::fail()
  /tests/index.php@77            ::fail(A)

T02-0001.400  My array=Array
  (
      [1] => 1000
      [key] => value
  )

Class source code



 0 or an uncaught Exception occured.
 * - Name  of recipient: $GLOBALS['config']['admin.name']
 * - EMail of recipient: $GLOBALS['config']['admin.email']
 *
 * The trace level is automatically set if $_GET['trace'] > 0
 * The trace level is saved in $_SESSION.
 * There is the possibility to set a default trace level using
 * - define('TRACER_DEFAULT_LEVEL', ). This should be
 *   for debugging only.
 *
 * If you want to force the Tracer being off (not seen by any
 * unauthenticated user) simply call Tracer::disable();
 *
 * @package de.atwillys.sw.php.swLib
 * @author Stefan Wilhelm
 * @copyright Stefan Wilhelm, 2007-2010
 * @license GPL
 * @version 1.0
 */
class Tracer {

    /**
     * Tracer class configuration
     * @var array
     */
    public static $config = array(
        'auto_source' => true,                  // Automatically add file, line, method ...
        'level' => -1,                          // Default level
        'append_trace_protocol' => false,       // Defines if the user can see the output
        'trace_to_file' => '',                  // File path to trace into (''=off)
        'email_on_uncaught_exceptions' => '',   // Admin email address (''=off)
        'traced_classes' => array()             // Keys are the names, values (bool) if traced
    );

    /**
     * Contains the context (globals) list if $traceContext == true
     * @staticvar array
     */
    private static $context = array();

    /**
     * Global trace level
     * @staticvar int
     */
    private static $level = -1;

    /**
     * Global tracer object
     * @staticvar tracer
     */
    private static $instance = null;

    /**
     * Global tracer start timer
     * @staticvar long
     */
    private static $timer;

    /**
     * Tracer output
     * @staticvar array
     */
    private static $output = array();

    /**
     * Contains the information about the last traced exception
     * @staticvar Exception[]
     */
    private static $exceptions = array();

    /**
     * Indicator that an uncaught exception occured
     * @staticvar bool
     */
    private static $hasUncaughgtException = false;

    /**
     * Tracer configuration. Sets the specified config settings (merges
     * with the existing). Returns the actual configuration after the
     * new array has been merged to the defaults/previous settings.
     * @param array $config
     * @return array
     */
    public static final function config($config = array()) {
        if(!is_array($config)) {
            throw new Exception('swlib config is no array');
        } else {
            self::$config = array_merge(self::$config, $config);
            if(!isset(self::$config['traced_classes'])) {
                self::$config['traced_classes'] = array();
            }
            self::$config['traced_classes'] = array_change_key_case(self::$config['traced_classes'], CASE_LOWER);
        }
        return self::$config;
    }

    /**
     * Tracer factory, subclass must be, if specified, a tracer derivate
     * @param array $config
     */
    public static final function start($config=array()) {
        if(!is_null(self::$instance)) {
            return self::$instance;
        }

        if(!empty($config)) {
            self::config($config);
        }

        if(!empty(self::$config['trace_to_file'])) {
            $o = "\n----------------------------------------------------------------------------- \n" .
                 "-- " . $_SERVER['REQUEST_URI'] . "\n" .
                 "----------------------------------------------------------------------------- \n";
            file_put_contents(self::$config['trace_to_file'], $o, FILE_APPEND);
            chmod(self::$config['trace_to_file'], 0666);
        }

        self::$timer = microtime(true);
        self::$instance = new self;
        self::$level = intval(self::$config['level']);

        if(self::$level === 0) {
            if(isset($_SESSION['swlib.tracelevel'])) unset($_SESSION['swlib.tracelevel']);
        } else if(self::$level > -1) {
            $_SESSION["swlib.tracelevel"] = self::$level;
        } else if(isset($_SESSION["swlib.tracelevel"])  && is_numeric($_SESSION['swlib.tracelevel'])) {
            self::$level = $_SESSION['swlib.tracelevel'];
        } else {
            self::$level = 0;
            if(isset($_SESSION['swlib.tracelevel'])) unset($_SESSION['swlib.tracelevel']);
        }

        if(self::$level > 0) {
            self::$context = array(
                'SERVER' => $_SERVER,
                'AT_STARTUP' => array(
                    'GET' => $_GET,
                    'POST' => $_POST,
                    'FILES' => $_FILES,
                    'COOKIE' => $_COOKIE,
                    'SESSION' => $_SESSION,
                    'REQUEST' => $_REQUEST,
                    'HTTP_REQUEST_HEADERS' => apache_request_headers(),
                    'HTTP_RESPONSE_HEADERS' => headers_list()
                )
            );
            if(isset(self::$context['SERVER']['PHP_AUTH_PW'])) {
                self::$context['SERVER']['PHP_AUTH_PW'] = "(password masked)";
            }
            self::$context['SERVER']['SERVER_ADMIN'] = '(admin email)';
        }
        return self::$instance;
    }

    /**
     * Disables tracer
     */
    public static final function stop() {
        self::$instance = null;
    }

    /**
     * Construction
     */
    private final function __construct() {
    }

    /**
     * Destruction
     */
    public final function __destruct() {
        if(self::$level > 0 || self::$hasUncaughgtException) {
            $included = array();
            foreach(get_included_files() as $value) {
                $included[] = str_replace($_SERVER['DOCUMENT_ROOT'], '', $value);
            }

            self::$context['AT_SHUTDOWN'] = array(
                    'GET' => $_GET,
                    'POST' => $_POST,
                    'FILES' => $_FILES,
                    'COOKIE' => $_COOKIE,
                    'SESSION' => $_SESSION,
                    'REQUEST' => $_REQUEST,
                    'HTTP_REQUEST_HEADERS' => apache_request_headers(),
                    'HTTP_RESPONSE_HEADERS' => headers_list()
                );

            self::$context['INCLUDED_FILES'] = $included;

            if(self::$level > 0 && self::$config['append_trace_protocol']) {
                $printit = strtolower(str_replace(' ', '', implode("\n", headers_list())));
                $printit = strpos($printit, 'content-type') !== false && strpos($printit, 'html') !== false;
                if($printit) {
                    $o = '';
                    foreach(self::$output as $line) {
                        $o .=  sprintf("T%02d-%s %s %s\n", $line[1], $line[0], $line[2], htmlspecialchars($line[3]));
                    }
                    if(!defined('TRACER_NO_CONTEXT') || TRACER_NO_CONTEXT != true) {
                        $o .= "\n" . ''. htmlspecialchars(print_r(self::$context, true)) . '';
                    }
                    $o = trim($o, " \n\r\t");
                    print '
' . $o . '';
                }
            } else if((self::$hasUncaughgtException && !empty(self::$config['email_on_uncaught_exceptions']))) {
                try {
                    foreach(self::$exceptions as $e) {
                        $o = 'Exception("' . $e->getMessage() . '"' . ($e->getCode()!=0?(' code=' . $e->getCode()):'') . ') in ' . str_replace($_SERVER['DOCUMENT_ROOT'], '', $e->getFile()) . "@" . $e->getLine() ."\n";
                        $o .= "\n" . self::backtrace($e->getTrace());
                        $o .= "\n";
                    }
                    $e = end(self::$exceptions);
                    require_once('Mailer.class.php');
                    $mailer = new Mailer();
                    $mailer->setSender(new EMailContact(' Tracer of ' . $_SERVER['SERVER_NAME'] , 'noreply@' . $_SERVER['SERVER_NAME']));
                    $mailer->addRecipient(new EMailContact(self::$config['email_on_uncaught_exceptions'], self::$config['email_on_uncaught_exceptions']));
                    $mailer->setSubject('Exception on ' . $_SERVER['SERVER_NAME'] . ': ' . $e->getMessage());
                    $o = 'Exception("' . $e->getMessage() . '"' . ($e->getCode()!=0?(' code=' . $e->getCode()):'') . ') in ' . str_replace($_SERVER['DOCUMENT_ROOT'], '', $e->getFile()) . "@" . $e->getLine() ."\n";
                    $o .= "\n" . self::backtrace($e->getTrace());
                    $o .= "\n" . print_r(self::$context, true);
                    $o .= "\n\n+++++ TRACER +++++++\n";
                    foreach(self::$output as $line) {
                        $o .=  sprintf("T%02d-%s %s %s\n", $line[1], $line[0], $line[2], htmlspecialchars($line[3]));
                    }
                    $mailer->setBody($o);
                    $mailer->send();
                } catch(Exception $ee) {
                    // ALL WRONG ...
                }
            }
        }
    }

    /**
     * Trace write method.
     * @param string $text
     * @param int $level
     * @param string $source
     */
    public final function write($text, $level=0, $source='') {
        self::$output[] = array(
            self::getTimer(),
            $level,
            $source,
            $text
        );
        $o = sprintf("T%02d-%s %s %s", $level, self::getTimer(), $source, $text);
        if(!empty(self::$config['trace_to_file'])) {
            file_put_contents(self::$config['trace_to_file'], $o . "\n", FILE_APPEND);
        }
    }

    /**
     * Get seconds since tracer factory was called (page was requested)
     * @return double
     */
    public static final function getTimer() {
        return trim(sprintf("%08.3f", 1000 * (microtime(true)-self::$timer)));
    }

    /**
     * Main class trace function
     * @param string $text
     * @param int $level
     * @return void
     */
    public static final function trace($text, $level=1) {
        if($level > self::$level || self::$instance==null) return;
        $source = '';
        if(self::$config['auto_source']) {
            $bt = debug_backtrace();
            $d  = null;
            foreach($bt as $a) {
                if(!(strtolower($a['function']) == 'trace' || !isset($a['class']) || $a['class'] == __CLASS__ || $a['class'] == 'EException')) {
                    $d = $a;
                    break;
                }
            }
            unset($bt); unset($a);
            if(is_array($d) && isset($d['function'])) {
                $c = isset($d['class']) ? $d['class'] : '';
                $source = $c . '::' . $d['function'] . '()';
                if(!empty($c)) {
                    $c = strtolower($c);
                    // Filter explicitly switched off classes
                    if(isset(self::$config['traced_classes'][$c]) && self::$config['traced_classes'][$c] === false) {
                        return;
                    }
                }
            }
        }
        self::$instance->write(trim($text), $level, $source);
    }

    /**
     * Exception tracing
     * @param Exception $e
     * @return string
     */
    public static final function traceException(&$e) {
        self::$exceptions[] = $e;
        if(self::$level<1 || self::$instance==null) return;
        $out = 'Exception("' . $e->getMessage() . '"' . ($e->getCode()!=0?(' code=' . $e->getCode()):'') . ') in ' . str_replace($_SERVER['DOCUMENT_ROOT'], '', $e->getFile()) . "@" . $e->getLine() ."\n";
        $out .= "\n" . self::backtrace($e->getTrace());
        self::$instance->write($out, 0, "");
        return $out;
    }

    /**
     * Traces uncaught exceptions (called in class EException)
     * Uncaught exceptions cause sending an email to the admin.
     * @param Exception $e
     */
    public static final function traceUncaughtException(&$e) {
        self::$hasUncaughgtException = true;
        self::traceException($e);
    }

    /**
     * Recursive tracing
     * @param mixed &$variable
     * @param string& $varname=''
     * @param int $level=1
     * @return void
     */
    public static final function trace_r(&$variable, $varname='', $level=1) {
        if($level <= self::$level && self::$instance!=null) {
            self::trace(
                "\n" . (
                (empty($varname) ? '' : $varname . '=') .
                print_r($variable, true)
                ) . '' , $level) ;
        }
    }

    /**
     * Returns a backtrace string, if no argument
     * the function uses normal backtrace
     * @param array $bt
     * @return string
     */
    public static function backtrace($bt=null) {
        if($bt==null) $bt = debug_backtrace();
        $out = '';
        foreach($bt as $a) {
            if(isset($a['class']) && $a['class'] == __CLASS__) {
                continue;
            }
            $location = '';
            if(isset($a['file'])) $location .=  trim(str_replace(': runtime-created function','', str_replace($_SERVER['DOCUMENT_ROOT'], '', $a['file'])));
            if(isset($a['line'])) $location .= '@' . $a['line'];
            $call = '';
            if(isset($a['class']))    $call .= $a['class'];
            if(isset($a['function'])) $call .= '::' . $a['function'];
            $call .= '(';
            if(isset($a['args'])) {
                $args = array();
                foreach($a['args'] as $arg) {
                    switch(gettype($arg)) {
                        case "boolean":
                            $args[] = $arg ? 'true' : 'false';
                            break;
                        case "integer":
                            $args[] = $arg;
                            break;
                        case "double":
                            $args[] = $arg;
                            break;
                        case "string":
                            if(strlen($arg) > 250) {
                                $args[] = '"' . substr($arg,0,250) . '" [...]';
                            } else {
                                $args[] = '"' . $arg . '"';
                            }
                            break;
                        case "array":
                            $args[] = "array(" . count($arg) . ")";
                            break;
                        case "object":
                            $args[] = get_class($arg);
                            break;
                        case "resource":
                            $args[] = 'resource(' . get_resource_type($arg) . ')';
                            break;
                        case "NULL":
                            $args[] = 'null';
                            break;
                        default:
                            $args[] = 'UNKNOWN';
                    }
                }
                $call .= implode(',', $args);
            }
            $call .= ')';
            $out  .= sprintf("%-30s %s\n", $location, $call);
        }
        return $out;
    }

    /**
     * Traces user defined variables fetched with function get_defined_vars
     * (no globals, session, getm post ...)
     */
    public static function traceDefinedVariables(array $get_defined_vars) {
        $ignore = array('GLOBALS' => '','_ENV' => '','HTTP_ENV_VARS' => '',
            '_POST' => '','HTTP_POST_VARS' => '','_GET' => '','HTTP_GET_VARS' => '',
            '_COOKIE' => '','HTTP_COOKIE_VARS' => '','_SERVER' => '','HTTP_SERVER_VARS' => '',
            '_FILES' => '','HTTP_POST_FILES' => '','_REQUEST' => '','HTTP_SESSION_VARS' => '',
            '_SESSION' => ''
        );
        $get_defined_vars = array_diff_key($get_defined_vars, $ignore);
        $out  = '';
        foreach($get_defined_vars as $key => $value) {
            $out .= $key . '=' . gettype($value) . "
";
        }
        self::trace($out);
    }

    /**
     * Sets the new trace level
     * @param int $level
     */
    public static final function setLevel($level) {
        self::$level = $level;
    }

    /**
     * Returns the actual trace level.
     * @return int
     */
    public static final function getLevel() {
        return self::$level;
    }

    /**
     * Sets if the automatic trace source is automatically fetched by
     * using backtrace.
     * @param bool $enable
     * @return bool
     */
    public static final function autoSourceEnable($enable=null) {
        if(!is_null($enable)) {
            self::$config['auto_source'] = !$enable ? false : true;
        }
        return self::$config['auto_source'];
    }

    /**
     * Disables the tracer
     */
    public static final function disable() {
        self::$level = -1;
        self::$output = array();
        self::$context = array();
    }

    /**
     * Defines/returns if the user can see the trace output on the page (appended
     * in a  ... 
     * @param bool $userCanSeeTracingsOnPage
     * @return bool
     */
    public static function appendProtocol($userCanSeeTracingsOnPage=null) {
        if(!is_null($userCanSeeTracingsOnPage)) {
            self::$config['append_trace_protocol'] = $userCanSeeTracingsOnPage ? true : false;
        }
        return self::$config['append_trace_protocol'];
    }

    /**
     * Sets/returns if a class is registered as traced or not. Returns true if
     * explicitly switched on, false if explicitly switched off, null otherwise.
     * @param string $name
     * @param bool $traceIt
     * @return bool
     */
    public static function tracedClass($name, $traceIt=null) {
        $name = strtolower(trim($name));
        if(empty($name)) {
            return null;
        } else if(!is_null($traceIt)) {
            $traceIt = $traceIt ? true : false;
            self::$config['traced_classes'][$name] = $traceIt;
            return $traceIt;
        } else if(isset(self::$config['traced_classes'][$name])) {
            return self::$config['traced_classes'][$name];
        } else {
            return null;
        }
    }
}
?>

This Article is also available in Deutsch.

Error exception class

stfwi — Sun, 04 Jul 2010 16:54:47 +0000

Attached an Exception-Extension similar to ErrorException. It contains one static control function ::enable() and the required redirections to catch errors. The class has cross-references to the Tracer I implemented, but checks if the tracer class exists, so the tracer is not required per se. Unfortunately not all errors are redirected by PHP (a general problem) and hence not all catchable. Here a sample code how to use it:

Sample source code

";

trigger_error('This should only be seen in the tracer', E_USER_NOTICE);
trigger_error('This should only be seen in the tracer', E_USER_WARNING);

try {
    trigger_error('This should be catched', E_USER_ERROR);
} catch(Exception $e) {
    print "Was catched: " . $e->getMessage();
}

// This will be catched by the exception handler.
trigger_error('This should be catched', E_USER_ERROR);

print "";
?>

Class source code

In the ::enable() function the catchable errors are redirected to the ::errorCallback(), which decide if an error shall be only logged in the tracer (vor warnings, notices and assertions) or an exception shall be thrown. Uncaught exceptions are delegated to uncaughtException(), which causes a tracing and stops the script.

 array(
            E_ERROR => array('level' => E_ERROR, 'tag' => 'Error', 'tracelevel' => 0),
            E_USER_ERROR => array('level' => E_ERROR, 'tag' => 'User error', 'tracelevel' => 0),
            E_RECOVERABLE_ERROR => array('level' => E_ERROR, 'tag' => 'Recoverable error', 'tracelevel' => 0),
            E_PARSE => array('level' => E_ERROR, 'tag' => 'Parse error', 'tracelevel' => 0),
            E_CORE_ERROR => array('level' => E_ERROR, 'tag' => 'Core error', 'tracelevel' => 0),
            E_COMPILE_ERROR => array('level' => E_ERROR, 'tag' => 'Compile error', 'tracelevel' => 0),
            E_WARNING => array('level' => E_WARNING, 'tag' => 'Warning', 'tracelevel' => 3),
            E_CORE_WARNING => array('level' => E_WARNING, 'tag' => 'Core warning', 'tracelevel' => 3),
            E_USER_WARNING => array('level' => E_WARNING, 'tag' => 'User warning', 'tracelevel' => 3),
            E_COMPILE_WARNING => array('level' => E_WARNING, 'tag' => 'Compile warning', 'tracelevel' => 3),
            E_NOTICE => array('level' => E_NOTICE, 'tag' => 'Notice', 'tracelevel' => 5),
            E_USER_NOTICE => array('level' => E_NOTICE, 'tag' => 'User notice', 'tracelevel' => 5),
            E_STRICT => array('level' => E_NOTICE, 'tag' => 'Strict', 'tracelevel' => 5),
            E_DEPRECATED => array('level' => E_NOTICE, 'tag' => 'Deprecated', 'tracelevel' => 5),
            E_USER_DEPRECATED => array('level' => E_NOTICE, 'tag' => '(User) Deprecated', 'tracelevel' => 5),
        ),
        'throw_on_include_fail' => false,
        'throw_on_division_by_zero' => true,
        'warning_level' => null,
        'notice_level' => null,
    );

    /**
     * Class configuration, first parameter can be either the config array
     * (to overwrite the whole config) or a key in the existing config array.
     * In the ladder case, the $value will be set for this key.
     * @param array $config
     * @param mixed $value
     */
    public static function config($config=array(), $value=null) {
        if(is_array($config)) {
            if(isset($config['error_levels'])) {
                $levels = array_merge(self::$config['error_levels'], $config['error_levels']);
            } else {
                $levels = self::$config['error_levels'];
            }
            self::$config = array_merge(self::$config, $config);
            self::$config['error_levels'] = $levels;
        } else if($config == 'warning_level' && is_numeric($value)) {
            $c = intval($value);
            foreach(self::$config['error_levels'] as $key => $value) {
                if($value['level'] == E_WARNING) {
                    self::$config['error_levels'][$key]['tracelevel'] = $c;
                }
            }
        } else if($config == 'notice_level' && is_numeric($value)) {
            $c = intval($value);
            foreach(self::$config['error_levels'] as $key => $value) {
                if($value['level'] == E_NOTICE) {
                    self::$config['error_levels'][$key]['tracelevel'] = $c;
                }
            }
        }
    }

    /**
     * Generate en eexception if a global error is raised. Dependent on PHP, not
     * all errors will be passed to this callback, but for future these cases
     * are implemented.
     * @param int $errno
     * @param string $errstr
     * @param string $errfile
     * @param string $errline
     * @param string $context
     * @return void
     */
    public static function errorCallback($errno, $errstr, $errfile, $errline, $context) {
        $errfile = str_replace($_SERVER['DOCUMENT_ROOT'],'',$errfile);
        $e = "";
        if(isset(self::$config['error_levels'][$errno])) {
            if(self::$config['error_levels'][$errno]['type'] == E_ERROR) {
                $e = self::$config['error_levels'][$errno]['tag'];
            } else if($errno == E_WARNING) {
                $etxt = strtolower(trim($errstr));
                if(strpos($etxt, 'function.include') !== false && self::$config['throw_on_include_fail']) {
                    $errno = E_ERROR;
                    $e = "Error:";
                    $errstr = "Include failed";
                } else if(strpos($etxt, 'function.require') !== false) {
                    $errno = E_ERROR;
                    $e = "Error:";
                    $errstr = "Require failed";
                } else if(strpos($etxt, 'division by zero') !== false && self::$config['throw_on_division_by_zero']) {
                    $errno = E_ERROR;
                    $e = "Error:";
                    $errstr = "Division by zero";
                    $eclass = 'MathException';
                }
            }

            if(class_exists('Tracer')) {
                Tracer::trace(self::$config['error_levels'][$errno]['tag'] . ": $errstr ($errfile@$errline)", self::$config['error_levels'][$errno]['tracelevel']);
            }

            if($e != '') {
                $e = isset($eclass) ? new $eclass : new self();
                $e->line = $errline;
                $e->file = $errfile;
                $e->message = strip_tags($errstr);
                $e->code = $errno;
                throw $e;
            }
        }
    }

    /**
     * Global catches uncaught exceptions
     * @param Exception $e
     * @return void
     */
    public static function uncaughtException(Exception $e) {
        print "A server error occoured. 
There is an uncaught exception, which is not visible to the user and has to be handled by the developer.";
        if(class_exists('Tracer')) {
            Tracer::traceUncaughtException($e);
        }
        die;
    }

    /**
     * Callback for usage of function assert()
     * @param string $file
     * @param int $line
     * @param string $code
     */
    public static function assertCallback($file, $line, $code='') {
        if(class_exists('Tracer')) {
            Tracer::trace("Assertion failed in '$file'@$line: $code");
        }
    }

    /**
     * Initialize and enable class usage.
     * @param bool $enabled
     * @return void
     */
    public static function enable($enabled=true) {
        assert_options(ASSERT_ACTIVE, 1);
        assert_options(ASSERT_WARNING, 0);
        assert_options(ASSERT_QUIET_EVAL, 1);
        restore_error_handler();
        restore_exception_handler();
        if($enabled) {
            assert_options(ASSERT_CALLBACK, array(__CLASS__, "assertCallback"));
            set_exception_handler(array(__CLASS__, "uncaughtException"));
            set_error_handler(array(__CLASS__, "errorCallback"));
        }
    }
}
?>

This Article is also available in Deutsch.

Session management wrapper class

stfwi — Sun, 04 Jul 2010 15:27:31 +0000

The session management is designed to be a singleton, which keeps a reference to the own instance reference in a static class variable. A good reason to have a wrapper for the normal PHP session management is that you can easily re-implement this class and make it loading the session from memory cache or a MySql memory table. Use the static functions to start or stop the session, and the instance() function to access the created instance. Example:

Sample source code

regrnerateId();
} else if($rand == 2) {
    Session::instance()->destroy();
}

print "";

// Work with a session variable
$_SESSION['test'] = !isset($_SESSION['test']) ? 0 : $_SESSION['test'] + 1;

// Print some data
print "Counter           = " . $_SESSION['test'] . "\n";
print "Session id        = " . Session::instance()->id() . "\n";
print "Session name      = " . Session::instance()->getName() . "\n";
print "Session expires   = " . Session::instance()->getCacheExpireTime() . "\n";

// This function is more for anaysis purposes
print "Session save path = " . Session::instance()->getSavePath() . "\n";

// Conditionally stop the session
if($Condition_that_requires_closing_the_session) {
    Session::stop();
} else {
    // The session will be written when the object is destructed,
    // this is when the script has finished and PHP unsets all
    // variables.
}

if($rand == 1) {
    print "\n(Session id regenerated)\n";
} else if($rand == 2) {
    print "\n(Session destroyed)\n";
}

print "";
?>

Class source code

 $file) {
            $f = pathinfo($file);
            $f = str_replace('sess_', '', $f['filename']);
            $sessions[$f] = filemtime($file);
        }
        return $sessions;
    }

    /**
     * Returns the IP address of the client browser
     * @return string
     */
    public static final function getClientIpAddress() {
        if(isset($_SERVER["REMOTE_ADDR"])) return $_SERVER["REMOTE_ADDR"];
        if(isset($_SERVER["HTTP_CLIENT_IP"])) return $_SERVER["HTTP_CLIENT_IP"];
        if(getenv("HTTP_CLIENT_IP")) return getenv("HTTP_CLIENT_IP");
        if(getenv("HTTP_X_FORWARDED_FOR")) return getenv("HTTP_X_FORWARDED_FOR");
        if(getenv("REMOTE_ADDR")) return getenv("REMOTE_ADDR");
        return null;
    }

    /**
     *
     */
    public static final function getClientUserAgent() {
        $agent = strtolower($_SERVER['HTTP_USER_AGENT']);
        foreach(array(
            '/chrome/i' => 'chrome', // chrome contains the text "safari"
            '/safari/i' => 'safari',
            '/firefox/i' => 'firefox',
            '/msie/i' => 'internet-explorer',
            '/opera/i' => 'opera',
        ) as $key => $value) {
            if(preg_match($key, $agent)) {
                return $value;
            }
        }
        return null;
    }

}
?>

This Article is also available in Deutsch.

HTTP authentication class

stfwi — Sun, 04 Jul 2010 14:38:43 +0000

This class manages user HTTP authentication, which is a common, safe and simple way of user login. The instance throws an exception if the user or password is wrong. The password is given with a .htaccess-like hash (using crypt()). The static function createPassword() can be used to create a compatible password. Let’s take a look how to use the class:

Sample source code

 HttpAuthentification::createPassword('pass1'),
    'user2' => crypt('pass2')
);

// Create instance
$auth = new HttpAuthentification($users);

// Add a user after the object was instanciated
$auth->addUser('user3', HttpAuthentification::createPassword('pass3'));

// Test if the authentication is ok
try {
    $auth->requireAuthentication();
    print "Auth succeeded";
} catch(Exception $e) {
    print "Auth failed: " . $e->getMessage();
}
?>

Class source code

And here the class source code. If you use autoloading, you should move the HttpAuthentificationException class to a separate file.



 $value) {
            $this->addUser($key, $value);
        }
    }

    /**
     * Adds a user to the login list. throws Exception if user exists.
     * @param string $loginName
     * @param string $cryptedPassword
     */
    public function addUser($loginName, $cryptedPassword) {
        $loginName = strtolower($loginName);
        if(isset($this->users[$loginName])) {
            throw new Exception('User "' . $loginName . '" already exists in login list');
        } else {
            $this->users[$loginName] = $cryptedPassword;
        }
    }

    /**
     * Returns the current user.
     * @return string
     */
    public function getUser() {
        if(is_null($this->actualUser)) {
            $user = trim(strtolower($_SERVER['PHP_AUTH_USER']));
            $auth = $_SERVER['PHP_AUTH_PW'];
            if(empty($this->users[$user]) || trim($auth) == '' || crypt($auth, $this->users[$user]) != $this->users[$user]) {
                $this->actualUser = '';
            } else {
                $this->actualUser = $user;
            }
        }
        return $this->actualUser;
    }

    /**
     * Throws an Exception if the user is not authorized
     * and adds the WWW-Authenticate to signal the required
     * auth to the browser.
     */
    public function requireAuthentication() {
        if($this->getUser() == '') {
          header('WWW-Authenticate: Basic realm="My Realm"');
          header('HTTP/1.0 401 Unauthorized');
          if(trim($_SERVER['PHP_AUTH_USER']) == '' && trim($_SERVER['PHP_AUTH_PW']) == '') {
            throw new HttpAuthentificationException('User did not enter data');
          } else if(trim($_SERVER['PHP_AUTH_USER']) == '') {
            throw new HttpAuthentificationException('User name not entered');
          } else if(trim($_SERVER['PHP_AUTH_PW']) == '') {
              throw new HttpAuthentificationException('User password not entered');
          } else {
              throw new HttpAuthentificationException('User entered wrong password (' . $_SERVER['PHP_AUTH_USER'] . ')' );
          }
        }
    }
}
?>

This Article is also available in Deutsch.

Class for sending emails

stfwi — Sun, 04 Jul 2010 13:27:37 +0000

I wrote this mailer classes to have better maintenance possibilities and can use abstract contacts from wherever I want. Could be interesting for you as well :). I split it in three files (as I autoload the classes when they are needed), but you can put them all in one file as well. A usage example could be:

Sample source code

setSender(new EMailContact('My site mailer', 'mailer@example.net'));
  $mailer->setSubject('Test email');
  $mailer->setBody('Test body');
  // To:
  $mailer->addRecipient(new EMailContact('You', 'contact@example.net'));
  // Copy To:
  $mailer->addRecipient(new EMailContact('You', 'contact@example.net'), 'cc');
  // Blind Copy To:
  $mailer->addRecipient(new EMailContact('You', 'contact@example.net'), 'bcc');
  // Send it
  $mailer->send();
} catch(Exception $e) {
  print "Exception: " . $e->getMessage();
}
?>

Class source code

The first file is an interface, which is used by the Mailer class. This means you can make every user- or address book class to be used as contact class for the Mailer (see below for further information).

The contact class can be anything, even your database user class, as long you add the method toEMailAddressString() {} and say implements IEMailContact. So this class is only a “default” contact …

name;
    }

    /**
     * Name setter
     * @param string $name
     */
    public function setName($name) {
        if(!isset($name) || $name == "") {
            throw new Exception("Name of email contact is invalid");
        }
        $this->name = $name;
    }

    /**
     * EMail address getter
     * @return string
     */
    public function getEMailAddress() {
        return $this->address;
    }

    /**
     * EMail address setter
     * @param string $address
     */
    public function setEMailAddress($address) {
        if(!isset($address) || $address == "") {
            throw new Exception("EMail addresss is invalid");
        } else if(!eregi("^[_a-z0-9-]+(\.[_a-z0-9-]+)*@[a-z0-9-]+(\.[a-z0-9-]+)*(\.[a-z]{2,3})$", $address)) {
            throw new Exception("EMail addresss is invalid");
        }
        $this->name = $address;
    }

    /**
     * Nonmagic string representator
     * @return string
     */
    public function toEMailAddressString() {
        return $this->name . " <" . $this->address . ">";
    }

    /**
     * EMailContact constructor
     * @param string $name
     * @param string $address
     */
    public function __construct($name="", $address="") {
        $this->name 	= $name;
        $this->address = $address;
    }

    public function __toString() {
      return $this->toEMailAddressString();
    }

}
?>

… and the mailer class itself. Note that the Mailer does not check if the email addresses are correct, because this should be done in the contact class. Otherwise there could be a discrepancy where the user class says the email is correct but the mailer would throw an exception.

 64) {
                return false;
            } else if(strlen($domain) > 255) {
                return false;
            } else if(preg_match('/[!\.-]{2}/', $domain)) {
                return false;
            } else if(preg_match('/[!\.-]{2}/', $email)) {
                return false;
            } else if(!preg_match('/^[A-Za-z0-9\\-\\.]+$/', $domain)) {
                return false;
            } else if(!preg_match('/^(\\\\.|[A-Za-z0-9!#%&`_=\\/$\'*+?^{}|~.-])+$/', str_replace("\\\\", '', $email)) && !preg_match('/^"(\\\\"|[^"])+"$/', str_replace("\\\\", '', $email))) {
                return false;
            } else if($lookupDomain && !(checkdnsrr($domain, "MX") || checkdnsrr($domain, "A"))) {
                return false;
            }
            return true;
        }
    }

    /**
     * Constructor
     */
    public function __construct() {
    }

    /**
     * Get server name/ip
     * @return string
     */
    public function getServer()	{
        return $this->server;
    }

    /**
     * Sets server name and port
     * @param string $server
     */
    public function setServer($server) {
        $this->server = $server;
        settype($this->server, "string");
    }

    /**
     * Login user getter
     * @return string
     */
    public function getUser() {
        return $this->user;
    }

    /**
     * Sets the login user
     * @param string $user
     */
    public function setUser($user) {
        $this->user = $user;
        settype($this->user, "string");
    }

    /**
     * Login password getter
     * @return string
     */
    public function getPassword() {
        return $this->password;
    }

    /**
     * Login password setter
     * @param string $password
     */
    public function setPassword($password) {
        $this->password = $password;
        settype($this->password, "string");
    }

    /**
     * Add recipient, $cc can be 'CC' or 'BCC'
     * @param IEMailContact $contact
     * @param string $cc=''
     */
    public function addRecipient(IEMailContact $contact, $cc='') {
        $cc = empty($cc) ? '' : trim(strtolower($cc));
        if($contact == null) {
            throw new Exception("Recipient to add is not specified");
        } else if(!empty($cc) && $cc != 'cc' && $cc != 'bcc') {
            throw new Exception('CC/BCC for Recipient to add must be specified with "CC" or "BCC"');
        } else {
            $this->recipients[] = $contact;
            if(!empty($cc)) {
                $this->ccs[$contact->toEMailAddressString()] = $cc;
            }
        }
    }

    /**
     * Recipient getter
     * @return array of IEMailContact
     */
    public function getRecipients() {
        return $this->recipients;
    }

    /**
     * Recipient getter with index
     * @return IEMailContact
     */
    public function getRecipient($index=0) {
        if(!array_key_exists($index, $this->recipients)) {
            throw new Exception("Invalid index '$index'");
        } else {
            return $this->recipients[$index];
        }
    }

    /**
     * Sender getter
     * @return IEMailContact
     */
    public function getSender()	{
        return $this->sender;
    }

    /**
     * Sender setter
     * @param string $name
     */
    public function setSender(IEMailContact $contact)	{
        if($contact == null) {
            throw new Exception("Argument is not an IEMailContact");
        } else {
            $this->sender = $contact;
        }
    }

    /**
     * eMail subject getter
     * @return string
     */
    public function getSubject() {
        return $this->subject;
    }

    /**
     * eMail subject setter
     * @param string $subject
     */
    public function setSubject($subject) {
        $this->subject = $subject;
        settype($this->subject, "string");
    }

    /**
     * eMail body getter
     * @return string
     */
    public function getBody() {
        return $this->body;
    }

    /**
     * eMail body setter
     * @param string $body
     */
    public function setBody($body) {
        $this->body = $body;
        settype($this->body, "string");
    }

    /**
     * Content type getter
     * @return string
     */
    public function getContentType() {
        return $this->contentType;
    }

    /**
     * Sets content type, only text/plain and text/html allowed.
     * @return void
     */
    public function setContentType($type) {
        $type = strtolower($type);
        if($type != "text/plain" && $type != "text/html") {
            throw new Exception("Only 'text/plain' or 'text/html' allowed");
        } else {
            $this->contentType = $type;
        }
    }

    /**
     * Use $this as default for all constructed mailers
     * @return void
     */
    public function setAsTemplate() {
        $ta = $this->recipients;
        $this->recipients = array();
        self::$template = clone $this;
        $this->recipients = $ta;
    }

    /**
     * Returns array with header, subject, body
     * @return array
     */
    public function getContents() {
        if(trim($this->getSubject()) == "") {
            throw new Exception("No subject specified.");
        } else if(trim($this->getBody()) == "") {
            throw new exception("Empty body.");
        } else if(is_null($this->getSender())) {
            throw new exception("Sender not specified");
        } else if(count($this->getRecipients()) == 0) {
            throw new exception("No recipients defined.");
        } else {
            $from = $this->getSender()->toEMailAddressString();
            if(count($this->getRecipients()) < 2) {
                $to = $this->getRecipient()->toEMailAddressString();
                $cc = $bcc = '';
            } else {
                $to  = $cc = $bcc = array();
                foreach($this->getRecipients() as $recip) {
                    $recip = $recip->toEMailAddressString();
                    if(isset($this->ccs[$recip]) && $this->ccs[$recip] == 'cc') {
                        $cc[] = $recip;
                    } else if(isset($this->ccs[$recip]) && $this->ccs[$recip] == 'bcc') {
                        $bcc[] = $recip;
                    } else {
                        $to[] = $recip;
                    }
                }
                $to  = implode(', ', $to);
                $cc  = empty($cc)  ? '' : 'Cc: '  . implode(', ', $cc)  . "\r\n";
                $bcc = empty($bcc) ? '' : 'Bcc: ' . implode(', ', $bcc) . "\r\n";
            }

            if(empty($to)) {
                throw new Exception('Email has no primary recipient (TO:)');
            } else {
                if(empty($this->contentType)) {
                    $this->contentType = 'text/plain';
                }
                $header  = "";
                $header .= "Content-Type: ". $this->getContentType() . "; charset=ISO-8859-15; format=flowed" . "\r\n";
                $header .= "Content-Transfer-Encoding: 8bit\r\n";
                $header .= "MIME-Version: 1.0" . "\r\n";
                $header .= "X-Accept-Language: de-de, de, en-us, en" . "\r\n";
                $header .= "From: $from\r\n";
                // To is handled in the mail function $header .= "To: $to\r\n";
                $header .= $cc . $bcc;
                $subject = $this->getSubject() ."\r\n";
                $content = array();
                $content["to"] 	= $to;
                $content["cc"] 	= $cc;
                $content["bcc"] = $bcc;
                $content["header"] 	= $header;
                $content["subject"]	= $subject;
                $content["body"]	= $this->getBody();
                return $content;
            }
        }
    }

    /**
     * Get email content to be sent
     * @return string
     */
    public function dump() { // getMailContent()
        $mail = $this->getContents();
        return $mail["header"] . "\n\n" . $mail["subject"] . "\n\n" . $mail["body"] . "\n";
    }

    /**
     * Sends the eMail
     * @return array succeeded posts
     */
    public function send() {
        $mail = $this->getContents();
        if(!mail($mail['to'], $mail["subject"], $mail["body"], $mail["header"])) {
            throw new Exception("Could not send mail to recipients.");
        }
        Tracer::trace("EMail sent:\n" . print_r($mail, true) ."\n");
    }
}
?>

This Article is also available in Deutsch.

Output buffering class

stfwi — Sun, 04 Jul 2010 11:38:09 +0000

This is a class is for having the output buffer well organized. Note that it uses the Tracer class, including the ITracable interface. You can remove these functions from the source code if you want …

Class source code

getContents();
 *
 * @package de.atwillys.sw.php.swLib
 * @author Stefan Wilhelm
 * @copyright Stefan Wilhelm, 2005-2010
 * @license GPL
 * @version 1.0
 * @uses Tracer
 */
class OutputBuffer implements ITracable {

    /**
     * Main instance
     * @staticvar OutputBuffer
     */
    private static $instance;

    /**
     * Defines if buffer is shown or dumped (trashed)
     *
     * @property bool
     */
    private $noOutput = false;

    /**
     * Defines the buffer level when the ob was started.
     * @property int
     */
    private $level = 0;

    /**
     * The callback function, overload this if you want to modify the buffer.
     * This function returns null to indicate that the output buffer callback
     * is not used.
     * $param string $buffer
     * @return string
     */
    public function onEnd($buffer='') {
        return null;
    }

    /**
     * Starts output control
     * @return void
     */
    public static final function start() {
        self::$instance = new self();
        self::trace("started");
    }

    /**
     * Aborts all buffers and sents the output
     * @return void
     */
    public static final function abort() {
        while(@ob_get_level() > 0) @ob_end_flush();
    }

    /**
     * Aborts all buffers without sending it. Instead the output
     * is returned as string.
     * @return string
     */
    public static final function purge() {
        $out = '';
        while(@ob_get_level() > 0) {
            $out .= @ob_get_clean();
        }
        return $out;
    }

    /**
     * Aborts all buffers without sending it. Instead the output
     * is returned as string.
     * @return string
     */
    public static final function disable() {
        return self::abort();
    }

    /**
     * Execute a PHP code in a level 2++ buffer. Restores buffering to level 1
     * @param string $code
     * @return string
     */
    public static final function executeBuffered($code) {
        $exception = null;
        $buffer = new self();
        try {
            $result = eval($code);
        } catch(Exception $e) {
            $exception = $e;
            $result = "Block exception thrown

$exception";
        }
        $result .= $buffer->getOutput();
        unset($buffer);
        if($exception != null) {
            throw $exception;
        } else {
            return $result;
        }
    }

    /**
     * Controller object construction, start level 1 buffer
     * @param bool $noOutput=false
     */
    public final function __construct($noOutput=false) {
        $this->noOutput = $noOutput;
        if(!is_null($this->onEnd())) {
            ob_start(array($this, 'onEnd'));
        } else {
            ob_start();
        }
        $this->level = ob_get_level();
        self::trace("New buffer, level " . $this->level, 3);
    }

    /**
     * Controller object destruction, flushes and writes all higher buffer level outputs than level at construction time.
     */
    public final function __destruct() {
        $out = '';
        if(ob_get_level() > $this->level) {
            self::trace("Buffer level(" . ob_get_level() . ", construction level=" . $this->level . ") not ok , flushing ");
            while(ob_get_level() > $this->level) {
                self::trace("Level now " . ob_get_level());
                $out .= ob_get_clean();
            }
            self::trace("Buffer destructed, level " . $this->level . " actual level " . ob_get_level());
        } else {
            self::trace("ok, already read level " . $this->level, 3);
        }
        if($this->noOutput) print $out; // ob_get_clean
    }

    /**
     * Returns the buffered output text.
     * @return string
     */
    public final function getOutput() {
        if($this->level != ob_get_level()) {
            self::trace("Warning: Actual buffer level (" . ob_get_level() . ") is deeper than this construction level (".$this->level.")");
            return "[Buffer level not ok]";
        } else {
            return ob_get_clean();
        }
    }

    /**
     * Private tracing method
     * @param string $text
     * @param int $level
     */
    protected function trace($text, $level=1) {
        if(!Tracer::tracedClass(__CLASS__)) return;
        Tracer::trace($text, $level);
    }
}
?>

This Article is also available in Deutsch.

UTC date class

stfwi — Sun, 04 Jul 2010 11:27:53 +0000

Here a “convenience class cluster” for UTC dates, local dates and the interface IDate, which is implemented from both UtcDate and LocalDate

Class source code



mTimeStamp = strtotime(gmdate("M d Y H:i:s", time()));
        } else if($datetime instanceof IDate) {
            $this->mTimeStamp = $datetime->getTimeStamp();
        } else if(is_numeric($datetime)) {
            $this->mTimeStamp = strtotime(gmdate("M d Y H:i:s", $datetime));
        } else if(!is_string($datetime)) {
            throw new Exception('Date format is not valid');
        } else {
            $t = strtotime($datetime);
            if($t === false) {
                throw new Exception('Cannot parse the passed date text');
            } else {
                $this->mTimeStamp = strtotime(gmdate("M d Y H:i:s", $t));
            }
        }
        $this->update();
    }

    /**
     * Updates properties by timestamp
     * @return void
     */
    protected function update() {
        $dt = getdate($this->mTimeStamp);
        $this->mSecond 		= $dt['seconds'];
        $this->mMinute 		= $dt['minutes'];
        $this->mHour 		= $dt['hours'];
        $this->mDay 		= $dt['mday'];
        $this->mMonth 		= $dt['mon'];
        $this->mYear 		= $dt['year'];
        $this->mWeekDay 	= $dt['wday'] < 1 ? 7 : $dt['wday'];
    }

    /**
     * Updates timestamp by properties
     * @return void
     */
    protected function updateTimeStamp() {
        $this->mTimeStamp = mktime($this->mHour,$this->mMinute,$this->mSecond,$this->mMonth,$this->mDay,$this->mYear, 0);
    }

    /**
     * Returns format "YYYY-MM-DD HH:MM:SS GMT"
     * @return string
     */
    public function toString() {
        return sprintf("%4d-%02d-%02d %02d:%02d:%02d %3s",
            $this->getYear(),
            $this->getMonth(),
            $this->getDay(),
            $this->getHour(),
            $this->getMinute(),
            $this->getSecond(),
            $this->getTimeZoneName()
        );
    }

    /**
     * Returns format  "YYYY-MM-DD"
     * @return string
     */
    public function toDateString() {
        return sprintf("%4d-%02d-%02d",
            $this->getYear(),
            $this->getMonth(),
            $this->getDay()
        );
    }

    /**
     * Returns format "HH:MM::SS"
     * @return string
     */
    public function toTimeString() {
        return sprintf("%02d:%02d:%02d",
            $this->getHour(),
            $this->getMinute(),
            $this->getSecond()
        );
    }

    /**
     * Returns format "YYYY-MM-DD HH:MM GMT"
     * @return string
     */
    public function __toString() {
        return $this->toString();
    }

    /**
     * Returns year
     * @return int
     */
    public function getYear() {
        return $this->mYear;
    }

    /**
     * Returns month
     * @return int
     */
    public function getMonth() {
        return $this->mMonth;
    }

    /**
     * Returns day
     * @return int
     */
    public function getDay() {
        return $this->mDay;
    }

    /**
     * Returns hour
     * @return int
     */
    public function getHour() {
        return $this->mHour;
    }

    /**
     * Returns minute
     * @return int
     */
    public function getMinute() {
        return $this->mMinute;
    }

    /**
     * Returns second
     * @return int
     */
    public function getSecond() {
        return $this->mSecond;
    }

    /**
     * Returns unix time stamp
     * @return int
     */
    public function getTimeStamp() {
        return $this->mTimeStamp;
    }

    /**
     * Returns the time zone abbreciation
     * @return string
     */
    public function getTimeZoneName() {
        return "GMT";
    }

    /**
     * Returns weekday
     * @return int
     */
    public function getWeekDay() {
        return $this->mWeekDay;
    }

    /**
     * Sets year
     * @param int $year
     */
    public function setYear($year) {
        $this->mYear = $year;
        $this->updateTimeStamp();
    }

    /**
     * Sets month
     * @param int $month
     */
    public function setMonth($month) {
        $this->mMonth = $month;
        $this->updateTimeStamp();
    }

    /**
     * Sets day
     * @param int $day
     */
    public function setDay($day) {
        $this->mDay = $day;
        $this->updateTimeStamp();
    }

    /**
     * Sets hour
     * @param int $hour
     */
    public function setHour($hour) {
        $this->mHour = $hour;
        $this->updateTimeStamp();
    }

    /**
     * Sets minute
     * @param int $minute
     */
    public function setMinute($minute) {
        $this->mMinute = $minute;
        $this->updateTimeStamp();
    }

    /**
     * Sets second
     * @param int $second
     */
    public function setSecond($second) {
        $this->mSecond = $second;
        $this->updateTimeStamp();
    }

    /**
     * Sets the timestamp
     * @param int $timestamp
     */
    public function setTimeStamp($timestamp) {
        $this->mTimeStamp = $timestamp;
        $this->update();
    }

    /**
     * Changes all properties != null and updates time stamp
     * @param int $year
     * @param int $month
     * @param int $day
     * @param int $hour
     * @param int $minute
     * @param int $second
     * @return void
     */
    public function setSerial($year=null, $month=null, $day=null, $hour=null, $minute=null, $second=null) {
        if($year  !== null) $this->mYear   = $year;
        if($month !== null) $this->mMonth  = $month;
        if($day   !== null) $this->mDay    = $day;
        if($hour  !== null) $this->mHour   = $hour;
        if($minute!== null) $this->mMinute = $minute;
        if($second!== null) $this->mSecond = $second;
        $this->updateTimeStamp();
    }

    /**
     * Returns this - another date, object is not affected, $date can also be
     * a timestamp or period in seconds
     * @param IDate $date
     * @return UtcDate
     */
    public function substract($date) {
        $class = get_class($this);
        if(is_numeric($date)) {
            return new $class($this->getTimeStamp() - intval($date));
        } else if($date instanceof IDate) {
            return new $class($this->getTimeStamp() - $date->getTimeStamp());
        } else {
            throw new Exception('Only timestamps or IDate can be substracted from an IDate');
        }
    }

    /**
     * Returns this + another date, object is not affected, $date can also be
     * a timestamp or a period in seconds
     * @param IDate $date
     * @return UtcDate
     */
    public function add($date) {
        $class = get_class($this);
        if(is_numeric($date)) {
            return new $class($this->getTimeStamp() + intval($date));
        } else if($date instanceof IDate) {
            return new $class($this->getTimeStamp() + $date->getTimeStamp());
        } else {
            throw new Exception('Only timestamps or IDate can be added to an IDate');
        }
    }

    /**
     * Returns the date/time from stamp in days
     * @return double
     */
    public function inWeeks() {
        return round($this->getTimeStamp() / 604800.0, 2);
    }

    /**
     * Returns the date/time from stamp in days
     * @return double
     */
    public function inDays() {
        return round($this->getTimeStamp() / 86400.0, 2);
    }

    /**
     * Returns the date/time from stamp in hours
     * @return double
     */
    public function inHours() {
        return round($this->getTimeStamp() / 3600.0, 2);
    }

    /**
     * Returns the date/time from stamp in hours
     * @return double
     */
    public function inMinutes() {
        return round($this->getTimeStamp() / 60.0, 2);
    }

    /**
     * Returns the date/time from stamp in seconds
     * @return double
     */
    public function inSeconds() {
        return $this->getTimeStamp();
    }

    /**
     * Returns next 'month','day','hour','minute','second'.
     * Next month of 2008-01-24 13:12:14 returns 2008-02-01 00:00:00
     * @return UtcDate
     */
    public function getNext($unit='second') {
        $unit = strtolower(trim($unit, " \n\r\t"));
        $year=null; $month=null; $day=null; $hour=null; $minute=null; $second=null;
        // Do not insert breaks here ...
        switch($unit) {
            case 'month':
                $day=1;
            case 'week':
            case 'day':
            case 'sunday':
            case 'monday':
            case 'tuesday':
            case 'wednesday':
            case 'thursday':
            case 'friday':
            case 'saturday':
                $hour=0;
            case 'hour':
                $minute=0;
            case 'minute':
                $second=0;
            case 'second':
                break;
            default:
                throw new Exception("argument unit is not valid: '$unit'");
        }
        $class = get_class($this);
        $d = new $class(strtotime("next $unit", $this->getTimeStamp()));
        $d->setSerial($year,$month,$day,$hour,$minute,$second);
        return $d;
    }

    /**
     * Returns last 'month','day','hour','minute','second'.
     * Next last of 2008-01-24 13:12:14 returns 2007-12-01 00:00:00
     * @return UtcDate
     */
    public function getLast($unit='second') {
        $unit = strtolower(trim($unit, " \n\r\t"));
        $year=null; $month=null; $day=null; $hour=null; $minute=null; $second=null;
        // Do not insert breaks here ...
        switch($unit) {
            case 'month':
                $day=1;
            case 'week':
            case 'day':
            case 'sunday':
            case 'monday':
            case 'tuesday':
            case 'wednesday':
            case 'thursday':
            case 'friday':
            case 'saturday':
                $hour=0;
            case 'hour':
                $minute=0;
            case 'minute':
                $second=0;
            case 'second':
                break;
            default:
                throw new Exception("argument unit is not valid: '$unit'");
        }
        $class = get_class($this);
        $d = new $class(strtotime("last $unit", $this->getTimeStamp()));
        $d->setSerial($year,$month,$day,$hour,$minute,$second);
        return $d;
    }

}
?>

mTimeStamp = time();
        } else if(is_numeric($datetime))	{
            $this->mTimeStamp = intval($datetime);
        } else if($datetime instanceof IDate) {
            $this->mTimeStamp = $datetime->getTimeStamp();
        } else if(!is_string($datetime)) {
            throw new Exception('Date format is not valid');
        } else {
            $t = strtotime($datetime);
            if($t === false) {
                throw new Exception('Cannot parse the passed date text');
            } else {
                $this->mTimeStamp = $t;
            }
        }
        $this->update();
    }

    /**
     * Returns the time zone abbreciation
     * @return string
     */
    public function getTimeZoneName() {
        return trim(strtoupper(date("T", $this->mTimeStamp)));
    }

    /**
     * Updates timestamp by properties
     * @return void
     */
    protected function updateTimeStamp() {
        $this->mTimeStamp = mktime($this->mHour,$this->mMinute,$this->mSecond,$this->mMonth,$this->mDay,$this->mYear, -1);
    }
}
?>

This Article is also available in Deutsch.

SEES source code and MacOS 10.6 binary available

stfwi — Thu, 01 Jul 2010 20:12:36 +0000

The page with the binary, source code, introduction and reference is available: You can find it here.

Zip a file or directory

stfwi — Thu, 01 Jul 2010 17:22:37 +0000

function zip(path, zipfile) {
	if(!path || path.toString().trim() == '') {
		throw new Error("No file/directory to zip given");
	} else if(!exist(path)) {
		throw new Error("File/Directory to zip not exist: " + path);
	} else if(!zipfile || zipfile.toString().trim() == '') {
		throw new Error("No zip file given to compress \"" + path + "\"");
	} else if(exist(zipfile)) {
		throw new Error("Zip file already exists:" + zipfile);
	} else {
		var here = pwd();
		try {
			cd(dirname(path));
			var r = exec("zip" + (isdir(path) ? " -r" : "") + " -o -9 " + zipfile + "  " + basename(path));
			cd(here);
		} catch(e) {
			cd(here);
			throw e;
		}

		if(r.exitcode != 0) {
			throw new Error("zip tool failed: " + r.stderr);
		}
	}
}

Remove .DS_Store files

stfwi — Thu, 01 Jul 2010 17:14:29 +0000

function removeDS_Store(path) {
	if(!path || path.toString().trim() == '') {
		throw new Error("No directory to remove .DS_Store given");
	} else if(!isdir(path)) {
		throw new Error("Directory to remove .DS_Store does not exist: " + path);
	} else {
		var files = ls(path + '/*', true, true);
		for(var i=0; i

Base64 encoder/decoder class

stfwi — Fri, 25 Jun 2010 20:47:36 +0000

This is a small class for encoding and decoding base64 streams.

Header file:

#ifndef __BASE_64_STREAM__HPP__
#define __BASE_64_STREAM__HPP__

#include 
#include 
#include 

namespace sw {
    namespace codec {

        class base64 {
        public:

            size_t max_decode_size(const std::string & s) const;
            bool encode(const std::string & s_in, std::string & s_out) const;
            bool decode(const std::string & s_in, std::string & s_out) const;
            bool encode(const void* si, size_t len, std::string & s) const;
            bool decode(const std::string & s, void* so, size_t max_so, size_t *n_so_converted) const;

        private:

            inline bool encode3to4(const unsigned char* c3, char* c4) const {
                c4[0] = _emap[ (unsigned char) (((c3[0] & 0xfc) >> 2)) ];
                c4[1] = _emap[ (unsigned char) (((c3[0] & 0x03) << 4) + ((c3[1] & 0xf0) >> 4)) ];
                c4[2] = _emap[ (unsigned char) (((c3[1] & 0x0f) << 2) + ((c3[2] & 0xc0) >> 6)) ];
                c4[3] = _emap[ (unsigned char) (((c3[2] & 0x3f))) ];
                return true;
            }

            inline bool decode4to3(const char* c4i, unsigned char* c3) const {
                unsigned char c4[4];
                for (int i = 0; i < 4; i++) {
                    c4[i] = _dmap[ (unsigned char) c4i[i]];
                } // printf("%c->%02x|", c4i[i], c4[i], c4[i]);
                c3[0] = (((c4[0] << 2)) + ((c4[1] & 0x30) >> 4));
                c3[1] = (((c4[1] & 0xf) << 4) + ((c4[2] & 0x3c) >> 2));
                c3[2] = (((c4[2] & 0x3) << 6) + ((c4[3])));
                return c4[0] < 0xfa && c4[1] < 0xfa && c4[2] < 0xfa && c4[3] < 0xfa;
            }

            static const char _emap[64];
            static const unsigned char _dmap[256];
        };
    }
};

#endif

Implementation file:

#include 

const char sw::codec::base64::_emap[64] = {
    0x41,0x42,0x43,0x44,0x45,0x46,0x47,0x48,0x49,0x4a,0x4b,0x4c,0x4d,0x4e,0x4f,0x50,
    0x51,0x52,0x53,0x54,0x55,0x56,0x57,0x58,0x59,0x5a,0x61,0x62,0x63,0x64,0x65,0x66,
    0x67,0x68,0x69,0x6a,0x6b,0x6c,0x6d,0x6e,0x6f,0x70,0x71,0x72,0x73,0x74,0x75,0x76,
    0x77,0x78,0x79,0x7a,0x30,0x31,0x32,0x33,0x34,0x35,0x36,0x37,0x38,0x39,0x2b,0x2f
};

const unsigned char sw::codec::base64::_dmap[256] = {
    0xfc,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xfe,0xfe,0xfe,0xfe,0xfe,0xff,0xff,
    0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,
    0xfe,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0x3e,0xff,0xff,0xff,0x3f,
    0x34,0x35,0x36,0x37,0x38,0x39,0x3a,0x3b,0x3c,0x3d,0xff,0xff,0xff,0xfd,0xff,0xff,
    0xff,0x00,0x01,0x02,0x03,0x04,0x05,0x06,0x07,0x08,0x09,0x0a,0x0b,0x0c,0x0d,0x0e,
    0x0f,0x10,0x11,0x12,0x13,0x14,0x15,0x16,0x17,0x18,0x19,0xff,0xff,0xff,0xff,0xff,
    0xff,0x1a,0x1b,0x1c,0x1d,0x1e,0x1f,0x20,0x21,0x22,0x23,0x24,0x25,0x26,0x27,0x28,
    0x29,0x2a,0x2b,0x2c,0x2d,0x2e,0x2f,0x30,0x31,0x32,0x33,0xff,0xff,0xff,0xff,0xff,
    0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,
    0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,
    0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,
    0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,
    0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,
    0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,
    0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,
    0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff,0xff
};

size_t sw::codec::base64::max_decode_size(const std::string & s) const
{
    return s.length() * 3 / 4 + 1;
}

bool sw::codec::base64::encode(const std::string & s_in, std::string & s_out) const
{
    return encode(s_in.c_str(), s_in.length()-1, s_out);
}

bool sw::codec::base64::decode(const std::string & s_in, std::string & s_out) const
{
    if(s_in.empty()) {
        s_out = "";
        return true;
    } else {
        size_t len = max_decode_size(s_in)+1;
        char* s_c = new char[len];
        if(s_c) {
            if(decode(s_in, s_c, len, &len)) {
                s_c[len] = '\0';
                s_out = s_c;
                delete [] s_c;
                return true;
            } else {
                s_out = "";
                delete [] s_c;
                return false;
            }
        } else {
                return false;
        }
    }
}

bool sw::codec::base64::encode(const void* si, size_t len, std::string & s) const
{
    if(!si) {
            return false;
    } else  if(len==0) {
            return true;
    } else {
        std::stringstream so;
        char c4[4];
        const unsigned char* pi = (unsigned char*) si;					// byte stepped pointer
        const unsigned char* pe = (unsigned char*) si+len;				// end pointer
        const unsigned char* pm = (unsigned char*) si+(len-(len%3));	// loop end pointer
        unsigned int  i=0;
        while(pipm) {
            unsigned char c3[3];
            for(i=0; i<(len%3); i++) c3[i] = *(pi++);
            while(i<4) c3[i++] = '\0';
            encode3to4(c3,c4);
            for(i=0; i<(len%3)+1; i++) so << c4[i];
            while(i++<4) so << "=";
        }
        s = so.str();
        return true;
    }
    return false;
}

bool sw::codec::base64::decode(const std::string & s, void* so, size_t max_so, size_t *n_so_converted) const
{
    (*n_so_converted) = 0; // do not check error, the programmer has to treat access violations here
    if(max_so < max_decode_size(s)) return false;
    const char* pi = (const char*) s.c_str();		// input iteration pointer
    const char*  pe = (const char*) pi+s.length();	// input iteration end() pointer
    unsigned char* po = (unsigned char*) so;		// output (iterated) pointer
    bool isend = false;
    while(pi

This Article is also available in Deutsch.

ZIP file wrapper class

stfwi — Thu, 24 Jun 2010 14:10:33 +0000

I was a little bit fed up with the situation that I have to organize too much around the ZipArchive class. So, here is a wrapper for this class, which applies to the usual tasks you have for zip files (compress recursive, extract recursive, look what’s inside etc.). The class ZipFile does not return error, but instead throws exceptions, which is (so I think) more elaborated. Notice, that if you should put the ZipException in a separate file for autoloading. File contents of ZipException.class.php and ZipFile.class.php:

Class source code



zip = new ZipArchive();
    }

    /**
     * Destructor
     */
    public final function __destruct() {
        $this->close();
    }

    /**
     * Throws an ZipException according to the occurred ZipArchive
     * error code.
     * @static
     * @param int $zipArchiveErrorCode
     * @throws ZipException
     * @return void
     */
    private static final function throwZipException($zipArchiveErrorCode) {
        switch($zipArchiveErrorCode) {
            case ZIPARCHIVE::ER_EXISTS:
                throw new ZipException('Zip file already exists');
            case ZIPARCHIVE::ER_OPEN:
                throw new ZipException('Failed to open zip file');
            case ZIPARCHIVE::ER_READ:
                throw new ZipException('Could not read zip file');
            case ZIPARCHIVE::ER_INCONS:
                throw new ZipException('Zip file inconsistent');
            case ZIPARCHIVE::ER_INVAL:
                throw new ZipException('Zip file invalid');
            case ZIPARCHIVE::ER_MEMORY:
                throw new ZipException('Not enough memory to handle zip file');
            case ZIPARCHIVE::ER_NOENT:
                throw new ZipException('Zip file has no entries');
            case ZIPARCHIVE::ER_NOZIP:
                throw new ZipException('File is no zip file');
            case ZIPARCHIVE::ER_SEEK:
                throw new ZipException('Could seek the position in zip file');
            default:
                throw new ZipException('Unknown error occurred handling zip file');
        }
    }

    /**
     * Generates a new zip file from a file or a folder. Folders are
     * compressed recursively.
     * @param string $fileOrFolder
     * @param string $zipArchive
     * @return string
     */
    public static function compress($fileOrFolder, $zipArchive) {
        $zip = new self();
        $zip->create($zipArchive);
        try {
            $zip->add($fileOrFolder);
        } catch(Exception $e) {
            $zip->close();
            @unlink($zipArchive);
            throw $e;
        }
        $zip->close();
        return realpath($zipArchive);
    }

    /**
     * Extracts a file or folder to a specified location folder.
     * The folder must exist before extracting
     * @param string $zipArchive
     * @param string $folder
     */
    public static function extract($zipArchive, $folder) {
        if(!is_dir($folder)) {
            throw new ZipException('Directory to extract to does not exist');
        } else {
            $zip = new self();
            $zip->open($zipArchive);
            $e = $zip->zip->extractTo($folder);
            if(!$e) {
                $zip->close();
                throw new ZipException('Failed to extract files');
            }
            $zip->close();
        }
    }

    /**
     * Returns an assoc. array containing the list of all entries in the zip archive.
     * Each entry is an assoc. array that contains details about the file/folder.
     * @return array
     */
    public static function contents($zipArchive) {
        $zip = new self();
        $zip->open($zipArchive);
        $l = $zip->getContentList();
        $zip->close();
        return $l;
    }

    /**
     * Opens a zip file for manipulation and returns
     * the ZipFile object for the opened file.
     * @param string $file
     * @throws ZipException
     * @return void
     */
    public function open($file) {
        if(!is_file($file)) {
            throw new ZipException('Zip file to open does not exist');
        } else if(!is_readable($file)) {
            throw new ZipException('Zip file to open is not readable');
        } else {
            $e = $this->zip->open($file);
            if($e !== true) {
                self::throwZipException($e);
            }
        }
    }

    /**
     * Creates and opens a zip file for manipulation and returns
     * the ZipFile object for the created file.
     * @static
     * @param string $file
     * @throws ZipException
     * @return void
     */
    public function create($file) {
        if(is_file($file)) {
            throw new ZipException('Zip file to create already exists');
        } else {
            $e = $this->zip->open($file, ZipArchive::CREATE);
            if($e !== true) {
                self::throwZipException($e);
            }
        }
    }

    /**
     * Closes the zip file
     */
    public function close() {
        try {
            @$this->zip->close();
        } catch(Exception $e) {
            // ignore here
        }
    }

    /**
     * Adds a file or a directory (recursive) to the zip archive. The $basePath
     * indicates the root directory of the archive. If e.g. $pathToFileOrDir
     * is "/tmp/folder1/folder2/file.txt" and $basePath is "/tmp/folder1", then
     * the file.txt will be in the archive as "/folder2/file.txt".
     * @param string $pathToFileOrDir
     * @param string $basePath
     */
    public function add($pathToFileOrDir, $basePath=null) {
        $pathToFileOrDir = trim($pathToFileOrDir);
        $basePath = trim($basePath);
        Tracer::trace("add '$pathToFileOrDir', basepath '$basePath'");

        if(!is_file($pathToFileOrDir) && !is_dir($pathToFileOrDir)) {
            throw new ZipException('File or directory to add does not exist in file system');
        } else {
            if(empty($basePath)) {
                // Assume that the file/directory is to be added to the zip root
                $basePath = dirname($pathToFileOrDir);
            }
            if(stripos($pathToFileOrDir, $basePath) === false) {
                throw new ZipException('The path to the file or directory must include base path');
            }

            // Create local path for zip
            if(is_file($pathToFileOrDir)) {
                $localPath = str_ireplace($basePath, '', $pathToFileOrDir);
                // Check if the directory structure already exist in the zip file
                if(dirname($localPath) != '') {
                    $e = $this->zip->addEmptyDir(dirname($localPath));
                    if($e !== true && $e != ZipArchive::ER_EXISTS) {
                        self::throwZipException($e);
                    }
                }
                // Finally add the file
                $e = $this->zip->addFile($pathToFileOrDir, $localPath);
                if($e !== true) {
                    self::throwZipException($e);
                }
            } else if(is_dir($pathToFileOrDir)) {
                // Add a directory
                $content = FileSystem::find($pathToFileOrDir,'*');
                foreach($content as $file) {
                    $localPath = str_ireplace($basePath, '', $file);
                    if(is_dir($file)) {
                        $e = $this->zip->addEmptyDir($localPath);
                        if($e !== true && $e != ZipArchive::ER_EXISTS) {
                            self::throwZipException($e);
                        }
                    } else {
                        $e = $this->zip->addFile($file, $localPath);
                        if($e !== true) {
                            self::throwZipException($e);
                        }
                    }
                }
            }
        }
    }

    /**
     * Removes a file or a folder in the zip file
     * @param string $fileOrFolderInZip
     */
    public function remove($fileOrFolderInZip) {
        $fileOrFolderInZip = trim($fileOrFolderInZip);
        if(strlen($fileOrFolderInZip) == 0) {
            throw new ZipException('No file or folder to delete given');
        } else if($fileOrFolderInZip == '/') {
            throw new ZipException('Cannot delete the root of zip file');
        } else {

            print "$fileOrFolderInZip\n\n\n";
            if(!$this->zip->deleteName($fileOrFolderInZip)) {
                throw new ZipException('Failed to remove file/folder in zip archive');
            }
        }
    }

    /**
     * Returns an assoc. array containing the list of all entries in the zip archive.
     * Each entry is an assoc. array that contains details about the file/folder.
     * @return array
     */
    public function getContentList() {
        $stats = array();
        for($i=0; $i<$this->zip->numFiles; $i++) {
            $stat = $this->zip->statIndex($i);
            if(!is_array($stat)) {
                throw new ZipException('Failed to receive the status or a contained file or folder');
            } else {
                $stats[$stat['name']] = $stat;
            }
        }
        return $stats;
    }

}
?>

This Article is also available in Deutsch.

Original text	$text
Image
Enter here
Last value was ok:	$inputCorrect