Peter M. Groen / knowledgetree

<?php /* vim: set expandtab softtabstop=4 shiftwidth=4 foldmethod=marker: */
/**
 * $Id$
 *
 * Represents a document as per the documents database table.
 *
 * Copyright (c) 2003, 2005 Jam Warehouse http://www.jamwarehouse.com
 *
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 *
 * @version $Revision$
 * @author Rob Cherry, Jam Warehouse (Pty) Ltd, South Africa
 * @package lib.documentmanagement
 */

// document statuses
DEFINE("LIVE", 1);
DEFINE("PUBLISHED", 2);
DEFINE("DELETED", 3);
DEFINE("ARCHIVED", 4);
DEFINE("STATUS_INCOMPLETE", 5);
DEFINE("STATUS_VERSION", 6);

require_once(KT_LIB_DIR . "/foldermanagement/Folder.inc");

class Document extends KTEntity {
    var $_bUsePearError = true;
    
    // {{{ attributes
    /** primary key */
    var $iId;
    
    /** document type primary key */
    var $iDocumentTypeID;

    /** document name */
    var $sName;

    /** document file name (path to document on file system) */
    var $sFileName;

    /** document file size */
    var $iSize;

    /** primary key of user who created document */
    var $iCreatorID;

    /** date the document was last modified */
    var $dModified;

    /** file description */
    var $sDescription;

    /** primary key of file mime type */
    var $iMimeTypeID;

    /** primary key of folder under which document is stored */
    var $iFolderID;

    /** major revision number */
    var $iMajorVersion;
    
    /** minor revision number */
    var $iMinorVersion;
   
    /** document checked out status */
    var $bIsCheckedOut;
    //?? make checked out a status?
   
    /** document status **/
    var $iStatusID;
   
    /** the user that currently has the document checked out */
    var $iCheckedOutUserID;
   
    /** comma delimited string of folder hierarch this document falls under */
    var $sParentFolderIDs;
   
    /** forward slash deliminated path from repository root */
    var $sFullPath;
   
    /** date the document was created */
    var $dCreated;

    /** object which controls (read/write) permissions on this document */
    var $iPermissionObjectID;
   
    /** object which has quick lookups (read-only) on permissions on this document */
    var $iPermissionLookupID;

    /** if this is a historic version, a pointer to the live document */
    var $iLiveDocumentID = null;

    /** metadata revision number */
    var $iMetadataVersion;

    /** storage path to the file from the repository root */
    var $sStoragePath;
   
    // }}}
    
    // {{{ KTEntity stuff
    var $_aFieldToSelect = array(
        "iId" => "id",
        "iDocumentTypeID" => 'document_type_id',
        "sName" => 'name',
        "sFileName" => 'filename',
        "iSize" => 'size',
        "iCreatorID" => 'creator_id',
        "dModified" => 'modified',
        "sDescription" => 'description',
        "iMimeTypeID" => 'mime_id',
        "iFolderID" => 'folder_id',
        "iMajorVersion" => 'major_version',
        "iMinorVersion" => 'minor_version',
        "bIsCheckedOut" => 'is_checked_out',
        "iCheckedOutUserID" => 'checked_out_user_id',
        "sParentFolderIDs" => 'parent_folder_ids',
        "sFullPath" => 'full_path',
        "iStatusID" => 'status_id',
        "dCreated" => 'created',
        "iPermissionObjectID" => 'permission_object_id',
        "iPermissionLookupID" => 'permission_lookup_id',
        "iLiveDocumentID" => 'live_document_id',
        "iMetadataVersion" => 'metadata_version',
        "sStoragePath" => 'storage_path',
    );
    // }}}

