API-CHANGE: DMS interface and mock implementation

code/DMS.php

@@ -0,0 +1,115 @@
+<?php
+class DMS implements DMSInterface {
+
+	static $dmsFolder = 'dms-assets';   //folder to store the documents in
+
+	//How many documents to store in a single folder. The square of this number is the maximum number of documents.
+	//The number should be a multiple of 10
+	static $dmsFolderSize = 1000;
+	static $dmsPath;    //DMS path set on creation
+
+	/**
+	 * Factory method that returns an instance of the DMS. This could be any class that implements the DMSInterface.
+	 * @static
+	 * @return DMSInterface An instance of the Document Management System
+	 */
+	static function getDMSInstance() {
+		self::$dmsPath = BASE_PATH . DIRECTORY_SEPARATOR . self::$dmsFolder;
+
+		$dms = new DMS();
+		$dms->createStorageFolder(self::$dmsPath);
+
+		return $dms;
+	}
+
+	/**
+	 * Takes a File object or a String (path to a file) and copies it into the DMS. The original file remains unchanged.
+	 * When storing a document, sets the fields on the File has "tag" metadata. E.g: filename, path, etc. all become
+	 * single-value tags on the Document.
+	 * @param $file File object, or String that is path to a file to store
+	 * @return DMSDocumentInstance Document object that we just created
+	 */
+	function storeDocument($file) {
+		//confirm we have a file
+		$fromPath = null;
+		if (is_string($file)) $fromPath = $file;
+		elseif (is_object($file) && $file->is_a("File")) $fromPath = $file->Filename;
+
+		if (!$fromPath) throw new FileNotFoundException();
+
+		//create a new document and get its ID
+		$doc = new DMSDocument();
+		$docID = $doc->write();
+
+		//calculate all the path to copy the file to
+		$fromFilename = basename($fromPath);
+		$toFilename = $docID . '~' . $fromFilename; //add the docID to the start of the Filename
+		$toFolder = self::getStorageFolder($docID);
+		$toPath = $toFolder . DIRECTORY_SEPARATOR . $toFilename;
+		$this->createStorageFolder($toFolder);
+
+		//copy the file into place
+		copy($fromPath, self::$dmsPath . DIRECTORY_SEPARATOR . $toPath);
+
+		//write the filename of the stored document
+		$doc->Filename = $toPath;
+		$doc->write();
+
+		//set an initial title for the document from the filename
+		$doc->addTag('title', $fromFilename, false);
+
+		return $doc;
+	}
+
+	/**
+	 *
+	 * Returns a number of Document objects based on the a search by tags. You can search by category alone,
+	 * by tag value alone, or by both. I.e: getByTag("fruits",null); getByTag(null,"banana"); getByTag("fruits","banana")
+	 * @param null $category The metadata category to search for
+	 * @param null $value The metadata value to search for
+	 * @param bool $showEmbargoed Boolean that specifies if embargoed documents should be included in results
+	 * @return DocumentInterface
+	 */
+	function getByTag($category = null, $value = null, $showEmbargoed = false) {
+		// TODO: Implement getByTag() method.
+	}
+
+	/**
+	 * Returns a number of Document objects that match a full-text search of the Documents and their contents
+	 * (if contents is searchable and compatible search module is installed - e.g. FullTextSearch module)
+	 * @param $searchText String to search for
+	 * @param bool $showEmbargoed Boolean that specifies if embargoed documents should be included in results
+	 * @return DocumentInterface
+	 */
+	function getByFullTextSearch($searchText, $showEmbargoed = false) {
+		// TODO: Implement getByFullTextSearch() method.
+	}
+
+	/**
+	 * Returns a list of Document objects associated with a Page
+	 * @param $page SiteTree to fetch the associated Documents from
+	 * @param bool $showEmbargoed Boolean that specifies if embargoed documents should be included in results
+	 * @return DataList Document list associated with the Page
+	 */
+	function getByPage($page, $showEmbargoed = false) {
+		// TODO: Implement getByPage() method.
+	}
+
+	/**
+	 * Creates a storage folder for the given path
+	 * @param $path Path to create a folder for
+	 */
+	protected function createStorageFolder($path) {
+		if (!is_dir($path)) {
+			mkdir($path, 0777);
+		}
+	}
+
+	/**
+	 * Calculates the storage path from a database DMSDocument ID
+	 */
+	static function getStorageFolder($id) {
+		$folderName = intval($id / self::$dmsFolderSize);
+		return self::$dmsPath . DIRECTORY_SEPARATOR . $folderName;
+	}
+}

