Merge pull request #6560 from robbieaverill/feature/docs-for-upgrading-tasks-segment

DOCS Add note for $segment in BuildTask to 4.0.0 changelog, switch code blocks to GitHub style

docs/en/04_Changelogs/4.0.0.md

@@ -64,10 +64,11 @@ as a standard first point of upgrade.
 Nearly all core PHP classes have been namespaced. For example, `DataObject` is now called `SilverStripe\ORM\DataObject`.
 We have developed an [upgrader tool](https://github.com/silverstripe/silverstripe-upgrader/) to (semi-)automatically update your 3.x code to the new naming. Here's an example how to upgrade your `mysite` folder:
 
-	composer global require silverstripe/upgrader
+```
-	cd ~/Project/Root
+composer global require silverstripe/upgrader
-	~/.composer/vendor/bin/upgrade-code upgrade ./mysite --write
+cd ~/Project/Root
-
+~/.composer/vendor/bin/upgrade-code upgrade ./mysite --write
+```
 
 If you want to do a dry-run, omit the `--write` option to see a preview of a diff of
 all changed project files.
@@ -176,34 +177,33 @@ explicitly cast for that field.
 
 You can resolve this in your model by adding an explicit cast to HTML for those fields.
 
-
 Before:
 
-
+```php
-	:::php
+class MyObject extends ViewableData {
-	class MyObject extends ViewableData {
+	public function getSomeHTML {
-		public function getSomeHTML {
+		$title = Convert::raw2xml($this->Title);
-			$title = Convert::raw2xml($this->Title);
+		return "<h1>{$title}</h1>";
-			return "<h1>{$title}</h1>";
-		}
 	}
-
+}
+```
 
 After:
 
+```php
+class MyObject extends ViewableData
+{
+	private static $casting = [
+		'SomeHTML' => 'HTMLText'
+	];
 
-	:::php
+	public function getSomeHTML
-	class MyObject extends ViewableData {
+    {
-		private static $casting = [
+		$title = Convert::raw2xml($this->Title);
-			'SomeHTML' => 'HTMLText'
+		return "<h1>{$title}</h1>";
-		];
-
-		public function getSomeHTML {
-			$title = Convert::raw2xml($this->Title);
-			return "<h1>{$title}</h1>";
-		}
 	}
-
+}
+```
 
 If you need to encode a field (such as HTMLText) for use in html attributes, use `.ATT`
 instead, or if used in an actual XML file use `.CDATA` (see [template casting](/developer_guides/templates/casting)).
@@ -225,9 +225,10 @@ In order to retain existing file paths in line with framework version 3 you shou
 Note that this will not allow you to utilise certain file versioning features in 4.0.
 
 
-	:::yaml
+```
-	\SilverStripe\Filesystem\Flysystem\FlysystemAssetStore:
+SilverStripe\Filesystem\Flysystem\FlysystemAssetStore:
-	  legacy_paths: true
+  legacy_paths: true
+```
 
 
 See our ["File Management" guide](/developer_guides/files/file_management) for more information.
@@ -241,10 +242,10 @@ this task is run manually during an explicit migration process, as this process
 large amounts of memory and run for an extended time.
 
 
-	:::yaml
+```yaml
-	File:
+File:
-	  migrate_legacy_file: true
+  migrate_legacy_file: true
-
+```
 
 This task will also support migration of existing File DataObjects to file versioning. Any
 pre-existing File DataObjects will be automatically published to the live stage, to ensure
@@ -273,40 +274,38 @@ is intended to upload images for manipulation.
 
 Before:
 
-
+```php
-	:::php
+if($file instanceof Image) {
-	if($file instanceof Image) {
+	$upload = new UploadField();
-		$upload = new UploadField();
+	$upload->setAllowedFileCategories('image');
-		$upload->setAllowedFileCategories('image');
+}
-	}
+```
-
 
 After:
 
-
+```php
-	:::php
+if ($file->getIsImage()) {
-	if($file->getIsImage()) {
+	$upload = new UploadField();
-		$upload = new UploadField();
+	$upload->setAllowedFileCategories('image/supported');
-		$upload->setAllowedFileCategories('image/supported');
+}
-	}
+```
-
 
 In cases where image-only assets may be assigned to relationships then your datamodel should specify explicitly
 an `Image` datatype, or refer to `DBFile('image/supported')`.
 
 E.g.
 
-
+```php
-	:::php
+class MyObject extends DataObject
-	class MyObject extends DataObject {
+{
-		private static $has_one = array(
+	private static $has_one = array(
-			"ImageObject" => "Image"
+		"ImageObject" => "Image"
-		);
+	);
-		private static $db = array(
+	private static $db = array(
-			"ImageField" => "DBFile('image/supported')"
+		"ImageField" => "DBFile('image/supported')"
-		);
+	);
-	}
+}
-
+```
 
 #### Upgrading code that writes to `File` dataobjects, or writes files to the 'assets' folder
 
@@ -321,27 +320,27 @@ You would need to upgrade your code as below.
 Before:
 
 
-	:::php
+```php
-	function importTempFile($tmp) {
+function importTempFile($tmp) {
-		copy($tmp, ASSETS_PATH . '/imported/' . basename($tmp));
+	copy($tmp, ASSETS_PATH . '/imported/' . basename($tmp));
-		$file = new File();
+	$file = new File();
-		$file->setFilename('assets/imported/'.basename($tmp));
+	$file->setFilename('assets/imported/'.basename($tmp));
-		$file->write();
+	$file->write();
-	}
+}
-
+```
 
 After:
 
-
+```php
-	:::php
+public function importTempFile($tmp)
-	function importTempFile($tmp) {
+{
-	    Versioned::reading_stage('Stage');
+    Versioned::reading_stage('Stage');
-		$file = new File();
+    $file = new File();
-		$file->setFromLocalFile($tmp, 'imported/'.basename($tmp));
+    $file->setFromLocalFile($tmp, 'imported/' . basename($tmp));
-		$file->write();
+	$file->write();
-		$file->doPublish();
+	$file->doPublish();
-	}
+}
-
+```
 
 Note that 'assets' is no longer present in the new code, and the path beneath what was once assets is now
 used to generate the 'filename' value. This is because there is no longer an assumption that files are
@@ -356,12 +355,11 @@ There are other important considerations in working with File dataobjects which
   to the public site. You will need to make sure to invoke `->doPublish()` on any File DataObject
   you wish visitors to be able to see.
 
-You can disable File versioning by adding the following to your _config.php
+You can disable File versioning by adding the following to your `_config.php`
-
-
-    :::php
-    File::remove_extension('Versioned');
 
+```php
+File::remove_extension('Versioned');
+```
 
 #### Upgrading code performs custom image manipulations
 
@@ -375,48 +373,52 @@ For instance, code which sizes images to a fixed width should be updated as belo
 
 Before:
 
-
+```php
-	:::php
+// in MyImageExtension.php
-	// in MyImageExtension.php
+class MyImageExtension extends DataExtension
-	class MyImageExtension extends DataExtension {
+{
-		public function GalleryThumbnail($height) {
+	public function GalleryThumbnail($height)
-			return $this->getFormattedImage('GalleryThumbnail', $height);
+    {
-		}
+		return $this->getFormattedImage('GalleryThumbnail', $height);
-		public function generateGalleryThumbnail(Image_Backend $backend, $height) {
-			return $backend->paddedResize(300, $height);
-		}
 	}
 
-	// in _config.php
+	public function generateGalleryThumbnail(Image_Backend $backend, $height)
-	Image::add_extension('MyImageExtension');
+    {
+		return $backend->paddedResize(300, $height);
+	}
+}
 
+// in _config.php
+Image::add_extension('MyImageExtension');
+```
 
 Now image manipulations are implemented with a single method via a callback generator:
 
+```php
+// in MyImageExtension.php
+class MyImageExtension extends Extension
+{
+	public function GalleryThumbnail($height)
+    {
+		// Generates the manipulation key
+		$variant = $this->owner->variantName(__FUNCTION__, $height);
 
-	:::php
+		// Instruct the backend to search for an existing variant with this key,
-	// in MyImageExtension.php
+		// and include a callback used to generate this image if it doesn't exist
-	class MyImageExtension extends Extension {
+		return $this->owner->manipulateImage($variant, function (Image_Backend $backend) use ($height) {
-		public function GalleryThumbnail($height) {
+			return $backend->paddedResize(300, $height);
-			// Generates the manipulation key
+		});
-			$variant = $this->owner->variantName(__FUNCTION__, $height);
-
-			// Instruct the backend to search for an existing variant with this key,
-			// and include a callback used to generate this image if it doesn't exist
-			return $this->owner->manipulateImage($variant, function(Image_Backend $backend) use ($height) {
-				return $backend->paddedResize(300, $height);
-			});
-		}
 	}
+}
 
-	// in _config.php
+// in _config.php
-	File::add_extension('MyImageExtension');
+File::add_extension('MyImageExtension');
-	SilverStripe\Filesystem\Storage\DBFile::add_extension('MyImageExtension');
+\SilverStripe\Filesystem\Storage\DBFile::add_extension('MyImageExtension');
-
+```
 
 There are a few differences in this new API:
 
-* The extension is no longer specific to DataObjects, so it uses the generic 'Extension' class instead of 'DataExtension'
+* The extension is no longer specific to DataObjects, so it uses the generic `Extension` class instead of `DataExtension`
 * This extension is added to both `DBFile` and `File`, or order to make this manipulation available to non-dataobject
   file references as well, but it could be applied to either independently.
 * A helper method `variantName` is invoked in order to help generate a unique variant key. Custom code may use another
@@ -432,22 +434,23 @@ that handled saving of content into composite fields can be removed, as it is no
 
 The below describes the minimum amount of effort required to implement a composite DB field.
 
-	:::php
+```php
-	<?
+<?php
-	class MyAddressField extends DBComposite {
+class MyAddressField extends DBComposite
+{
+	private static $composite_db = array(
+		'Street' => 'Varchar(200)',
+		'Suburb' => 'Varchar(100)',
+		'City' => 'Varchar(100)',
+		'Country' => 'Varchar(100)'
+	);
 
-		private static $composite_db = array(
+	public function scaffoldFormField($title = null)
-			'Street' => 'Varchar(200)',
+    {
-			'Suburb' => 'Varchar(100)',
+		new AddressFormField($this->getName(), $title);
-			'City' => 'Varchar(100)',
-			'Country' => 'Varchar(100)'
-		);
-
-		public function scaffoldFormField($title = null) {
-			new AddressFormField($this->getName(), $title);
-		}
 	}
-
+}
+```
 
 #### Upgrading code that references `DataObject::database_fields` or `DataObject::db`
 
@@ -483,26 +486,46 @@ fix a table name, to prevent it being changed (for instance, when applying a nam
 the `table_name` config can be applied to any DataObject class.
 
 
-	:::php
+```php
-	namespace SilverStripe\BannerManager;
+namespace SilverStripe\BannerManager;
-	class BannerImage extends \DataObject {
-		private static $table_name = 'BannerImage';
-	}
 
+use SilverStripe\ORM\DataObject;
+
+class BannerImage extends DataObject
+{
+	private static $table_name = 'BannerImage';
+}
+```
 
 In order to ensure you are using the correct table for any class a new [api:DataObjectSchema] service
 is available to manage these mappings (see [versioned documentation](/developer_guides/model/data_model_and_orm)).
 
 
-	:::php
+```php
-	public function countDuplicates($model, $fieldToCheck) {
+public function countDuplicates($model, $fieldToCheck)
-		$table = DataObject::getSchema()->tableForField($model, $field);
+{
-		$query = new SQLSelect();
+	$table = DataObject::getSchema()->tableForField($model, $field);
-		$query->setFrom("\"{$table}\"");
+	$query = new SQLSelect();
-		$query->setWhere(["\"{$table}\".\"{$field}\"" => $model->$fieldToCheck]);
+	$query->setFrom("\"{$table}\"");
-		return $query->count();
+	$query->setWhere(["\"{$table}\".\"{$field}\"" => $model->$fieldToCheck]);
-	}
+	return $query->count();
+}
+```
 
+#### Upgrade BuildTask classes
+
+Similarly to the `$table_name` configuration property for DataObjects, you should define a `private static $segment` for `BuildTask`
+instances to ensure that you can still run your task via `sake dev/tasks/MyTask`. Without defining it, the default
+will be a fully-qualified class name like `sake dev/tasks/Me-MyModule-Tasks-MyTask`. This can also be configured in YAML.
+
+```php
+use SilverStripe\Dev\BuildTask;
+
+class MyTask extends BuildTask
+{
+    private static $segment = 'MyTask';
+}
+```
 
 #### Upgrade implementations of augmentSQL
 
@@ -511,27 +534,29 @@ type will raise a PHP error.
 
 Before:
 
-	:::php
+```php
-	function augmentSQL(SQLQuery &$query, DataQuery &$dataQuery = null) {
+function augmentSQL(SQLQuery &$query, DataQuery &$dataQuery = null) {
-		$locale = Translatable::get_current_locale();
+	$locale = Translatable::get_current_locale();
-		if(!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhere())))  {
+	if(!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhere())))  {
-			$qry = sprintf('"Locale" = \'%s\'', Convert::raw2sql($locale));
+		$qry = sprintf('"Locale" = \'%s\'', Convert::raw2sql($locale));
-			$query->addWhere($qry);
+		$query->addWhere($qry);
-		}
 	}
+}
+```
 
 After:
 
-	:::php
+```php
-	function augmentSQL(SQLSelect $query, DataQuery $dataQuery = null) {
+public function augmentSQL(SQLSelect $query, DataQuery $dataQuery = null)
-		$locale = Translatable::get_current_locale();
+{
-		if(!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhereParameterised($parameters))))  {
+	$locale = Translatable::get_current_locale();
-			$query->addWhere(array(
+	if (!preg_match('/("|\'|`)Locale("|\'|`)/', implode(' ', $query->getWhereParameterised($parameters))))  {
-				'"Locale"' => $locale
+		$query->addWhere(array(
-			));
+			'"Locale"' => $locale
-		}
+		));
 	}