    // {{{ constructor
    /**
     * Document class constructor
     *
     * @param $sName    File Name
     * @param $iSize    File size in bytes
     * @param $iCreatorID  Primary key of user who created document
     * @param $sDescription  Description
     * @param $iMimeID   Primary key of file mime type
     * @param $iFolderID   Primary key of folder to which document belongs
     *
     */
    function Document($sNewName = null, $sNewFileName = null, $iNewSize = null, $iNewCreatorID = null, $iNewMimeID = null, $iNewFolderID = null, $sNewDescription = "None") {
        $this->iId = -1; //primary key not set as document is not stored yet
        $this->sName = $sNewName;
        $this->iSize = $iNewSize;
        $this->iCreatorID = $iNewCreatorID;
        $this->sFileName = $sNewFileName;
        $this->sDescription = $sNewDescription;
        $this->iMimeTypeID = $iNewMimeID;
        $this->iFolderID = $iNewFolderID;
        $this->iDocumentTypeID = Folder::getDefaultFolderDocumentType($this->iFolderID);
        $this->iMajorVersion = 0;
        $this->iMetadataVersion = 0;
        $this->iMinorVersion = 1;
        $this->bIsCheckedOut = false;
        $this->iCheckedOutUserID = -1;
        // FIXME: statuses
        $this->iStatusID = LIVE;
    }
    // }}}

    // {{{ getters/setters
    function getID() { return $this->iId; }
    function getDocumentTypeID() { return $this->iDocumentTypeID; }
    function setDocumentTypeID($sNewValue) { $this->iDocumentTypeID = $sNewValue; }
    function getName() { return $this->sName; }
    function setName($sNewValue) { $this->sName = $sNewValue; }
    function getFileName() { return $this->sFileName; }
    function setFileName($sNewValue) { $this->sFileName = $sNewValue; }
    function getFolderID() { return $this->iFolderID; }
    function setFolderID($iNewValue) { $this->iFolderID = $iNewValue; }
    function getFileSize() { return $this->iSize; }
    function setFileSize($iNewValue) { $this->iSize = $iNewValue; }
    function getSize() { return $this->iSize; }
    function setSize($iNewValue) { $this->iSize = $iNewValue; }
    function getCreatorID() { return $this->iCreatorID; }
    function setCreatorID($iNewValue) { $this->iCreatorID = $iNewValue; }
    function getLastModifiedDate() { return $this->dModified; }
    function setLastModifiedDate($dNewValue) { $this->dModified = $dNewValue; }
    function getCreatedDateTime() { return $this->dCreated; }
    function getDescription() { return $this->sDescription; }
    function setDescription($sNewValue) { $this->sDescription = $sNewValue; }
    function getMimeTypeID() { return $this->iMimeTypeID; }
    function setMimeTypeID($iNewValue) { $this->iMimeTypeID = $iNewValue; }
    function getMajorVersionNumber() { return $this->iMajorVersion; }
    function setMajorVersionNumber($iNewValue) { $this->iMajorVersion = $iNewValue; }
    function getMinorVersionNumber() { return $this->iMinorVersion; }
    function setMinorVersionNumber($iNewValue) { $this->iMinorVersion = $iNewValue; }
    function getIsCheckedOut() { return $this->bIsCheckedOut; }
    function setIsCheckedOut($bNewValue) { $this->bIsCheckedOut = KTUtil::anyToBool($bNewValue); }
    function getCheckedOutUserID() { return $this->iCheckedOutUserID; }
    function setCheckedOutUserID($iNewValue) { $this->iCheckedOutUserID = $iNewValue; }
    function getStatusID() { return $this->iStatusID; }
    function setStatusID($iNewValue) { $this->iStatusID = $iNewValue; }
    function getPermissionObjectID() { return $this->iPermissionObjectID; }
    function setPermissionObjectID($iNewValue) { $this->iPermissionObjectID = $iNewValue; }
    function getPermissionLookupID() { return $this->iPermissionLookupID; }
    function setPermissionLookupID($iNewValue) { $this->iPermissionLookupID = $iNewValue; }
    function getLiveDocumentID() { return $this->iLiveDocumentID; }
    function setLiveDocumentID($iNewValue) { $this->iLiveDocumentID = $iNewValue; }
    function getMetadataVersion() { return $this->iMetadataVersion; }
    function setMetadataVersion($iNewValue) { $this->iMetadataVersion = $iNewValue; }
    function getStoragePath() { return $this->sStoragePath; }
    function setStoragePath($sNewValue) { $this->sStoragePath = $sNewValue; }
    // }}}

