API / BUG Fix DBField summary methods

Cleanup DBField subclasses
Fixes silverstripe#2929
Fixes silverstripe#1381
Fixes silverstripe#5547
Fixes silverstripe#1751

api/RSSFeed.php

@@ -307,7 +307,14 @@ public function Title() {
 	 * @return DBField Returns the description of the entry.
 	 */
 	public function Description() {
-		return $this->rssField($this->descriptionField);
+		$description = $this->rssField($this->descriptionField);
+
+		// HTML fields need links re-written
+		if($description instanceof DBHTMLText) {
+			return $description->obj('AbsoluteLinks');
+		}
+
+		return $description;
 	}
 
 	/**

core/Convert.php

@@ -189,6 +189,8 @@ public static function symbol2sql($identifier, $separator = '.') {
 	 * Convert XML to raw text.
 	 * @uses html2raw()
 	 * @todo Currently &#xxx; entries are stripped; they should be converted
+	 * @param mixed $val
+	 * @return array|string
 	 */
 	public static function xml2raw($val) {
 		if(is_array($val)) {
@@ -232,6 +234,7 @@ public static function json2array($val) {
 	 * false by default.
 	 * @param boolean $disableExternals Disables the loading of external entities. false by default.
 	 * @return array
+	 * @throws Exception
 	 */
 	public static function xml2array($val, $disableDoctypes = false, $disableExternals = false) {
 		// Check doctype
@@ -240,6 +243,7 @@ public static function xml2array($val, $disableDoctypes = false, $disableExterna
 		}
 
 		// Disable external entity loading
+		$oldVal = null;
 		if($disableExternals) $oldVal = libxml_disable_entity_loader($disableExternals);
 		try {
 			$xml = new SimpleXMLElement($val);
@@ -261,7 +265,7 @@ public static function xml2array($val, $disableDoctypes = false, $disableExterna
 	 * @return mixed
 	 */
 	protected static function recursiveXMLToArray($xml) {
-		if(is_object($xml) && get_class($xml) == 'SimpleXMLElement') {
+		if($xml instanceof SimpleXMLElement) {
 			$attributes = $xml->attributes();
 			foreach($attributes as $k => $v) {
 				if($v) $a[$k] = (string) $v;

docs/en/02_Developer_Guides/01_Templates/09_Casting.md

@@ -145,3 +145,16 @@ html. To ensure that the correct encoding is used for that field in a template,
 `$Field` by itself to allow the casting helper to determine the best encoding itself.
 </div>
 
+## Cast summary methods
+
+Certain subclasses of DBField also have additional summary or manipulations methods, each of
+which can be chained in order to perform more complicated manipulations.
+
+For instance, The following class methods can be used in templates for the below types:
+
+Text / HTMLText methods:
+
+* `$Plain` Will convert any HTML to plain text version. For example, could be used for plain-text
+  version of emails.
+* `$LimitSentences(<num>)` Will limit to the first `<num>` sentences in the content. If called on
+  HTML content this will have all HTML stripped and converted to plain text.

docs/en/04_Changelogs/4.0.0.md

@@ -49,6 +49,7 @@
    html fields as `HTMLText(['whitelist=meta,link'])`, or use a `ShortcodeHTMLText` as
    a shorthand substitute.
  * `FormField->dontEscape` has been removed. Escaping is now managed on a class by class basis.
+ * `DBString->LimitWordCountXML` removed. Use `LimitWordCount` for XML safe version.
 
 ## New API
 
@@ -103,6 +104,11 @@
  * `FormAction::setValidationExempt` can be used to turn on or off form validation for individual actions
  * `DataObject.table_name` config can now be used to customise the database table for any record.
  * `DataObjectSchema` class added to assist with mapping between classes and tables.
+ * Changes to `DBString` formatting:
+   * `NoHTML` is renamed to `Plain`
+   * `LimitWordCountXML` is removed. Use `LimitWordCount` instead.
+   * `BigSummary` is removed. Use `Summary` instead.
+   * Most limit methods on `DBHTMLText` now plain text rather than attempt to manipulate the underlying HTML.
    * `FormField::Title` and `FormField::RightTitle` are now cast as plain text by default (but can be overridden).
 
 ### Front-end build tooling for CMS interface
@@ -173,7 +179,7 @@ admin/font/                => admin/client/dist/font/
    * History.js
 
  * `debugmethods` querystring argument has been removed from debugging.
-
+ 
  * The following ClassInfo methods are now deprecated:
    * `ClassInfo::baseDataClass` - Use `DataObject::getSchema()->baseDataClass()` instead.
    * `ClassInfo::table_for_object_field` - Use `DataObject::getSchema()->tableForField()` instead

forms/gridfield/GridFieldLevelup.php

@@ -1,4 +1,6 @@
 <?php
+use SilverStripe\Model\FieldType\DBField;
+
 /**
  * Adds a "level up" link to a GridField table, which is useful when viewing
  * hierarchical data. Requires the managed record to have a "getParent()"
@@ -58,7 +60,7 @@ public function getHTMLFragments($gridField) {
 			foreach($attrs as $k => $v) $attrsStr .= " $k=\"" . Convert::raw2att($v) . "\"";
 
 			$forTemplate = new ArrayData(array(
-				'UpLink' => sprintf('<a%s></a>', $attrsStr)
+				'UpLink' => DBField::create_field('HTMLFragment', sprintf('<a%s></a>', $attrsStr))
 			));
 
 			return array(

model/FieldType/DBComposite.php

@@ -64,7 +64,7 @@ public function writeToManipulation(&$manipulation) {
 	 * to get to these columns. Will mostly just write to the {@link SQLSelect->select}
 	 * array.
 	 *
-	 * @param SQLSelect $query
+	 * @param \SQLSelect $query
 	 */
 	public function addToQuery(&$query) {
 		parent::addToQuery($query);
@@ -126,7 +126,7 @@ public function exists() {
 	public function requireField() {
 		foreach($this->compositeDatabaseFields() as $field => $spec){
 			$key = $this->getName() . $field;
-			DB::requireField($this->tableName, $key, $spec);
+			DB::require_field($this->tableName, $key, $spec);
 		}
 	}
 

model/FieldType/DBDate.php

@@ -33,11 +33,11 @@ class DBDate extends DBField {
 
 	/**
 	 * @config
-	 * @see SS_DateTime::nice_format
-	 * @see Time::nice_format
+	 * @see DBDateTime::nice_format
+	 * @see DBTime::nice_format
 	 */
 	private static $nice_format = 'd/m/Y';
-	
+
 	public function setValue($value, $record = null, $markChanged = true) {
 		if($value === false || $value === null || (is_string($value) && !strlen($value))) {
 			// don't try to evaluate empty values with strtotime() below, as it returns "1970-01-01" when it should be
@@ -67,9 +67,9 @@ public function setValue($value, $record = null, $markChanged = true) {
 		} elseif(is_string($value)) {
 			try{
 				$date = new DateTime($value);
-				$this->value = $date->Format('Y-m-d');
+				$this->value = $date->format('Y-m-d');
 				return;
-			}catch(Exception $e){
+			} catch(Exception $e) {
 				$this->value = null;
 				return;
 			}
@@ -78,71 +78,86 @@ public function setValue($value, $record = null, $markChanged = true) {
 
 	/**
 	 * Returns the date in the format specified by the config value nice_format, or dd/mm/yy by default
-	 */	 
+	 *
+	 * @return string
+	 */
 	public function Nice() {
-		if($this->value) return $this->Format($this->config()->nice_format);
+		return $this->Format($this->config()->nice_format);
 	}
 
 	/**
 	 * Returns the date in US format: “01/18/2006”
+	 *
+	 * @return string
 	 */
 	public function NiceUS() {
-		if($this->value) return $this->Format('m/d/Y');
+		return $this->Format('m/d/Y');
 	}
 
 	/**
 	 * Returns the year from the given date
+	 *
+	 * @return string
 	 */
 	public function Year() {
-		if($this->value) return $this->Format('Y');
+		return $this->Format('Y');
 	}
 
 	/**
 	 * Returns the Full day, of the given date.
+	 *
+	 * @return string
 	 */
 	public function Day(){
-		if($this->value) return $this->Format('l');
+		return $this->Format('l');
 	}
 
 	/**
 	 * Returns a full textual representation of a month, such as January.
+	 *
+	 * @return string
 	 */
 	public function Month() {
-		if($this->value) return $this->Format('F');
+		return $this->Format('F');
 	}
 
 	/**
 	 * Returns the short version of the month such as Jan
+	 *
+	 * @return string
 	 */
 	public function ShortMonth() {
-		if($this->value) return $this->Format('M');
+		return $this->Format('M');
 	}
 
 	/**
 	 * Returns the day of the month.
-	 * @param boolean $includeOrdinals Include ordinal suffix to day, e.g. "th" or "rd"
+	 *
+	 * @param boolean $includeOrdinal Include ordinal suffix to day, e.g. "th" or "rd"
 	 * @return string
 	 */
 	public function DayOfMonth($includeOrdinal = false) {
-		if($this->value) {
-			$format = 'j';
-			if ($includeOrdinal) $format .= 'S';
-			return $this->Format($format);
-		}
+		$format = 'j';
+		if ($includeOrdinal) $format .= 'S';
+		return $this->Format($format);
 	}
 
 	/**
 	 * Returns the date in the format 24 December 2006
+	 *
+	 * @return string
 	 */
 	public function Long() {
-		if($this->value) return $this->Format('j F Y');
+		return $this->Format('j F Y');
 	}
 
 	/**
 	 * Returns the date in the format 24 Dec 2006
+	 *
+	 * @return string
 	 */
 	public function Full() {
-		if($this->value) return $this->Format('j M Y');
+		return $this->Format('j M Y');
 	}
 
 	/**
@@ -154,20 +169,25 @@ public function Full() {
 	public function Format($format) {
 		if($this->value){
 			$date = new DateTime($this->value);
-			return $date->Format($format);
+			return $date->format($format);
 		}
+		return null;
 	}
 
 	/**
 	 * Return the date formatted using the given strftime formatting string.
 	 *
 	 * strftime obeys the current LC_TIME/LC_ALL when printing lexical values
 	 * like day- and month-names
+	 *
+	 * @param string $formattingString
+	 * @return string
 	 */
 	public function FormatI18N($formattingString) {
 		if($this->value) {
 			return strftime($formattingString, strtotime($this->value));
 		}
+		return null;
 	}
 
 	/**
@@ -192,10 +212,11 @@ public function FormatFromSettings($member = null) {
 		return $zendDate->toString($formatD);
 	}
 
-	/*
+	/**
 	 * Return a string in the form "12 - 16 Sept" or "12 Aug - 16 Sept"
-	 * @param Date $otherDateObj Another date object specifying the end of the range
-	 * @param boolean $includeOrdinals Include ordinal suffix to day, e.g. "th" or "rd"
+	 *
+	 * @param DBDate $otherDateObj
+	 * @param bool $includeOrdinals
 	 * @return string
 	 */
 	public function RangeString($otherDateObj, $includeOrdinals = false) {
@@ -211,12 +232,28 @@ public function RangeString($otherDateObj, $includeOrdinals = false) {
 		else return "$d1 - $d2 $m1 $y1";
 	}
 
+	/**
+	 * Return string in RFC822 format
+	 *
+	 * @return string
+	 */
 	public function Rfc822() {
-		if($this->value) return date('r', strtotime($this->value));
+		if($this->value) {
+			return date('r', strtotime($this->value));
+		}
+		return null;
 	}
 
+	/**
+	 * Return date in RFC2822 format
+	 *
+	 * @return string
+	 */
 	public function Rfc2822() {
-		if($this->value) return date('Y-m-d H:i:s', strtotime($this->value));
+		if($this->value) {
+			return date('Y-m-d H:i:s', strtotime($this->value));
+		}
+		return null;
 	}
 
 	public function Rfc3339() {
@@ -243,23 +280,24 @@ public function Rfc3339() {
 	 * @return  String
 	 */
 	public function Ago($includeSeconds = true, $significance = 2) {
-		if($this->value) {
-			$time = DBDatetime::now()->Format('U');
-			if(strtotime($this->value) == $time || $time > strtotime($this->value)) {
-				return _t(
-					'Date.TIMEDIFFAGO',
-					"{difference} ago",
-					'Natural language time difference, e.g. 2 hours ago',
-					array('difference' => $this->TimeDiff($includeSeconds, $significance))
-				);
-			} else {
-				return _t(
-					'Date.TIMEDIFFIN',
-					"in {difference}",
-					'Natural language time difference, e.g. in 2 hours',
-					array('difference' => $this->TimeDiff($includeSeconds, $significance))
-				);
-			}
+		if(!$this->value) {
+			return null;
+		}
+		$time = DBDatetime::now()->Format('U');
+		if(strtotime($this->value) == $time || $time > strtotime($this->value)) {
+			return _t(
+				'Date.TIMEDIFFAGO',
+				"{difference} ago",
+				'Natural language time difference, e.g. 2 hours ago',
+				array('difference' => $this->TimeDiff($includeSeconds, $significance))
+			);
+		} else {
+			return _t(
+				'Date.TIMEDIFFIN',
+				"in {difference}",
+				'Natural language time difference, e.g. in 2 hours',
+				array('difference' => $this->TimeDiff($includeSeconds, $significance))
+			);
 		}
 	}
 
@@ -298,7 +336,9 @@ public function TimeDiff($includeSeconds = true, $significance = 2) {
 	 * @return string The resulting formatted period
 	 */
 	public function TimeDiffIn($format) {
-		if(!$this->value) return false;
+		if(!$this->value) {
+			return null;
+		}
 
 		$time = DBDatetime::now()->Format('U');
 		$ago = abs($time - strtotime($this->value));
@@ -327,6 +367,9 @@ public function TimeDiffIn($format) {
 			case "years":
 				$span = round($ago/86400/365);
 				return ($span != 1) ? "{$span} "._t("Date.YEARS", "years") : "{$span} "._t("Date.YEAR", "year");
+
+			default:
+				throw new \InvalidArgumentException("Invalid format $format");
 		}
 	}