-
+}
+```
 
 #### Upgrade code that modifies the behaviour of ErrorPage
 
@@ -553,29 +578,31 @@ In case that user code must customise this filename, such as for extensions whic
 for any error page, the extension point `updateErrorFilename` can be used. This extension point should
 also be used to replace any `alternateFilepathForErrorcode` used.
 
-
+```php
-	:::php
+class MyErrorPageExtension extends SiteTreeExtension
-	class MyErrorPageExtension extends SiteTreeExtension {
+{
-		public function updateErrorFilename(&$name, &$statuscode) {
+	public function updateErrorFilename(&$name, &$statuscode)
-			if($this->owner->exists()) {
+    {
-				$locale = $this->Locale;
+		if ($this->owner->exists()) {
-			} else {
+			$locale = $this->Locale;
-				$locale = Translatable::get_current_locale();
+		} else {
-			}
+			$locale = Translatable::get_current_locale();
-			$name = "error-{$statusCode}-{$locale}.html";
 		}
+		$name = "error-{$statusCode}-{$locale}.html";
 	}
+}
+```
 
-
+```yml
-	:::yaml
+ErrorPage:
-	ErrorPage:
+  extensions:
-	  extensions:
+    - MyErrorPageExtension
-	    - MyErrorPageExtension
+```
 
 #### Upgrading asset web.config, .htaccess, or other server configuration
 
 Server configuration files for `/assets` are no longer static, and are regenerated via a set of
-standard silverstripe templates on flush. These templates include:
+standard SilverStripe templates on flush. These templates include:
 
  * `Assets_HTAccess.ss`: Template for public permissions on the Apache server.
  * `Assets_WebConfig.ss`: Template for public permissions on the IIS server.
@@ -605,11 +632,12 @@ of items to disable.
 
 #### Upgrading TinyMCE to 4.0
 
- Please see the [tinymce upgrading guide](http://archive.tinymce.com/wiki.php/Tutorial:Migration_guide_from_3.x)
+Please see the [tinymce upgrading guide](http://archive.tinymce.com/wiki.php/Tutorial:Migration_guide_from_3.x)
- to assist with upgrades to customisations to tinymce 3.
+to assist with upgrades to customisations to tinymce 3.
+
+In Framework 4.0 the user interface for TinyMCE has been trimmed down considerably, with certain toolbar
+buttons removed from the default cms configuration. These include:
 
- In Framework 4.0 the user interface for TinyMCE has been trimmed down considerably, with certain toolbar
- buttons removed from the default cms configuration. These include:
  * Strikethrough
  * Styles dropdown
  * Block quotes
@@ -625,25 +653,26 @@ tinymce config, or by creating custom configurations.
 The optional `ss_macron` plugin for inserting Māori diacritical marks
 has been removed from core. You can configure the built-in `charmap` plugin instead:
 
-    :::php
+```php
-    $editor = HtmlEditorConfig::get('cms');
+$editor = HtmlEditorConfig::get('cms');
-    $editor->enablePlugins('charmap');
+$editor->enablePlugins('charmap');
-    $editor->addButtonsToLine(1, 'charmap');
+$editor->addButtonsToLine(1, 'charmap');
-    $editor->setOption('charmap_append', [
+$editor->setOption('charmap_append', [
-        ['256','A - macron'],
+    ['256','A - macron'],
-        ['274','E - macron'],
+    ['274','E - macron'],
-        ['298','I - macron'],
+    ['298','I - macron'],
-        ['332','O - macron'],
+    ['332','O - macron'],
-        ['362','U - macron'],
+    ['362','U - macron'],
-        ['257','a - macron'],
+    ['257','a - macron'],
-        ['275','e - macron'],
+    ['275','e - macron'],
-        ['299','i - macron'],
+    ['299','i - macron'],
-        ['333','o - macron'],
+    ['333','o - macron'],
-        ['363','u - macron']
+    ['363','u - macron']
-    ]);
+]);
+```
 
 For more information on available options and plugins please refer to the
-[tinymce documentation](https://www.tinymce.com/docs/configure/)
+[TinyMCE documentation](https://www.tinymce.com/docs/configure/)
 
 #### Upgrading DataObjects with the `Versioned` extension
 
@@ -654,26 +683,27 @@ Rather than declaring the list of stages a model has, the constructor for `Versi
 parameter, which declares whether or not the model is versioned and has a draft and live stage, or alternatively
 if it only has versioning without staging.
 
+```php
+/**
+ * This model has staging and versioning. Stages will be "Stage" and "Live"
+ */
+class MyStagedModel extends DataObject
+{
+	private staic $extensions = array(
+		"SilverStripe\\ORM\\Versioning\\Versioned('StagedVersioned')"
+	);
+}
 
-	:::php
+/**
-	/**
+ * This model has versioning only, and will not has a draft or live stage, nor be affected by the current stage.
-	 * This model has staging and versioning. Stages will be "Stage" and "Live"
+ */
-	 */
+class MyVersionedModel extends DataObject
-	class MyStagedModel extends DataObject {
+{
-		private staic $extensions = array(
+	private static $extensions = array(
-			"Versioned('StagedVersioned')"
+		"SilverStripe\\ORM\\Versioning\\Versioned('Versioned')"
-		);
+	);
-	}
+}
-
+```
-	/**
-	 * This model has versioning only, and will not has a draft or live stage, nor be affected by the current stage.
-	 */
-	class MyVersionedModel extends DataObject {
-		private static $extensions = array(
-			"Versioned('Versioned')"
-		);
-	}
-
 
 Additionally, the following api methods have been added:
 
@@ -721,41 +751,48 @@ An exception to this is any classes which once had the `SS_` prefix, which will
 
 Before:
 
-	class MyObject extends DataObject {
+```
-	    private static $db = array(
+class MyObject extends DataObject {
-	        'Number' => 'Int',
+    private static $db = array(
-	        'Time' => 'SS_Datetime'
+        'Number' => 'Int',
-	    );
+        'Time' => 'SS_Datetime'
+    );
 
-	    /**
+    /**
-	     * @param Int $val
+     * @param Int $val
-	     * @return Varchar
+     * @return Varchar
-	     */
+     */
-	    public function TextNumber() {
+    public function TextNumber() {
-	        return new Varchar('TextNumber', 'Number is ' . $this->Number);
+        return new Varchar('TextNumber', 'Number is ' . $this->Number);
-	    }
+    }
-	}
+}
+```
 
 After:
 
-	use SilverStripe\ORM\FieldType\DBVarchar;
+```php
+use SilverStripe\ORM\DataObject;
+use SilverStripe\ORM\FieldType\DBVarchar;
 
-	class MyObject extends DataObject {
+class MyObject extends DataObject
-	    private static $db = array(
+{
-	        'Number' => 'Int',
+    private static $db = array(
-	        'Time' => 'Datetime'
+        'Number' => 'Int',
-	    );
+        'Time' => 'Datetime'
+    );
 
-	    /**
+    /**
-	     * @param Int $val
+     * @param Int $val
-	     * @return Varchar
+     * @return Varchar
-	     */
+     */
-	    public function TextNumber() {
+    public function TextNumber()
-	        return new DBVarchar('TextNumber', 'Number is ' . $this->Number);
+    {
-	    }
+        return new DBVarchar('TextNumber', 'Number is ' . $this->Number);
-	}
+    }
+}
+```
 
-Note that string references to SS_Datetime passed to injector, or used in config values, will still work, and will refer to the updated class names.
+Note that string references to `SS_Datetime` passed to injector, or used in config values, will still work, and will refer to the updated class names.
 
 #### Upgrading from deprecated RestfulService