code/DMSDocument.php

@@ -1,41 +1,36 @@
 <?php
-/**
+class DMSDocument extends DataObject implements DMSDocumentInterface {
- * Interface for a Document used in the Document Management System. A document is create by storing a File object in an
- * instance of the DMSInterface. All write operations on the Document create a new relation, so we never need to
- * explicitly call the write() method on the Document DataObject
- */
-interface DocumentInterface {
 
-	/**
+	static $db = array(
-	 * Deletes the document, its underlying file, as well as any tags related to this document.
+		"Filename" => "Text",
-	 * @abstract
+	);
-	 * @return null
-	 */
-	function delete();
 
 	/**
 	 * Associates this document with a Page. This method does nothing if the association already exists.
 	 * This could be a simple wrapper around $myDoc->Pages()->add($myPage) to add a has_many relation
-	 * @abstract
 	 * @param $pageObject Page object to associate this Document with
 	 * @return null
 	 */
-	function addPage($pageObject);
+	function addPage($pageObject) {
+		// TODO: Implement addPage() method.
+	}
 
 	/**
 	 * Removes the association between this Document and a Page. This method does nothing if the association does not exist.
-	 * @abstract
 	 * @param $pageObject Page object to remove the association to
 	 * @return mixed
 	 */
-	function removePage($pageObject);
+	function removePage($pageObject) {
+		// TODO: Implement removePage() method.
+	}
 
 	/**
 	 * Returns a list of the Page objects associated with this Document
-	 * @abstract
 	 * @return DataList
 	 */
-	function getPages();
+	function getPages() {
+		// TODO: Implement getPages() method.
+	}
 
 	/**
 	 * Adds a metadata tag to the Document. The tag has a category and a value.
@@ -44,13 +39,14 @@ interface DocumentInterface {
 	 * addTag("fruit","banana") addTag("fruit", "apple") would result in a single metadata tag: fruit->apple.
 	 * Can could be implemented as a key/value store table (although it is more like category/value, because the
 	 * same category can occur multiple times)
-	 * @abstract
 	 * @param $category String of a metadata category to add (required)
 	 * @param $value String of a metadata value to add (required)
 	 * @param bool $multiValue Boolean that determines if the category is multi-value or single-value (optional)
 	 * @return null
 	 */
-	function addTag($category, $value, $multiValue = true);
+	function addTag($category, $value, $multiValue = true) {
+		// TODO: Implement addTag() method.
+	}
 
 	/**
 	 * Quick way to add multiple tags to a Document. This takes a multidimensional array of category/value pairs.
@@ -59,30 +55,33 @@ interface DocumentInterface {
 	 *      array('fruit','banana'),
 	 *      array('fruit','apple')
 	 * );
-	 * @abstract
 	 * @param $twoDimensionalArray array containing a list of arrays
 	 * @param bool $multiValue Boolean that determines if the category is multi-value or single-value (optional)
 	 * @return null
 	 */
-	function addTags($twoDimensionalArray, $multiValue = true);
+	function addTags($twoDimensionalArray, $multiValue = true) {
+		// TODO: Implement addTags() method.
+	}
 
 	/**
 	 * Removes a tag from the Document. If you only set a category, then all values in that category are deleted.
 	 * If you specify both a category and a value, then only that single category/value pair is deleted.
 	 * Nothing happens if the category or the value do not exist.
-	 * @abstract
 	 * @param $category Category to remove (required)
 	 * @param null $value Value to remove (optional)
 	 * @return null
 	 */
-	function removeTag($category, $value = null);
+	function removeTag($category, $value = null) {
+		// TODO: Implement removeTag() method.
+	}
 
 	/**
 	 * Deletes all tags associated with this Document.
-	 * @abstract
 	 * @return null
 	 */
-	function removeAllTags();
+	function removeAllTags() {
+		// TODO: Implement removeAllTags() method.
+	}
 
 	/**
 	 * Returns a multi-dimensional array containing all Tags associated with this Document. The array has the
@@ -91,89 +90,98 @@ interface DocumentInterface {
 	 *      array('fruit','banana'),
 	 *      array('fruit','apple')
 	 * );
-	 * @abstract
 	 * @return array Multi-dimensional array of tags
 	 */
-	function getAllTags();
+	function getAllTags() {
+		// TODO: Implement getAllTags() method.
+	}
 
 	/**
 	 * Returns a link to download this document from the DMS store
-	 * @abstract
 	 * @return String
 	 */
-	function downloadLink();
+	function downloadLink() {
+		// TODO: Implement downloadLink() method.
+	}
 
 	/**
 	 * Hides the document, so it does not show up when getByPage($myPage) is called
 	 * (without specifying the $showEmbargoed = true parameter). This is similar to expire, except that this method
 	 * should be used to hide documents that have not yet gone live.
-	 * @abstract
 	 * @return null
 	 */
-	function embargo();
+	function embargo() {
+		// TODO: Implement embargo() method.
+	}
 
 	/**
 	 * Returns if this is Document is embargoed.
-	 * @abstract
 	 * @return bool True or False depending on whether this document is embargoed
 	 */
-	function isEmbargoed();
+	function isEmbargoed() {
+		// TODO: Implement isEmbargoed() method.
+	}
 
 	/**
 	 * Hides the document, so it does not show up when getByPage($myPage) is called. Automatically un-hides the
 	 * Document at a specific date.
-	 * @abstract
 	 * @param $datetime String date time value when this Document should expire
 	 * @return null
 	 */
-	function embargoUntilDate($datetime);
+	function embargoUntilDate($datetime) {
+		// TODO: Implement embargoUntilDate() method.
+	}
 
 	/**
 	 * Clears any previously set embargos, so the Document always shows up in all queries.
-	 * @abstract
 	 * @return null
 	 */
-	function clearEmbargo();
+	function clearEmbargo() {
+		// TODO: Implement clearEmbargo() method.
+	}
 
 	/**
 	 * Hides the document, so it does not show up when getByPage($myPage) is called.
 	 * (without specifying the $showEmbargoed = true parameter). This is similar to embargo, except that it should be
 	 * used to hide documents that are no longer useful.
-	 * @abstract
 	 * @return null
 	 */
-	function expire();
+	function expire() {
+		// TODO: Implement expire() method.
+	}
 
 	/**
 	 * Returns if this is Document is expired.
-	 * @abstract
 	 * @return bool True or False depending on whether this document is expired
 	 */
-	function isExpired();
+	function isExpired() {
+		// TODO: Implement isExpired() method.
+	}
 
 	/**
 	 * Hides the document at a specific date, so it does not show up when getByPage($myPage) is called.
-	 * @abstract
 	 * @param $datetime String date time value when this Document should expire
 	 * @return null
 	 */
-	function expireAtDate($datetime);
+	function expireAtDate($datetime) {
+		// TODO: Implement expireAtDate() method.
+	}
 
 	/**
 	 * Clears any previously set expiry.
-	 * @abstract
 	 * @return null
 	 */
-	function clearExpiry();
+	function clearExpiry() {
-
+		// TODO: Implement clearExpiry() method.
-	/*---- FROM HERE ON: optional API features ----*/
+	}
 
 	/**
 	 * Returns a DataList of all previous Versions of this document (check the LastEdited date of each
 	 * object to find the correct one)
-	 * @abstract
 	 * @return DataList List of Document objects
 	 */
-	function getVersions();
+	function getVersions() {
+		// TODO: Implement getVersions() method.
+	}
 
 }