    // {{{ getParentID
    /**
     * Allows documents to be treated like folders in terms of finding
     * their parent objects.
     */
    function getParentID() {
        return $this->getFolderID();
    }
    // }}}

    // {{{ getVersion
    /** returns the complete version number as a string */
    function getVersion() {
        return $this->iMajorVersion . "." . $this->iMinorVersion;
    }
    // }}}

    // {{{ isLive
    /** Returns the live status of the document */
    function isLive() {
        return $this->getStatusID() == LIVE;
    }
    // }}}

    // {{{ isArchived
    /** Get status ID wrapper for archived status */
    function isArchived() {
        return $this->getStatusID() == ARCHIVED;
    }
    // }}}

    // {{{ getDaysSinceLastModified
    /** returns the number of days since this document has been last modified **/
    function getDaysSinceLastModified() {
        // convert to epoch
        $iLastModified = strtotime($this->dModified);
        $iCurrentDateTime = time();
        // calculate the difference
        $iDiff = $iCurrentDateTime - $iLastModified;
        // how many days is that?
        $iMinutes = $iDiff / 60;
        $iHours = $iMinutes / 60;
        $iDays = $iHours / 24;
        return floor($iDays);
    }
    // }}}

    // {{{ ktentity requirements
    function _fieldValues () {
        $this->sFullPath = Document::_generateFolderPath($this->iFolderID);
        $this->sParentFolderIDs = Document::_generateFolderIDs($this->iFolderID);
        return array(
            'document_type_id' => $this->iDocumentTypeID,
            'name' => $this->sName,
            'filename' => $this->sFileName,
            'size' => $this->iSize,
            'creator_id' => $this->iCreatorID,
            'modified' => $this->dModified,
            'description' => $this->sDescription,
            'mime_id' => $this->iMimeTypeID,
            'folder_id' => $this->iFolderID,
            'major_version' => $this->iMajorVersion,
            'minor_version' => $this->iMinorVersion,
            'is_checked_out' => KTUtil::anyToBool($this->bIsCheckedOut),
            'checked_out_user_id' => $this->iCheckedOutUserID,
            'parent_folder_ids' => $this->sParentFolderIDs,
            'full_path' => $this->sFullPath,
            'status_id' => $this->iStatusID,
            'created' => $this->dCreated,
            'permission_object_id' => $this->iPermissionObjectID,
            'permission_lookup_id' => $this->iPermissionLookupID,
            'live_document_id' => $this->iLiveDocumentID,
            'metadata_version' => $this->iMetadataVersion,
            'storage_path' => $this->sStoragePath,
        );
    }

    function _table () {
        global $default;
        return $default->documents_table;
    }

    /**
     * Recursive function to generate a comma delimited string containing
     * the parent folder ids
     *
     * @return String	comma delimited string containing the parent folder ids
     */
    function _generateParentFolderIDS($iFolderID) {
        global $default;
        //if the folder is not the root folder
        if ($iFolderID != 0) {
            $sql = $default->db;
            $sql->query(array("SELECT parent_id FROM $default->folders_table WHERE ID = ?", $iFolderID));/*ok*/
            $sql->next_record();
            return Document::_generateParentFolderIDS($sql->f("parent_id")) . ",$iFolderID";
        }
        return;
    }

    /**
     * Returns a comma delimited string containing the parent folder ids, strips leading /
     *
     * @return String	comma delimited string containing the parent folder ids
     */
    function _generateFolderIDs($iFolderID) {
        $sFolderIDs = Document::_generateParentFolderIDS($iFolderID);
        return substr($sFolderIDs, 1, strlen($sFolderIDs));
    }

