Introduction

The Simple Document Management System is a PHP web application that provides basic DMS functions. It is designed to be plugged into an existing application and authentication scheme.

I developed it because of the organizations I do work for would benefit from a DMS. However, installing one of the commercial DMSes, or a larger open source CMS would be overkill. Also, I wanted authentication to be based on the existing hand written CMS that they were using. I decided to write a system that provides some basic DMS functions, and can be plugged into any existing application.

Current Version

Name Simple Document Management System
Version 0.1
Date December 30, 2010
Requirements PHP, mysql database
Download Download Here sdms-20101230.zip (55.7kb) — Version 0.4bsdms-0_4b-20110821.zip (46.6kb)
Changelog Version 0.4 - To be released soon
Roadmap Version 0.4 - Future Development

Application Features

  • Can be plugged into any existing application authentication scheme. Even applications in other languages! See the Auth Adapter section for more information.
  • Multiple Modes:
    • Basic File Browser: Allow users to browse files you make available
    • DMS: Allow users to upload files, manage files, and enter metadata.
  • Configurable and easy to modify to add additional language support.

Documentation

Requirements

  • PHP5+
  • mysql database (optional. Required if using Full DMS mode.)
  • A web server (only tested with Apache). A Rewrite module may be required if you wish to protect downloads in the files folder.

Installation

  • Download the .zip file above, and extract the files onto your webserver.
  • Create an account and database on your mysql server for the application.
    • Defaults: Database Name: sdms
    • Defaults: User: sdms
    • Defaults: Prefix: {blank} but sdms_ is the default if required to house in a single database with other applications.
  • Give the user the all permissions on the database.
  • Run the following script to create the tables within the database.
USE sdms;
 