code/exceptions/FileNotFoundException.php

@@ -0,0 +1,8 @@
+<?php
+/**
+ * Simple exception extension so that we can tell the difference between internally
+ * raised exceptions and those thrown by DMS.
+ */
+class FileNotFoundException extends Exception {
+
+}

code/interface/DMSDocumentInterface.php

@@ -0,0 +1,179 @@
+<?php
+/**
+ * Interface for a DMSDocument used in the Document Management System. A DMSDocument is create by storing a File object in an
+ * instance of the DMSInterface. All write operations on the DMSDocument create a new relation, so we never need to
+ * explicitly call the write() method on the DMSDocument DataObject
+ */
+interface DMSDocumentInterface {
+
+	/**
+	 * Deletes the DMSDocument, its underlying file, as well as any tags related to this DMSDocument.
+	 * @abstract
+	 * @return null
+	 */
+	function delete();
+
+	/**
+	 * Associates this DMSDocument with a Page. This method does nothing if the association already exists.
+	 * This could be a simple wrapper around $myDoc->Pages()->add($myPage) to add a has_many relation
+	 * @abstract
+	 * @param $pageObject Page object to associate this DMSDocument with
+	 * @return null
+	 */
+	function addPage($pageObject);
+
+	/**
+	 * Removes the association between this DMSDocument and a Page. This method does nothing if the association does not exist.
+	 * @abstract
+	 * @param $pageObject Page object to remove the association to
+	 * @return mixed
+	 */
+	function removePage($pageObject);
+
+	/**
+	 * Returns a list of the Page objects associated with this DMSDocument
+	 * @abstract
+	 * @return DataList
+	 */
+	function getPages();
+
+	/**
+	 * Adds a metadata tag to the DMSDocument. The tag has a category and a value.
+	 * Each category can have multiple values by default. So: addTag("fruit","banana") addTag("fruit", "apple") will add two items.
+	 * However, if the third parameter $multiValue is set to 'false', then all updates to a category only ever update a single value. So:
+	 * addTag("fruit","banana") addTag("fruit", "apple") would result in a single metadata tag: fruit->apple.
+	 * Can could be implemented as a key/value store table (although it is more like category/value, because the
+	 * same category can occur multiple times)
+	 * @abstract
+	 * @param $category String of a metadata category to add (required)
+	 * @param $value String of a metadata value to add (required)
+	 * @param bool $multiValue Boolean that determines if the category is multi-value or single-value (optional)
+	 * @return null
+	 */
+	function addTag($category, $value, $multiValue = true);
+
+	/**
+	 * Quick way to add multiple tags to a DMSDocument. This takes a multidimensional array of category/value pairs.
+	 * The array should look like this:
+	 * $twoDimensionalArray = new array(
+	 *      array('fruit','banana'),
+	 *      array('fruit','apple')
+	 * );
+	 * @abstract
+	 * @param $twoDimensionalArray array containing a list of arrays
+	 * @param bool $multiValue Boolean that determines if the category is multi-value or single-value (optional)
+	 * @return null
+	 */
+	function addTags($twoDimensionalArray, $multiValue = true);
+
+	/**
+	 * Removes a tag from the DMSDocument. If you only set a category, then all values in that category are deleted.
+	 * If you specify both a category and a value, then only that single category/value pair is deleted.
+	 * Nothing happens if the category or the value do not exist.
+	 * @abstract
+	 * @param $category Category to remove (required)
+	 * @param null $value Value to remove (optional)
+	 * @return null
+	 */
+	function removeTag($category, $value = null);
+
+	/**
+	 * Deletes all tags associated with this DMSDocument.
+	 * @abstract
+	 * @return null
+	 */
+	function removeAllTags();
+
+	/**
+	 * Returns a multi-dimensional array containing all Tags associated with this DMSDocument. The array has the
+	 * following structure:
+	 * $twoDimensionalArray = new array(
+     *      array('fruit','banana'),
+     *      array('fruit','apple')
+     * );
+	 * @abstract
+	 * @return array Multi-dimensional array of tags
+	 */
+	function getAllTags();
+
+	/**
+	 * Returns a link to download this DMSDocument from the DMS store
+	 * @abstract
+	 * @return String
+	 */
+	function downloadLink();
+
+	/**
+	 * Hides the DMSDocument, so it does not show up when getByPage($myPage) is called
+	 * (without specifying the $showEmbargoed = true parameter). This is similar to expire, except that this method
+	 * should be used to hide DMSDocuments that have not yet gone live.
+	 * @abstract
+	 * @return null
+	 */
+	function embargo();
+
+	/**
+	 * Returns if this is DMSDocument is embargoed.
+	 * @abstract
+	 * @return bool True or False depending on whether this DMSDocument is embargoed
+	 */
+	function isEmbargoed();
+
+	/**
+	 * Hides the DMSDocument, so it does not show up when getByPage($myPage) is called. Automatically un-hides the
+	 * DMSDocument at a specific date.
+	 * @abstract
+	 * @param $datetime String date time value when this DMSDocument should expire
+	 * @return null
+	 */
+	function embargoUntilDate($datetime);
+
+	/**
+	 * Clears any previously set embargos, so the DMSDocument always shows up in all queries.
+	 * @abstract
+	 * @return null
+	 */
+	function clearEmbargo();
+
+	/**
+	 * Hides the DMSDocument, so it does not show up when getByPage($myPage) is called.
+	 * (without specifying the $showEmbargoed = true parameter). This is similar to embargo, except that it should be
+	 * used to hide DMSDocuments that are no longer useful.
+	 * @abstract
+	 * @return null
+	 */
+	function expire();
+
+	/**
+	 * Returns if this is DMSDocument is expired.
+	 * @abstract
+	 * @return bool True or False depending on whether this DMSDocument is expired
+	 */
+	function isExpired();
+
+	/**
+	 * Hides the DMSDocument at a specific date, so it does not show up when getByPage($myPage) is called.
+	 * @abstract
+	 * @param $datetime String date time value when this DMSDocument should expire
+	 * @return null
+	 */
+	function expireAtDate($datetime);
+
+	/**
+	 * Clears any previously set expiry.
+	 * @abstract
+	 * @return null
+	 */
+	function clearExpiry();
+
+	/*---- FROM HERE ON: optional API features ----*/
+
+	/**
+	 * Returns a DataList of all previous Versions of this DMSDocument (check the LastEdited date of each
+	 * object to find the correct one)
+	 * @abstract
+	 * @return DataList List of DMSDocument objects
+	 */
+	function getVersions();
+
+}