    /**
     * Recursively generates forward slash deliminated string giving full path of document
     * from file system root url
     */
    function _generateFullFolderPath($iFolderID) {
        global $default;
        //if the folder is not the root folder
        if ($iFolderID != 0) {
            $sql = $default->db;
            $sql->query(array("SELECT name, parent_id FROM $default->folders_table WHERE ID = ?", $iFolderID));/*ok*/
            $sql->next_record();
            return Document::_generateFullFolderPath($sql->f("parent_id")) . "/" . $sql->f("name");
        }
        return;
    }

    /**
     * Returns a forward slash deliminated string giving full path of document, strips leading /
     */
    function _generateFolderPath($iFolderID) {
        global $default;
        $sPath = Document::_generateFullFolderPath($iFolderID);
        $sPath = substr($sPath, 1, strlen($sPath));
        $sPath = addslashes($sPath);
        return $sPath;
    }
    // }}}

    // {{{ create
    /**
     * Insert the current document into the database
     *
     * @return boolean true on successful insert, false otherwise
     */
    function create() {
        if (empty($this->dCreated)) {
            $this->dCreated = getCurrentDateTime();
        }
        if (empty($this->dModified)) {
            $this->dModified = getCurrentDateTime();
        }
        $oFolder = Folder::get($this->getFolderID());
        $this->iPermissionObjectID = $oFolder->getPermissionObjectID();
        $res = parent::create();

        if ($res === true) {
            KTPermissionUtil::updatePermissionLookup($this);
        }

        return $res;
    }
    // }}}

    // {{{ update
    function update($bPathMove = false) {
        $res = parent::update();
        if (($res === true) && ($bPathMove === true)) {
            KTPermissionUtil::updatePermissionLookup($this);
        }
        return $res;
    }
    // }}}

    // {{{ get
    function &get($iId) {
        return KTEntityUtil::get('Document', $iId);
    }
    // }}}

    // {{{ getList
    /**
     * Static function
     * Get a list of Documents
     *
     * @param  String  Where clause (not required)
     *
     * @return Array array of Documents objects, false otherwise.
     */
    function getList($sWhereClause = null) {
        return KTEntityUtil::getList(Document::_table(), 'Document', $sWhereClause);
    }
    // }}}

    // {{{ getDocumentFieldsForDocumentType
    /**
     * Static function.
     * Get all the document field's associated with a document type
     *
     * @param  Document type primary key
     * @param  Get only the mandatory fields
     *
     * @return array array of document field objects, false otherwise
     */
    function getDocumentFieldsForDocumentType($iDocumentTypeID, $bMandatoryOnly = false) {
        $aDocumentFieldArray;
        settype($aDocumentFieldArray,"array");
        $sql = $default->db;
        $sQuery = "SELECT DF.id AS id, DF.name AS name, DF.data_type AS data_type " ./*ok*/
            "FROM $default->document_fields_table AS DF " .
            "INNER JOIN $default->document_type_fields_table AS DTFL ON DF.id = DTFL.field_id " .
             "WHERE DTFL.document_type_id = ? ";
        $aParams = array($iDocumentTypeID);
        if ($bMandatoryOnly) {
            $sQuery .= "AND DFTL.is_mandatory = ? ";
            $aParams[] = true;
        }
        $sQuery .= "ORDER BY DF.name ASC";
        $result = $sql->query(array($sQuery, $aParams));

        if ($result) {
            $iCount = 0;
            while ($sql->next_record()) {
                $oDocumentField = DocumentField::get($sql->f("id"));
                if (!($oDocumentField === false)) {
                    $aDocumentFieldArray[$iCount] = $oDocumentField;
                    $iCount++;
                }
            }
            return $aDocumentFieldArray;
        }
        return false;

    }
    // }}}