CREATE TABLE `files` (
  `fid` BIGINT(20) NOT NULL AUTO_INCREMENT,
  `fullpath` text NOT NULL,
  `filename` VARCHAR(250) NOT NULL,
  `filesize` BIGINT(20) NOT NULL,
  `filemime` VARCHAR(200) NOT NULL,
  `fileext` VARCHAR(10) NOT NULL,
  `filedescription` text,
  `version` VARCHAR(10) DEFAULT NULL,
  `uploadedby` VARCHAR(100) NOT NULL,
  `uploadedbyid` BIGINT(20) NOT NULL,
  `uploadedbyname` VARCHAR(100) NOT NULL,
  `deleted` tinyint(1) NOT NULL DEFAULT '0',
  `dateupdated` datetime NOT NULL,
  `filehash` VARCHAR(40) NOT NULL,
  PRIMARY KEY (`fid`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1
 
CREATE TABLE `filetags` (
  `id` BIGINT(20) NOT NULL AUTO_INCREMENT,
  `fid` BIGINT(20) NOT NULL,
  `tid` BIGINT(20) NOT NULL,
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1
 
CREATE TABLE `tags` (
  `tid` BIGINT(20) NOT NULL AUTO_INCREMENT,
  `tag` VARCHAR(50) NOT NULL,
  PRIMARY KEY (`tid`)
) ENGINE=InnoDB DEFAULT CHARSET=latin1
  • If you are allowing uploads, you will need to make the files directory writable by the web server. If running apache on Linux, this is often the apache, nobody, or www-data user.

To see special instructions for upgrading, please see the upgrading section.

Configuration

There are a number of settings you need to configure in the config.php file before you can use the system. They are outlined below.

Database Settings:

  • DB_HOST: The host name of your database server. Usually it is on localhost.
  • DB_DB: The database assigned for SDMS. Normally it is in its own database called sdms, but if you only have one database available, place its name here.
  • DB_PREFIX: The prefix of the table name that will be used on all database tables. So instead of a table called files, if you enable a 'sdms_' prefix the table will need to be called sdms_files and this will allow your the application to share a database with other applications that may have a table also called files.
  • DB_USER: The username of the database user who can access the database specified.
  • DB_PASSWORD: The password of the above user.

Application Settings:

  • LOGIN_URL: The URL to redirect people to if they try to access the application, but are not yet logged in.
  • ROOT_FOLDER: The folder within the application where the file storage is. Normally a folder called files.
  • DMS_FILEROOT: This is the full system path where the DMS is installed.
  • DMS_ROOT: This is the web address where the DMS in installed.
  • ALLOW_RAW_DOWNLOAD: true/false - This determines if download links will be directly to the file, or if they will go through a download script. Currently, only true is supported.
  • BROWSER_ONLY: true/false - This determines of the system will allow any uploads or metadata. If set to true, the system acts as a fancy file browser. If set to false, all functions become available for those with permission. A database is not required if this is set to true.
  • DISABLE_ABOUT: true / false - If set to true, this disables the about page.
  • MAX_FILE_SIZE: This is a number of bytes to allow for a file upload. Default is 2000000 (2 MB). If you want to set it higher, you may also need to modify the PHP setting for max file uploads.
  • HOME_BUTTON_URL: This is the URL of the Home button. (Added v0.4)
  • HOME_BUTTON_TEXT: This is the text that appears on the Home button. (Added v0.4)

Language Settings:

  • LANG: This is the language abbreviation that the system will use. Options Supported: en - English. If you develop a language pack, you will need to store the file in the /libs/lang/ folder and give it the name {code}.php where {code} is the two letter ISO_639-1 code.

Debugging:

  • Normally you would want to leave this commented out.

Authentication Adapter (authadapter.php)

The authentication adapter allows you to snap the sdms into your existing application and authentication scheme. The only required content for this file is the header:

<?php
session_start();
include('libs/config.php');
/**
 * This file allows you to link your system to the sdms.
 * 
 * You will need to write code below to link up to six main session variables.
 * DMS_READ - boolean - Does the user have read permission?
 * DMS_WRITE - boolean - Does the user have write permission?
 * DMS_USERNAME - string - What is the username of the user.
 * DMS_FULLNAME - string - What is the full name of the user.
 * DMS_USERID - int - What is the user ID of the user from your system.
 * DMS_LOGGEDIN - boolean - Has the user successfully logged in.
 * 
 * You will want to set each of these sessions variables, and then set the DMS_LOGGEDIN to true before 
 * the end of the script.  If there are any failed tests, the user will be kicked back to the login 
 * page specified in the config.php file.
 * 
 * You can use any code in here to link to your system.  Some basic blocks are already configured.
 */

And this at the bottom of the file:

/****************************************
 * Do Not Change Code Below This Line!
 ***************************************/
 
if(BROWSER_ONLY){
	/*
	 * We are in Browser Only Mode.
	 * Disable writing.
	 */
	$_SESSION['DMS_WRITE'] = false;
}
 
if($_SESSION['DMS_LOGGEDIN']){
 
}
else{
	header('Location: ' . LOGIN_URL);
}

All code between these blocks you will need to write to hook into your existing application. The application is shipped with some basic code that give anyone who visits read and write access to the system under a dummy user account. You will want to customize this. Some examples are below.

Hook Into Another PHP Application 1

I wrote this with the intention of hooking it into an existing CMS I wrote. I installed the application in a sub folder, and then created this code to hook to my application:

/**
 * Everyone gets read/write access
 */
$_SESSION['DMS_READ'] = true;
$_SESSION['DMS_WRITE'] = true;
//print_r($_SESSION);
$_SESSION['DMS_USERNAME'] = $_SESSION['username'];
$_SESSION['DMS_FULLNAME'] = $_SESSION['fullname'];//'n/a';//Full Name not provided
$_SESSION['DMS_USERID'] = $_SESSION['userid'];
$_SESSION['DMS_LOGGEDIN'] = $_SESSION['loggedin'];

This example is fairly straight forward as I wanted all users of the CMS to have full access in the DMS. I just mapped the session variables in my CMS to the variables in the DMS. As you can see based on my comments above, originally I wasn't capturing the full name of my users, but later added that to my login script.

Hook Into Another PHP Application 2

A more complex example could require only allowing selected people to have write access, while others are allowed to read. Using the same example as above, I'll show you how you can do this:

/**
 * Thomas and Sara can write to the system.  Everyone else can only read.
 */
if($_SESSION['userid'] == 1 || $_SESSION['userid'] == 999){
	$_SESSION['DMS_WRITE'] = true;
}
else{
	$_SESSION['DMS_WRITE'] = false;
}
$_SESSION['DMS_READ'] = true;
//print_r($_SESSION);
$_SESSION['DMS_USERNAME'] = $_SESSION['username'];
$_SESSION['DMS_FULLNAME'] = $_SESSION['fullname'];//'n/a';//Full Name not provided
$_SESSION['DMS_USERID'] = $_SESSION['userid'];
$_SESSION['DMS_LOGGEDIN'] = $_SESSION['loggedin'];

Since I know the userids of users Thomas and Sara, I can do a check of that before assigning permissions.

Other Methods of Defining Access

Lets say you only want to allow write access from a specific IP address. And forgo user accounts completely. You could try something like this:

/**
 * Only allow access from 192.168.1.15
 */
if(getenv(REMOTE_ADDR) == '192.168.1.15'){
	$_SESSION['DMS_WRITE'] = true;
}
else{
	$_SESSION['DMS_WRITE'] = false;
}
$_SESSION['DMS_READ'] = true;
$_SESSION['DMS_USERNAME'] = 'admin';
$_SESSION['DMS_FULLNAME'] = 'Administrator';
$_SESSION['DMS_USERID'] = '1';
$_SESSION['DMS_LOGGEDIN'] = true;

I wouldn't recommend this type of setup however, I'm just trying to provide examples on how you can use the auth adapter.

Hooking into Another Programming Language

Lets say you have an old Perl application that you are using, and you want to add this PHP DMS to the mix. Since PHP and Perl cannot share the same session variables (as far as I know) you will need to find another way around the problem. You could:

  • Have your Perl application write a cookie that the PHP application can read to determine access.
  • Have the Perl application write a file to the file system on the server that you have the authadapter read, and then set up access.
  • Write code in the authadapter to directly pull the authentication information from another database or authentication scheme.

The following code has not been tested, and would require additional code on the other application side of things:

<code php>
/**
 * Read a file from the /server/authenticationbridge/ folder and log in the user.
 * Thomas and Sara can write to the system.  Everyone else can only read.
 * Example file:
 * 1,thomas,20110820100000
 * First field is userid.
 * Second field is username.
 * Third field is date/time stamp
 */
$file = file_get_contents('/server/authenticationbridge/transfer.txt');
$fields = explode(',',$file);
/*
 * Quick check to see if this request is recent.
 * Checks to see if token is more than 10 seconds old.  Ignores it if it is.
 */
if((date('Ymdhis') - $field[2]) > 10){
	header('Location: http://somewhere.to.login.html');
	exit();	
}
if($field[1] == 'thomas' || $field[1] == 'sara'){
	$_SESSION['DMS_WRITE'] = true;
}
else{
	$_SESSION['DMS_WRITE'] = false;
}
$_SESSION['DMS_READ'] = true;
//print_r($_SESSION);
$_SESSION['DMS_USERNAME'] = $field[1];
$_SESSION['DMS_FULLNAME'] = 'n/a';//Full Name not provided
$_SESSION['DMS_USERID'] = $field[0];
$_SESSION['DMS_LOGGEDIN'] = true;

Modes

Browse Only Mode

The system acts as a fancy file browser. In this mode, people can browse to files on the file system and download them. No Metadata is provided, and no Database is required. To upload files, you would use FTP or some other direct access to the server. You could allow public access via the authadapter.php file, or lock it down to your authenticated users only.

Full DMS Mode

This mode provides browsing functionality, metadata viewing/editing, searching, and file uploading features. Users can be given two rights, read and write. Read allows browsing and downloading of data only. Writing allows uploading and system modification.

Upgrading

Version 0.1/0.2/0.3 to Version 0.4

Database Changes

None. Existing database structure is fine.

File Changes

A number of core files have changed. You can extract the .zip archive on top of the existing install and it will upgrade your application. However, make sure you back up copies of the following files before upgrading as they will be clobbered by the upgrade unzipping process:

  • /libs/config.php : Your custom configuration settings. New configuration options are now available. Merge your old config with the new config before using the application.
  • /authadapter.php : Your custom authentication script. Nothing has changed in the core handling of the authentication system. You can simply replace the upgraded file with your file.
  • /libs/lang/en.php : If you customized the languages, you should make a copy of this file and merge your changes afterwards. Starting with version 0.4, all new language strings will be specified in their own section of the file.
  • Any other file you made custom modifications too : If you modified the functionality at all, you should back up that file and merge your changes afterwards. I can't guarantee which files were modified and which were not. If you are making modifications to the core, and you would like to contribute them back to the application for others, please use our bug tracking software to post your code changes: http://bugs.cornempire.net
sdms/start.txt · Last modified: 2011/08/21 12:59 by cornmaster
CC Attribution-Noncommercial-Share Alike 3.0 Unported
www.chimeric.de Valid CSS Driven by DokuWiki do yourself a favour and use a real browser - get firefox!! Recent changes RSS feed Valid XHTML 1.0