silverstripe-docsviewer/code/models/DocumentationEntity.php

<?php

/**
 * A {@link DocumentationEntity} represents a module or folder with 
 * documentation. An entity not an individual page but a `section` of 
 * documentation.
 *
 * Each section must have a version (defaults to `master`) which stores the 
 * actual path to the documentation (i.e framework 3.0, 3.1 docs point to 
 * different paths).
 *
 * Under each {@link DocumentationEntityVersion} contains languages. Most people
 * will just have the one `en` folder but that translates to the
 * {@link DocumentationEntityLanguage} instance to which the page relates to.
 * 
 * 
 * @package docsviewer
 * @subpackage models
 */

class DocumentationEntity extends ViewableData {
	
	/**
	 * @var array
	 */
	private static $casting = array(
		'Title' => 'Text'
	);
	
	/**
	 * @var string $title
	 */
	protected $title;

	/**
	 * @var string $folder
	 */
	protected $folder;

	/**
	 * @var ArrayList $versions
	 */
	protected $versions;

	/**
	 * If the system is setup to only document one entity then you may only 
	 * want to show a single entity in the URL and the sidebar. Set this when
	 * you register the entity with the key `DefaultEntity`
	 *
	 * @var boolean $default_entity
	 */
	protected $defaultEntity;

	/**
	 * Constructor. You do not need to pass the langs to this as
	 * it will work out the languages from the filesystem
	 *
	 * @param string $folder folder name
	 * @param string $title
	 */
	public function __construct($folder, $title = false) {
		$this->versions = new ArrayList();
		$this->folder = $folder;
		$this->title = (!$title) ? $folder : $title;
	}
	
	/**
	 * Get the title of this module.
	 *
	 * @return String
	 */
	public function getTitle() {
		return $this->title;
	}
	
	/**
	 * Return the versions which have been registered for this entity.
	 *
	 * @return array
	 */
	public function getVersions() {
		return $this->versions;
	}
	
	/**
	 * @return string|boo
	 */
	public function getStableVersion() {
		if(!$this->hasVersions()) {
			return false;
		}

		$sortedVersions = $this->getVersions()->toArray();
			
		usort($sortedVersions, create_function('$a,$b', 'return version_compare($a,$b);'));
			
		return array_pop($sortedVersions);
	}
	
	/**
	 * Return whether we have a given version of this entity
	 *
	 * @return bool
	 */
	public function hasVersion($version) {
		return $this->versions->find('Version', $version);
	}
	
	/**
	 * Return whether we have any versions at all0
	 *
	 * @return bool
	 */
	public function hasVersions() {
		return $this->versions->count() > 0;
	}
	
	/**
	 * Add another version to this entity
	 *
	 * @param DocumentationEntityVersion
	 */
	public function addVersion($version) {
		$this->versions->push($version);

		return $this;
	}
	
	/**
	 * Remove a version from this entity
	 *
	 * @param float $version
	 *
	 */
	public function removeVersion($version) {
		$this->versions->remove('Version', $version);

		return $this;
	}
	
	/**
	 * Return the absolute path to this documentation entity.
	 *
	 * @return string
	 */
	public function getPath() {
		return $this->path;
	}
	
	/**
	 * @return string
	 */
	public function getFolder() {
		return $this->folder;
	}

	/**
	 * Returns the web accessible link to this entity. This does not include any
	 * of the language information, the URL without the language should be a 
	 * permanent direct to 'en' documentation or the first language.
	 *
	 * @return string
	 */
	public function Link() {
		return ($this->getDefaultEntity()) 
			? Config::inst()->get('DocumentationViewer', 'link_base')
			: Controller::join_links(
				Config::inst()->get('DocumentationViewer', 'link_base'), 
				$this->getFolder()
			);
	}
	
	/**
	 * @return string
	 */
	public function __toString() {
		return sprintf('DocumentationEntity: %s)', $this->getPath());
	}

	/**
	 * @param DocumentationPage $page
	 *
	 * @return boolean
	 */
	public function hasRecord(DocumentationPage $page) {
		foreach($this->getVersions() as $version) {
			if(strstr($page->getPath(), $version->getPath()) !== false) {
				return true;
			}
		}
	}

	/**
	 * @param boolean $bool
	 */
	public function setDefaultEntity($bool) {
		$this->defaultEntity = $bool;

		return $this;
	}

	public function getDefaultEntity() {
		return $this->defaultEntity;
	}
}