    // {{{ getDocumentHistory
    /**
     * Get a document's transaction history
     *
     * @return Array array of DocumentTransaction objects
     *
     */
    function getDocumentHistory() {
        global $default, $lang_err_database;
        $aDocumentHistory = array();
        $sql = $default->db;
        $result = $sql->query(array("SELECT * FROM  " . $default->document_transactions_table . " " ./*ok*/
                              "WHERE document_id = ? " .
                              "ORDER BY datetime DESC", $this->iId));
        if ($result) {
            $iCount = 0;
            while($sql->next_record()) {
                $oDocumentTransaction = DocumentTransaction::get($sql->f("id"));
                $aDocumentHistory[$iCount] = $oDocumentTransaction;
                $iCount++;
            }
            return $history;
        }
        return false;
    }
    // }}}

    // {{{ getMimeTypeIconUrl
    /**
     * Returns the url to the file type icon associated with this document
     *
     * @return string the url to the relevant file icon, false if there is none
     */
    function getMimeTypeIconUrl() {
        global $default;
        if ($this->iMimeTypeID) {
            // lookup the icon from the table
            $sIconPath = lookupField($default->mimetypes_table, "icon_path", "id", $this->iMimeTypeID);
            if (strlen($sIconPath) > 0) {
                return $default->graphicsUrl . "/" . $sIconPath;
            } else {
                return false;
            }
        } else {
            return false;
        }
    }
    // }}}

    // {{{ getIcon
    /**
     * Returns the html to display the document icon image
     */
    function getIcon() {
        global $default;
        return generateImage($this->getMimeTypeIconUrl() ? $this->getMimeTypeIconUrl() : "$default->graphicsUrl/unknown.gif");
    }
    // }}}

    // {{{ getPath
    /**
     * Get the full path for a document
     *
     * @return string full path of document
     */
    function getPath() {
        return Folder::getFolderPath($this->iFolderID) . $this->sFileName;
    }
    // }}}

    // {{{ getDisplayPath
    /**
     * Get the path for a document that will be displayed to the user
     *
     * @return string full path to document
     */
    function getDisplayPath($bDisplayIcon = false) {
        $sFolderPath = Folder::getFolderDisplayPath($this->iFolderID);
        // #3425 for consistency
        return ($bDisplayIcon ? $this->getIcon() : "") .
           ($sFolderPath == "" ? "Deleted Folder" : $sFolderPath) . " &raquo; " . $this->sFileName;
    }
    // }}}

    // {{{ documentExists
    /**
     * Static function.
     * Check if a document already exists
     *
     * @param String  File name of document
     * @param int  Primary key of folder to which document is assigned
     *
     * @return boolean true if document exists, false otherwise.
     */
    function documentExists($sFileName, $iFolderID) {
        global $default;
        $sql = $default->db;
        $sQuery = "SELECT * FROM $default->documents_table " ./*ok*/
              "WHERE filename = ? " .
              " AND folder_id = ?" .
              " AND status_id = ?";
        $aParams = array($sFileName, $iFolderID, LIVE);
        $sql->query(array($sQuery, $aParams));
        if ($sql->next_record()) {
            return true;
        }
        return false;
    }
    // }}}

    // {{{ getDocumentName
    /**
     * Lookup the document name for the document
     *
     * @param int the ID of the document to lookup the document name for
     * @return string the name of the document on success, false otherwise.
     */
    function getDocumentName($iDocumentID) {
        global $default, $lang_err_database, $lang_err_doc_not_exist;
        $sql = $default->db;

        if ($sql->query(array("SELECT name FROM $default->documents_table " ./*ok*/
                        "WHERE id = ?", $iDocumentID))) {
            if ($sql->next_record()) {
                return $sql->f("name");
            }
        }
        return false;
    }
    // }}}

