Skip to content
This repository
Browse code

MINOR Upgrading notes

  • Loading branch information...
commit f8d38a332c9bd4f78435fe0d2c79db148b259cb6 1 parent d88a680
Ingo Schommer authored March 13, 2012
188  docs/en/changelogs/3.0.0.md
Source Rendered
@@ -13,6 +13,106 @@
13 13
 
14 14
 ## Upgrading ##
15 15
 
  16
+### New ORM: More flexible and expressive querying via `DataList` ###
  17
+
  18
+The new "fluent" syntax to retrieve ORM records allows for a more
  19
+expressive notation (instead of unnamed arguments). 
  20
+
  21
+	:::php
  22
+	// before
  23
+	DataObject::get('Member', '"FirstName" = \'Sam'\', '"Surname" ASC");
  24
+	// after
  25
+	DataList::create('Member')->filter(array('FirstName' => 'Sam'))->sort('Surname');
  26
+	
  27
+The underlying record retrieval and management is rewritten from scratch, and features
  28
+lazy loading which fetches only the records it needs, as late as possible.
  29
+In order to retrieve all ORM records manually (as the previous ORM would've done),
  30
+please use `DataList->toArray()`.
  31
+
  32
+The old getters (`DataObject::get()`, `DataObject:;get_one()`, `DataObject::get_by_id()`)
  33
+are now deprecated, but continue to operate. Instead of a `DataObjectSet`, they'll
  34
+now return a `DataList`.
  35
+
  36
+	:::php
  37
+	// before
  38
+	DataObject::get_one('Member', '"Email" = \'someone@example.com\'');
  39
+	// after
  40
+	DataList::create('Member')->filter('Email', 'someone@example.com')->First();
  41
+
  42
+	:::php
  43
+	// before
  44
+	DataObject::get_by_id('Member', 5);
  45
+	// after
  46
+	DataList::create('Member')->byID(5);
  47
+
  48
+Note that they will return a `DataList` even if they're empty, so if you want to check 
  49
+for the presence of records, please call the count() method on the `DataList`:
  50
+
  51
+	:::php
  52
+	// before
  53
+	if(!DataObject::get('SiteTree', '"ParentID" = 5')) echo "Page 5 has no children";
  54
+	// after
  55
+	if(!DataObject::get('SiteTree', '"ParentID" = 5')->count()) echo "Page 5 has no children";
  56
+
  57
+See the ["datamodel" documentation](../../topics/datamodel) for more details.
  58
+
  59
+### New ORM: Changes to manipulation of SQL queries ###
  60
+
  61
+In the 2.4 ORM it was sometimes necessary to bypass the ORM for performance reasons.  For example,
  62
+this command would have been intolerably slow:
  63
+
  64
+	:::php
  65
+	DataList::create('SiteTree')->count();
  66
+	
  67
+The 3.0 ORM is more intelligent gives you tools you need to create high-performance code without
  68
+bypassing the ORM:
  69
+
  70
+	:::php
  71
+	// before
  72
+	echo DB::query("SELECT COUNT(*) FROM \"SiteTree\"")->value();
  73
+	// after
  74
+	echo DataList::create('SiteTree')->count()
  75
+
  76
+Both `extendedSQL()` and `buildSQL()` have been deprecated.  There is not currently any way of 
  77
+overriding the query generation code equivalent to overriding `buildSQL()` in 2.4, but this facility
  78
+was error prone.  If you need to access the `SQLQuery` object, you can call `->dataQuery()->query()`
  79
+on any DataList.  Note that modifications to this query will **not** be passed back into the DataList.
  80
+
  81
+	:::php
  82
+	// before
  83
+	$query = singleton('SiteTree')->extendedSQL('ParentID = 5');
  84
+	// after
  85
+	$query = DataList::create('SiteTree')->filter('ParentID', 5)->dataQuery()->query();
  86
+
  87
+We advise that you keep this kind of code to a minimum and that you use the DataList wherever possible.
  88
+If you find yourself needing to bypass the ORM in SilverStripe 3, we suggest you raise this
  89
+as a discussion topic on silverstripe-dev@groups.google.com, as we may want to add more tools to
  90
+the ORM to help you.
  91
+
  92
+### New ORM: Better encapsulation of relationship queries with `RelationList` ###
  93
+
  94
+The abstract `RelationList` class and its implementations `ManyManyList` and `HasManyList`
  95
+are replacing the `ComponentSet` API, which is only relevant if you have instanciated these manually.
  96
+Relations are retrieved through the same way (e.g. `$myMember->Groups()`).
  97
+
  98
+### InnoDB driver for existing and new tables on MySQL (instead of MyISAM) ###
  99
+
  100
+SilverStripe has traditionally created all MySQL tables with the MyISAM storage driver,
  101
+mainly to ensure a fulltext search based on MySQL works out of the box.
  102
+Since then, the framework has gained many alternatives for fulltext search
  103
+([sphinx](https://github.com/silverstripe/silverstripe-sphinx), [solr](https://github.com/nyeholt/silverstripe-solr), etc.), and relies more on database transactions and other features not available in MyISAM.
  104
+
  105
+This change convert tables on existing databases when `dev/build` is called,
  106
+unless the `FullTextSearch` feature is enabled. In order to disable this behaviour,
  107
+you have to add the following code to your `_config.php` BEFORE running a `dev/build`:
  108
+
  109
+	:::php
  110
+	DataObject::$create_table_options['MySQLDatabase] = 'ENGINE=MyISAM';
  111
+
  112
+As with any SilverStripe upgrade, we recommend database backups before calling `dev/build`.
  113
+See [mysql.com](http://dev.mysql.com/doc/refman/5.5/en/converting-tables-to-innodb.html) for details on the conversion.
  114
+Note: MySQL has made InnoDB the default engine in its [5.5 release](http://dev.mysql.com/doc/refman/5.5/en/innodb-storage-engine.html).
  115
+
16 116
 ### GridField: Replacement for TableListField and ComplexTableField ###
17 117
 
18 118
 We have a new component for managing lists of objects: The `[GridField](/topics/grid-field)`.
@@ -58,7 +158,7 @@ The template engine has been completely rewritten, and although it is generally
58 158
 and some features have been deprecated. See the [template upgrading guide](/reference/templates-upgrading-guide) and the
59 159
 [template reference](/reference/templates) for more information.
60 160
 
61  
-#### Removed view-specific accessors from ViewableData ####
  161
+### Removed view-specific accessors from ViewableData ####
62 162
 
63 163
 Several methods in ViewableData that were originally added to expose values to the template language were moved,
64 164
 in order to stop polluting the namespace. These were sometimes called by project-specific PHP code too, and that code
@@ -126,42 +226,11 @@ please create a new CSS file and link it into the CMS via `[api:LeftAndMain::req
126 226
 
127 227
 ### Built-in Javascript validation removed ###
128 228
 
129  
-Built-in client-side form validation using behaviour.js has been removed, and is no longer supported.
130  
-
  229
+Built-in client-side form validation using `Validator.js` and `behaviour.js` has been removed, and is no longer supported.
131 230
 Server-side validation remains. Developers are encouraged to use custom Javascript validation on their
132 231
 forms if requiring client-side validation.
133  
-
134  
-These classes/files have been removed:
135  
-
136  
-	Validator.js
137  
-	CustomRequiredFields.php
138  
-
139  
-These functions are now deprecated and will throw a notice if used:
140  
-
141  
-	Validator::set_javascript_validation_handler()
142  
-	Validator::get_javascript_validator_handler()
143  
-	Validator::setJavascriptValidationHandler()
144  
-
145  
-These functions have been removed:
146  
-
147  
-	Validator::javascript() (abstract function)
148  
-	Validator::includeJavascriptValidation()
149  
-	FormField::jsValidation()
150  
-	AjaxUniqueTextField::jsValidation()
151  
-	ConfirmedPasswordField::jsValidation()
152  
-	CreditCardField::jsValidation()
153  
-	CurrencyField::jsValidation()
154  
-	CustomRequiredFields::javascript()
155  
-	DateField::jsValidation()
156  
-	DatetimeField::jsValidation()
157  
-	EmailField::jsValidation()
158  
-	FieldGroup::jsValidation()
159  
-	FormField::jsValidation()
160  
-	NumericField::jsValidation()
161  
-	PhoneNumberField::jsValidation()
162  
-	RequiredFields::javascript()
163  
-	TableField::jsValidation()
164  
-	TimeField::jsValidation()
  232
+You don't need to explicitly disable JS validation through `Validator::set_javascript_validation_handler()`
  233
+any longer (the method is deprecated).
165 234
 
166 235
 ### FormField consistently adds classes to HTML elements ###
167 236
 
@@ -235,6 +304,11 @@ IP restrictions for group memberships in the "Security" section were a rarely us
235 304
 and cluttered up the interface. We've decided to move it to a separate module
236 305
 called [securityextras](https://github.com/silverstripe-labs/silverstripe-securityextras).
237 306
 To continue using these restrictions, just install the module - no data migration required.
  307
+
  308
+### Moved comments system into new 'comments' module ###
  309
+
  310
+This affects websites which have comments enabled, through the `$Comments`
  311
+placeholder and the `PageComment` class. See the ['comments' module](https://github.com/silverstripe/silverstripe-comments). To continue using comments, simply install the module - no data migration required.
238 312
 	
239 313
 ### Removed "auto-merging" of member records from `Member->onBeforeWrite()`
240 314
 
@@ -260,26 +334,56 @@ Breadcrumbs have been altered to be their own template. In the process of this,
260 334
 SiteTree::$breadcrumbs_delimiter has been removed. To customise breadcrumbs now, create a template
261 335
 BreadcrumbsTemplate.ss from cms/template to your theme or application.
262 336
 
  337
+### Deprecation API ###
  338
+
  339
+There is a new deprecation API that generates deprecation notices.  Calls to Deprecated methods
  340
+will only produce errors if the API was deprecated in the release equal to or earlier than the
  341
+"notification version".
  342
+
  343
+`sapphire/_config.php` currently contains a call to throw notices calls to all methods deprecated 
  344
+in 3.0.
  345
+
  346
+	Deprecation::notification_version('3.0.0');
  347
+	
  348
+If you change the notification version to 3.0.0-dev, then only methods deprecated in older versions
  349
+(e.g. 2.4) will trigger notices, and the other methods will silently pass.  This can be useful if
  350
+you don't yet have time to remove all calls to deprecated methods.
  351
+
  352
+	Deprecation::notification_version('3.0.0-dev');
  353
+
263 354
 ### Deprecated Classes ###
264 355
 
  356
+ * `ComplexTableField`: Use `GridField` instead
  357
+ * `DataObjectDecorator`: Use `DataExtension` instead
  358
+ * `DataObjectSet`: Use `DataList` instead
265 359
  * `FileIframeField`: Use `UploadField`
  360
+ * `HasManyComplexTableField`: Use `GridField` instead
266 361
  * `ImageField`: Use `UploadField` with `$myField->allowedExtensions = array('jpg', 'gif', 'png')`
  362
+ * `ManyManyComplexTableField`: Use `GridField` instead
  363
+ * `SimpleImageField`: Use `FileField` or `UploadField` with `setAllowedExtensions()`
  364
+ * `TableListField`: Use `GridField` instead 
267 365
 
268 366
 ### Renamed Classes ###
269 367
 
  368
+ * `CMSMainMarkingFilter`: Use `CMSSiteTreeFilter_Search` instead * 
270 369
  * `DataObjectDecorator`: Use `DataExtension` instead (the class doesn't implement the [GOF "Decorator" pattern](http://en.wikipedia.org/wiki/Decorator_pattern))
271 370
  * `MySQLFulltextSearchable`: Use `FulltextSearchable` instead
272  
- * `CMSMainMarkingFilter`: Use `CMSSiteTreeFilter_Search` instead * 
273 371
 
274 372
 ### Removed Classes ###
275 373
 
276  
- * `QueuedEmail`, `QueuedEmailDispatchTask`: If you make use of these, copy the classes from 2.4 into your project.
277  
- * `RestrictedTextField`, `UniqueTextField`, `UniqueRestrictedTextField`, `AutocompleteTextField`, `ConfirmedFormAction`: Use custom fields instead
278  
- * `TreeSelectorField`: Use `TreeDropdownField` instead.
279  
- * `Notifications`: If you make use of this, copy the classes from 2.4 into your project.
280 374
  * `Archive`, `TarballArchive`: If you make use of these, copy the classes from 2.4 into your project.
281  
- * `XML`: Use PHP's built-in SimpleXML instead
  375
+ * `AssetTableField`: Use `GridField` with `GridFieldConfig_RelationEditor` instead
  376
+ * `ComponentSet`: Use `ManyManyList` or `HasManyList`
  377
+ * `CustomRequiredFields`: Use `RequiredFields`
282 378
  * `DataObjectLog`: There is no replacement for this.
  379
+ * `DataObjectSet`: Use `ArrayList` or `DataList` instead
  380
+ * `FieldSet`: Use `FieldList` instead
283 381
  * `GeoIP`: Moved to separate ["geoip" module](https://github.com/silverstripe-labs/silverstripe-geoip)
  382
+ * `MemberTableField`: Use `GridField` with `GridFieldConfig_RelationEditor` instead
  383
+ * `Notifications`: If you make use of this, copy the classes from 2.4 into your project.
284 384
  * `NZGovtPasswordValidator`: Moved to ["securityextras" module](https://github.com/silverstripe-labs/silverstripe-securityextras)
285  
-* `MemberTableField`: Use GridField with GridFieldConfig_RelationEditor instead
  385
+ * `QueuedEmail`, `QueuedEmailDispatchTask`: If you make use of these, copy the classes from 2.4 into your project.
  386
+ * `RestrictedTextField`, `UniqueTextField`, `UniqueRestrictedTextField`, `AutocompleteTextField`, `ConfirmedFormAction`: Use custom fields instead
  387
+ * `SQLMap`: Use `SS_Map` instead
  388
+ * `TreeSelectorField`: Use `TreeDropdownField` instead.
  389
+ * `XML`: Use PHP's built-in SimpleXML instead
116  docs/en/changelogs/alpha/3.0.0-alpha1.md
Source Rendered
@@ -18,122 +18,6 @@ See [3.0.0 upgrading guide](../3.0.0) for more details.
18 18
 
19 19
 ## Upgrading ##
20 20
 
21  
-### New ORM: More flexible and expressive querying via `DataList` ###
22  
-
23  
-The new "fluent" syntax to retrieve ORM records allows for a more
24  
-expressive notation (instead of unnamed arguments). 
25  
-
26  
-	// before
27  
-	DataObject::get('Member', '"FirstName" = \'Sam'\', '"Surname" ASC");
28  
-	// after
29  
-	DataList::create('Member')->filter(array('FirstName' => 'Sam'))->sort('Surname');
30  
-	
31  
-The underlying record retrieval and management is rewritten from scratch, and features
32  
-lazy loading which fetches only the records it needs, as late as possible.
33  
-In order to retrieve all ORM records manually (as the previous ORM would've done),
34  
-please use `DataList->toArray()`.
35  
-	
36  
-The old getters (`DataObject::get()`, `DataObject:;get_one()`, `DataObject::get_by_id()`)
37  
-are now deprecated, but continue to operate. Instead of a `DataObjectSet`, they'll
38  
-now return a `DataList`.
39  
-
40  
-	// before
41  
-	DataObject::get_one('Member', '"Email" = \'someone@example.com\'');
42  
-	// after
43  
-	DataList::create('Member')->filter('Email', 'someone@example.com')->First();
44  
-
45  
-	// before
46  
-	DataObject::get_by_id('Member', 5);
47  
-	// after
48  
-	DataList::create('Member')->byID(5);
49  
-
50  
-Note that they will return a `DataList` even if they're empty, so if you want to check 
51  
-for the presence of records, please call the count() method on the `DataList`:
52  
-
53  
-	// before
54  
-	if(!DataObject::get('SiteTree', '"ParentID" = 5')) echo "Page 5 has no children";
55  
-	// after
56  
-	if(!DataObject::get('SiteTree', '"ParentID" = 5')->count()) echo "Page 5 has no children";
57  
-
58  
-See the ["datamodel" documentation](../../topics/datamodel) for more details.
59  
-
60  
-### New ORM: Changes to manipulation of SQL queries ###
61  
-
62  
-In the 2.4 ORM it was sometimes necessary to bypass the ORM for performance reasons.  For example,
63  
-this command would have been intolerably slow:
64  
-
65  
-	DataList::create('SiteTree')->count();
66  
-	
67  
-The 3.0 ORM is more intelligent gives you tools you need to create high-performance code without
68  
-bypassing the ORM:
69  
-
70  
-	// before
71  
-	echo DB::query("SELECT COUNT(*) FROM \"SiteTree\"")->value();
72  
-	// after
73  
-	echo DataList::create('SiteTree')->count()
74  
-
75  
-Both `extendedSQL()` and `buildSQL()` have been deprecated.  There is not currently any way of 
76  
-overriding the query generation code equivalent to overriding `buildSQL()` in 2.4, but this facility
77  
-was error prone.  If you need to access the `SQLQuery` object, you can call `->dataQuery()->query()`
78  
-on any DataList.  Note that modifications to this query will **not** be passed back into the DataList.
79  
-
80  
-	// before
81  
-	$query = singleton('SiteTree')->extendedSQL('ParentID = 5');
82  
-	// after
83  
-	$query = DataList::create('SiteTree')->filter('ParentID', 5)->dataQuery()->query();
84  
-
85  
-We advise that you keep this kind of code to a minimum and that you use the DataList wherever possible.
86  
-If you find yourself needing to bypass the ORM in SilverStripe 3, we suggest you raise this
87  
-as a discussion topic on silverstripe-dev@groups.google.com, as we may want to add more tools to
88  
-the ORM to help you.
89  
-
90  
-### New ORM: Better encapsulation of relationship queries with `RelationList` ###
91  
-
92  
-The abstract `RelationList` class and its implementations `ManyManyList` and `HasManyList`
93  
-are replacing the `ComponentSet` API, which is only relevant if you have instanciated these manually.
94  
-Relations are retrieved through the same way (e.g. `$myMember->Groups()`).
95  
-
96  
-### InnoDB driver for existing and new tables on MySQL (instead of MyISAM) ###
97  
-
98  
-SilverStripe has traditionally created all MySQL tables with the MyISAM storage driver,
99  
-mainly to ensure a fulltext search based on MySQL works out of the box.
100  
-Since then, the framework has gained many alternatives for fulltext search
101  
-([sphinx](https://github.com/silverstripe/silverstripe-sphinx), [solr](https://github.com/nyeholt/silverstripe-solr), etc.), and relies more on database transactions and other features not available in MyISAM.
102  
-
103  
-This change convert tables on existing databases when `dev/build` is called,
104  
-unless the `FullTextSearch` feature is enabled. In order to disable this behaviour,
105  
-you have to add the following code to your `_config.php` BEFORE running a `dev/build`:
106  
-
107  
-	DataObject::$create_table_options['MySQLDatabase] = 'ENGINE=MyISAM';
108  
-
109  
-As with any SilverStripe upgrade, we recommend database backups before calling `dev/build`.
110  
-See [mysql.com](http://dev.mysql.com/doc/refman/5.5/en/converting-tables-to-innodb.html) for details on the conversion.
111  
-Note: MySQL has made InnoDB the default engine in its [5.5 release](http://dev.mysql.com/doc/refman/5.5/en/innodb-storage-engine.html).
112  
-
113  
-### Deprecation API ###
114  
-
115  
-There is a new deprecation API that generates deprecation notices.  Calls to Deprecated methods
116  
-will only produce errors if the API was deprecated in the release equal to or earlier than the
117  
-"notification version".
118  
-
119  
-`sapphire/_config.php` currently contains a call to throw notices calls to all methods deprecated 
120  
-in 3.0.
121  
-
122  
-	Deprecation::notification_version('3.0.0');
123  
-	
124  
-If you change the notification version to 3.0.0-dev, then only methods deprecated in older versions
125  
-(e.g. 2.4) will trigger notices, and the other methods will silently pass.  This can be useful if
126  
-you don't yet have time to remove all calls to deprecated methods.
127  
-
128  
-	Deprecation::notification_version('3.0.0-dev');
129  
-
130  
-### Deprecated Classes and Methods ###
131  
-
132  
- * `FieldSet`: Use `FieldList` instead
133  
- * `DataObjectSet`: Use `ArrayList` or `DataList` instead
134  
- * `SQLMap`: Use `SS_Map` instead
135  
- * `ComponentSet`: Use `ManyManyList` or `HasManyList`
136  
-
137 21
 See [3.0.0 upgrading guide](../3.0.0) for further details.
138 22
 
139 23
 ## Changelog ##

0 notes on commit f8d38a3

Please sign in to comment.
Something went wrong with that request. Please try again.