Peter M. Groen / knowledgetree

<?php /* vim: set expandtab softtabstop=4 shiftwidth=4 foldmethod=marker: */
/**
 * $Id$
 *
 * Represents a document as per the documents database table.
 *
 * @version $Revision$
 * @author Neil Blakey-Milner, 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',
        "iModifiedUserId" => 'modified_user_id',
    );
    // }}}

    // {{{ 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;
        if (!empty($this->iFolderID)) {
            $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; }
    function getModifiedUserId() { return $this->iModifiedUserId; }
    function setModifiedUserId($iNewValue) { $this->iModifiedUserId = $iNewValue; }
    // }}}

    // {{{ 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;
    }
    // }}}

    // {{{ 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,
            'modified_user_id' => $this->iModifiedUserId,
        );
    }

    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();
        }
        if (empty($this->iModifiedUserId)) {
            $this->iModifiedUserId = $this->iCreatorID;
        }
        $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);
    }
    // }}}

    // {{{ 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;
    }
    // }}}

    // {{{ 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();
    }
    // }}}

    // {{{ 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);
    }

}
?>