    // {{{ getDocumentDisplayPath
    /**
     * Static function.
     * Get the path for a document that will be displayed to the user
     *
     * @param integer primary key of document to generate path for
     * @return string full path to document
     */
    function getDocumentDisplayPath($iDocumentID) {
        global $default;
        $oDocument = & Document::get($iDocumentID);
        return $oDocument->getDisplayPath();
    }
    // }}}

    // {{{ documentIsAssignedDocTypeInFolder
    /**
     * Check if any documents are assigned the given
     * document type in a specified folder
     *
     */
    function documentIsAssignedDocTypeInFolder($iFolderID, $iFolderDocTypeID) {
        global $default;
        $sql = $default->db;
        $sql->query(array("SELECT * " . /*ok*/
                    "FROM $default->folder_doctypes_table AS FDL " .
                    "INNER JOIN $default->documents_table AS D ON D.document_type_id = FDL.document_type_id " .
                    "WHERE FDL.id = ? " .
                    "AND D.folder_id = ?", array($iFolderDocTypeID, $iFolderID)));
        if ($sql->next_record()) {
            return true;
        }
        return false;
    }
    // }}}

    // {{{ removeInvalidDocumentTypeEntries
    /**
     * On a document type change, delete all document field entries for the
     * old document type
     */
    function removeInvalidDocumentTypeEntries() {
        global $default;
        $sQuery = array("SELECT field_id FROM $default->document_type_fields_table DTFL " . /*ok*/
              "INNER JOIN $default->document_fields_table AS DF ON DF.id = DTFL.field_id " .
              "WHERE DTFL.document_type_id = ? " .
              "AND DF.is_generic = ?", array($this->iDocumentTypeID, false));
        $sql = $default->db;
        $sql->query($sQuery);
        $aFieldIDs = array();
        //get all the fields from the old document type
        while ($sql->next_record()) {
            $aFieldIDs[count($aFieldIDs)] = $sql->f("field_id");
        }
        if (count($aFieldIDs) > 0) {
            //delete the entries
            $sQuery = "DELETE FROM $default->document_fields_link_table " .
                      "WHERE document_id = " . quote($this->iId) . "
                       AND document_field_id IN (" . implode(",",$aFieldIDs) . ")";
            if ($sql->query($sQuery)) {
                return true;
            }
            return false;
        }
        //none to remove if we get here
        return true;
    }
    // }}}

    // {{{ cleanupDocumentData
    /**
     * Deletes content from document data tables
     */
    function cleanupDocumentData($iDocumentID) {
        global $default;
        $sql = $default->db;
        $result = $sql->query("DELETE FROM $default->document_text_table WHERE document_id = $iDocumentID") &&
                  $sql->query("DELETE FROM $default->search_permissions_table WHERE document_id = $iDocumentID") &&
                  $sql->query("DELETE FROM $default->document_fields_link_table WHERE document_id = $iDocumentID");
        return $result;
    }
    // }}}

    // {{{ getByLiveDocument
    function &getByLiveDocument($oDocument) {
        return KTEntityUtil::getByDict('Document', array(
            'live_document_id' => $oDocument->getID(),
        ), array('multi' => true, 'orderby' => 'modified DESC'));
    }
    // }}}

    // {{{ getByFolderIDAndLookupID
    function &getByFolderIDAndLookupID($iParentID, $iLookupID, $aOptions = null) {
        return KTEntityUtil::getByDict('Document', array(
            'folder_id' => $iParentID,
            'permission_lookup_id' => $iLookupID,
            'status_id' => LIVE,
        ), array('multi' => true));
    }
    // }}}

    // STATIC
    function &createFromArray($aOptions) {
        if (KTUtil::arrayGet($aOptions, "size") === null) {
            $aOptions['size'] = 0;
        }
        if (KTUtil::arrayGet($aOptions, "mimetypeid") === null) {
            $aOptions['mimetypeid'] = 0;
        }
        return KTEntityUtil::createFromArray('Document', $aOptions);
    }

}
?>