Merge pull request #345 from halkyon/config_upgrading_doc

MINOR Documentation for new Config system and DataExtension/extraStatics

docs/en/changelogs/3.0.0.md

@@ -27,6 +27,79 @@ Here's a list of steps to check:
  * Find and replace any references to `sapphire` in your custom code to `framework`. In your PHP code, you can use the constant `FRAMEWORK_DIR`,
 which points to the framework directory, and in the templates you can use `$ModulePath(framework)`
 
+### Object static functions replaced with new Config class [new-config] ###
+
+Static functions for getting a static variable on the `Object` class have been deprecated,
+in favour of using the new `Config` class instead.
+
+`Object::set_static('MyClass', 'myvar')` becomes `Config::inst()->update('MyClass', 'myvar', 'myval')` instead.
+`Object::addStaticVars('MyClass', array('myvar' => 'myval'))` should be replaced with individual calls to `Config::inst()->update()` instead.
+`Object::add_static_var('MyClass', 'myvar', 'myval')` becomes `Config::inst()->update('MyClass', 'myvar', 'myval')` instead.
+`Object::set_uninherited('MyClass', 'myvar', 'myval')` becomes `Config::inst()->update('MyClass', 'myvar', 'myval')` instead.
+
+Any arrays you pass as values to `update()` will be automatically merged. To replace the variable, call `remove()` first, then call `update()`.
+
+`Object::get_static('MyClass', 'myvar')` becomes `Config::inst()->get('MyClass', 'myvar', Config::FIRST_SET)`
+`Object::uninherited_static('MyClass', 'myvar')` becomes `Config::inst()->get('MyClass', 'myvar', Config::UNINHERITED)`
+`Object::combined_static('MyClass', 'myvar')` becomes `Config::inst()->get('MyClass', 'myvar')` (no option as third argument)
+
+Note the different options for the third parameter of `get()`:
+
+`Config::INHERITED` will only get the configuration set for the specific class, not any of it's parents.
+`Config::FIRST_SET` will inherit configuration from parents, but stop on the first class that actually provides a value.
+`Config::EXCLUDE_EXTRA_SOURCES` will not use additional static sources (such as those defined on extensions)
+
+If you don't set an option, it will get all the values for the static, including inherited ones.
+This was previously known as `Object::combined_static()`.
+
+### DataExtension and deprecated extraStatics on extension classes [extensions] ###
+
+`DataObjectDecorator` has been renamed to `DataExtension`. Any classes that extend `DataObjectDecorator`
+should now extend `DataExtension` instead.
+
+`extraStatics()` on extensions is now deprecated.
+
+Instead of using `extraStatics()`, you can simply define static variables on your extension directly.
+
+If you need custom logic, e.g. checking for a class before applying the statics on the extension,
+you can use `add_to_class()` as a replacement to `extraStatics()`.
+
+Given the original `extraStatics` function:
+
+	<?php
+	//...
+	function extraStatics($class, $extensionClass) {
+		if($class == 'MyClass') {
+			return array(
+				'db' => array(
+					'Title' => 'Varchar'
+				);
+			);
+		}
+	}
+
+This would now become a static function `add_to_class`, and calls `update()` with an array
+instead of returning it. It also needs to call `parent::add_to_class()`:
+
+	<?php
+	//...
+	static function add_to_class($class, $extensionClass, $args = null) {
+		if($class == 'MyClass') {
+			Config::inst()->update($class, 'db', array(
+				'Title' => 'Varchar'
+			));
+		}
+		parent::add_to_class($class, $extensionClass, $args);
+	}
+
+Alternatively, you can define statics on the extension directly, like this:
+
+	<?php
+	//...
+	static $db = array(
+		'Title' => 'Varchar'
+	);
+
 ### New ORM: More flexible and expressive querying via `DataList` [new-orm-datalist] ###
 
 The new "fluent" syntax to retrieve ORM records allows for a more