code/interface/DMSInterface.php

@@ -24,7 +24,7 @@ interface DMSInterface {
 	 * single-value tags on the Document.
 	 * @abstract
 	 * @param $file File object, or String that is path to a file to store
-	 * @return boolean Success or Failure of the store operation
+	 * @return DMSDocumentInstance Document object that we just created
 	 */
 	function storeDocument($file);
 
@@ -36,7 +36,7 @@ interface DMSInterface {
 	 * @param null $category The metadata category to search for
 	 * @param null $value The metadata value to search for
 	 * @param bool $showEmbargoed Boolean that specifies if embargoed documents should be included in results
-	 * @return DocumentInterface
+	 * @return DMSDocumentInterface
 	 */
 	function getByTag($category = null, $value = null, $showEmbargoed = false);
 
@@ -46,7 +46,7 @@ interface DMSInterface {
 	 * @abstract
 	 * @param $searchText String to search for
 	 * @param bool $showEmbargoed Boolean that specifies if embargoed documents should be included in results
-	 * @return DocumentInterface
+	 * @return DMSDocumentInterface
 	 */
 	function getByFullTextSearch($searchText, $showEmbargoed = false);
 

tests/DMSTest.php

@@ -0,0 +1,80 @@
+<?php
+class DMSTest extends SapphireTest {
+
+	static $testFile = 'dms/tests/DMS-test-lorum-file';
+
+	//store values to reset back to after this test runs
+	static $dmsFolderOld;
+	static $dmsFolderSizeOld;
+
+	function setUp() {
+		self::$dmsFolderOld = DMS::$dmsFolder;
+		self::$dmsFolderSizeOld = DMS::$dmsFolderSize;
+
+		//use a test DMS folder, so we don't overwrite the live one
+		DMS::$dmsFolder = 'dms-assets-test-1234';
+
+		//clear out the test folder (in case a broken test doesn't delete it)
+		$this->delete(BASE_PATH . DIRECTORY_SEPARATOR . DMS::$dmsFolder);
+	}
+
+	function tearDown() {
+		//delete the test folder after the test runs
+		$this->delete(BASE_PATH . DIRECTORY_SEPARATOR . DMS::$dmsFolder);
+
+		//set the old DMS folder back again
+		DMS::$dmsFolder = self::$dmsFolderOld;
+		DMS::$dmsFolderSize = self::$dmsFolderSizeOld;
+	}
+
+	public function delete($path) {
+	    $it = new RecursiveIteratorIterator(
+	        new RecursiveDirectoryIterator($path),
+	        RecursiveIteratorIterator::CHILD_FIRST
+	    );
+	    foreach ($it as $file) {
+	        if (in_array($file->getBasename(), array('.', '..'))) {
+	            continue;
+	        } elseif ($file->isDir()) {
+	            rmdir($file->getPathname());
+	        } elseif ($file->isFile() || $file->isLink()) {
+	            unlink($file->getPathname());
+	        }
+	    }
+	    rmdir($path);
+	}
+
+
+	function testDMSStorage() {
+		$dms = DMS::getDMSInstance();
+
+		$file = BASE_PATH . DIRECTORY_SEPARATOR . self::$testFile;
+		$document = $dms->storeDocument($file);
+
+		$this->assertNotNull($document, "Document object created");
+		$this->assertTrue(file_exists(DMS::$dmsPath . DIRECTORY_SEPARATOR . $document->Filename),"Document file copied into DMS folder");
+
+		//$title = $document->getTag('title');
+	}
+
+	function testDMSFolderSpanning() {
+		DMS::$dmsFolderSize = 5;
+		$dms = DMS::getDMSInstance();
+
+		$file = BASE_PATH . DIRECTORY_SEPARATOR . self::$testFile;
+
+		for($i = 0; $i <= 16; $i++) {
+			$document = $dms->storeDocument($file);
+			$this->assertNotNull($document, "Document object created on run number: $i");
+		}
+
+		//test we created 4 folder to contain the 17 files
+		$this->assertTrue(is_dir(DMS::$dmsPath . DIRECTORY_SEPARATOR . '1'));
+		$this->assertTrue(is_dir(DMS::$dmsPath . DIRECTORY_SEPARATOR . '2'));
+		$this->assertTrue(is_dir(DMS::$dmsPath . DIRECTORY_SEPARATOR . '3'));
+		$this->assertTrue(is_dir(DMS::$dmsPath . DIRECTORY_SEPARATOR . '4'));
+		$this->assertFalse(is_dir(DMS::$dmsPath . DIRECTORY_SEPARATOR . '5'));
+	}
+
+
+}