Upgrading rules for new inspect/warning capabilities

.upgrade.yml

@@ -953,3 +953,151 @@ excludedPaths:
   - '*vendor*'
 doctorTasks:
   SilverStripe\Dev\Upgrade\UpgradeBootstrap: src/Dev/Upgrade/UpgradeBootstrap.php
+warnings:
+  classes:
+    'Object':
+      message: 'Replaced with traits'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#object-replace'
+    'SS_Log':
+      message: 'Replaced with a PSR-3 logger'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#psr3-logging'
+    'Session':
+      message: 'Session is no longer statically accessible'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#session'
+    'SQLQuery':
+      message: 'Use SQLSelect instead'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#sqlquery'
+    'SilverStripe\AssetAdmin\Forms\UploadField':
+      message: 'Class implementations should be wrapped with FileHandleField'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#uploadfield'
+    'CompositeDBField':
+      message: 'Class has been replaced with an abstract DBComposite'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#compositedbfield'
+    'BuildTask':
+      message: 'Now needs a $segment property to run it'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#buildtask-segment'
+    'RestfulService':
+      message: 'Removed from core, please use Guzzle'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#restfulservice'
+    'Oembed':
+      message: 'Removed from core, please use third party lib'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#oembed'
+    'SS_Cache':
+      message: 'Using symfony/cache now'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#cache'
+    'LeftAndMain_TreeNode':
+      message: 'Renamed to CMSMain_TreeNode'
+    'SilverStripe\ORM\Hierarchy->getChildrenAsUL()':
+      message: 'Replaced with renderChildren()'
+    'SilverStripe\Security\Permission::flush_permission_cache()':
+      message: 'Renamed to reset()'
+  methods:
+    'setFilename()':
+      message: 'Filenames should not be set directly any more'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#write-file-dataobject'
+    'File::handle_shortcode()':
+      message: 'Has been removed'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#file-shortcode'
+    'database_fields()':
+      message: 'Does not have a second parameter any more'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#dataobject-db-database-fields'
+    'Authenticator::register()':
+      message: 'Custom authenticators work differently now'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#custom-authenticators'
+    'Object::useCustomClass()':
+      message: 'Use injector instead'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#custom-authenticators'
+    'Director::setUrlParams()':
+      message: 'Method removed'
+    'manyManyComponent()':
+      message: 'DataObject->manyManyComponent() moved to DataObjectSchema, access through getSchema()'
+    'belongsToComponent()':
+      message: 'DataObject->belongsToComponent() moved to DataObjectSchema, access through getSchema()'
+    'hasOneComponent()':
+      message: 'DataObject->hasOneComponent() moved to DataObjectSchema, access through getSchema()'
+    'hasManyComponent()':
+      message: 'DataObject->hasManyComponent() moved to DataObjectSchema, access through getSchema()'
+    'getRemoteJoinField()':
+      message: 'DataObject->getRemoteJoinField() moved to DataObjectSchema, access through getSchema()'
+    'has_own_table()':
+      message: 'DataObject::has_own_table() moved to DataObjectSchema->classHasTable(), access through getSchema()'
+    'database_fields()':
+      message: 'DataObject::database_fields() moved to DataObjectSchema->databaseFields(), access through getSchema()'
+    'database_fields()':
+      message: 'DataObject::database_fields() moved to DataObjectSchema->databaseFields(), access through getSchema()'
+    'manyManyExtraFieldsForComponent()':
+      message: 'DataObject::manyManyExtraFieldsForComponent() moved to DataObjectSchema, access through getSchema()'
+    'validateModelDefinitions()':
+      message: 'Removed DataObject->validateModelDefinitions()'
+    'hasOwnTableDatabaseField()':
+      message: 'DataObject->hasOwnTableDatabaseField() has been replaced with DataObjectSchema::fieldSpec(), access through getSchema()'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#dataobject-has-own'
+    'has_own_table_database_field()':
+      message: 'DataObject::has_own_table_database_field() has been replaced with DataObjectSchema::fieldSpec(), access through getSchema()'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#dataobject-has-own'
+    'hasDatabaseFields()':
+      message: 'DataObject->hasDatabaseFields() has been replaced with DataObjectSchema::fieldSpec(), access through getSchema()'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#dataobject-has-own'
+    'is_composite_field()'
+      message: 'Removed DataObject::is_composite_field. Use DataObjectSchema::compositeField instead.'
+    'custom_database_fields()':
+      message: 'Removed DataObject::custom_database_fields. Use DataObjectSchema::databaseFields'
+  props:
+    'class':
+      message: '$this->class access has been removed'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#object-replace'
+  functions:
+    'file_get_contents()':
+      message: 'Use new asset abstraction'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#asset-storage'
+    'file_put_contents()':
+      message: 'Use new asset abstraction'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#asset-storage'
+  constants:
+    'SS_TRUSTED_PROXY_HOST_HEADER':
+      message: 'See TrustedProxyMiddleware'
+    'SS_TRUSTED_PROXY_PROTOCOL_HEADER':
+      message: 'See TrustedProxyMiddleware'
+    'SS_TRUSTED_PROXY_IP_HEADER':
+      message: 'See TrustedProxyMiddleware'
+    'SS_TRUSTED_PROXY_HOST_HEADER':
+      message: 'See TrustedProxyMiddleware'
+    'MODULES_PATH':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'
+    'MODULES_DIR':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'
+    'FRAMEWORK_PATH':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'
+    'FRAMEWORK_DIR':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'
+    'CMS_PATH':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'
+    'CMS_DIR':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'
+    'FRAMEWORK_ADMIN_PATH':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'
+    'FRAMEWORK_ADMIN_DIR':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'
+    'FRAMEWORK_ADMIN_THIRDPARTY_DIR':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'
+    'THEMES_PATH':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'
+    'THEMES_DIR':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'
+    'THIRDPARTY_PATH':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'
+    'THIRDPARTY_DIR':
+      message: 'Path constants have been deprecated, use the Requirements and ModuleResourceLoader APIs'
+      url: 'https://docs.silverstripe.org/en/4/changelogs/4.0.0#module-paths'

docs/en/04_Changelogs/4.0.0.md

@@ -129,6 +129,20 @@ For a full list of renamed classes, check the `.upgrade.yml` definitions in each
 
 The rename won't affect class-based permission codes or database table names.
 
+##### Using the upgrader tool to get upgrade tips on your code
+
+While there's some code we can automatically rewrite, other uses of changed SilverStripe APIs aren't that obvious.
+You can use our heuristics to get some hints on where you need to review code manually.
+Hints will generally point to more detail about a specific upgrade in this guide.
+This task should be run *after* `upgrade-code upgrade`.
+
+```
+~/.composer/vendor/bin/upgrade-code inspect ./mysite
+```
+
+These hints only cover a part of the upgrade work,
+but can serve as a good indicator for where to start.
+
 ##### Upgrade references to literal or class table names
 
 In 3.x the class name of any DataObject matched the table name, but in 4.x all classes are namespaced, and it is
@@ -251,7 +265,7 @@ visibility) will make it 4.0 compatible.
 ];
 ```
 
-#### Upgrade module paths in file references
+#### <a name="module-paths"></a>Upgrade module paths in file references
 
 You should no longer rely on modules being placed in a deterministic folder (e.g. `/framework`),
 and use getters on the [Module](api:SilverStripe\Core\Manifest\Module) object instead.
@@ -340,7 +354,7 @@ or explicitly switch to the "copy" mode to avoid symlinks.
 The below sections deal with upgrades to specific parts of various API. Projects which rely on certain
 API should be upgraded as appropriate using any of the relevant processes documented below.
 
-#### Upgrade references of SS_Log to use PSR-3 logging
+#### <a name="psr3-logging"></a>Upgrade references of SS_Log to use PSR-3 logging
 
 One of the great changes that comes with SilverStripe 4 is the introduction of 
 [PSR-3](http://www.php-fig.org/psr/psr-3/) compatible logger interfaces. This 
@@ -398,7 +412,7 @@ implements the `Monolog\Formatter\FormatterInterface` interface.
 #### Upgrade `mysite/_config.php`
 
 The globals `$database` and `$databaseConfig` are deprecated. You should upgrade your
-site _config.php files to use the `.env` configuration (below).
+site `_config.php` files to use the `.env` configuration (below).
 
 `conf/ConfigureFromEnv.php` is also no longer used, and references to this file should be deleted.
 
@@ -488,7 +502,7 @@ which is no longer necessary.
 
 See [Environment Management docs](/getting-started/environment_management/) for full details.
 
-#### Replace usages of Object class
+#### <a name="object-replace"></a>Replace usages of Object class
 
 Object has been superseded by a trio of traits which replace components of this legacy class:
 
@@ -562,7 +576,7 @@ Extensions
 +$extensions = DataObject::get_extensions(File::class); // alternate
 ```
 
-#### Upgrade references to Session object
+#### <a name="session"></a>Upgrade references to Session object
 
 Session object is no longer statically accessible via `Session::inst()`. Instead, Session
 is a member of the current request.
@@ -740,6 +754,8 @@ class MyObject extends ViewableData
 After:
 
 ```php
+use SilverStripe\Core\Convert;
+
 class MyObject extends SilverStripe\View\ViewableData
 {
     private static $casting = [
@@ -748,7 +764,7 @@ class MyObject extends SilverStripe\View\ViewableData
 
     public function getSomeHTML
     {
-        $title = SilverStripe\Core\Convert::raw2xml($this->Title);
+        $title = Convert::raw2xml($this->Title);
         return "<h1>{$title}</h1>";
     }
 }
@@ -757,11 +773,11 @@ class MyObject extends SilverStripe\View\ViewableData
 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)).
 
-#### Upgrade code that uses SQLQuery
+#### <a name="sqlquery"></a>Upgrade code that uses SQLQuery
 
 Where your code once used SQLQuery you should now use SQLSelect in all cases, as this has been removed (check the [3.2.0](3.2.0) upgrading notes).
 
-#### Upgrade code that uses UploadField
+#### <a name="uploadfield"></a>Upgrade code that uses UploadField
 
 This field has been superceded by a new class provided by the
 [asset-admin](https://github.com/silverstripe/silverstripe-asset-admin) module, which provides a more
@@ -914,7 +930,7 @@ Consequently, we've also removed `MemberDatetimeOptionsetField`.
 the [IntlDateFormatter defaults](http://php.net/manual/en/class.intldateformatter.php) for the selected locale.
 
 
-#### New asset storage mechanism
+#### <a name="asset-storage"></a>New asset storage mechanism
 
 File system has been abstracted into an abstract interface. By default, the out of the box filesystem
 uses [Flysystem](http://flysystem.thephpleague.com/) with a local storage mechanism (under the assets directory).
@@ -1003,7 +1019,7 @@ class MyObject extends SilverStripe\ORM\DataObject
 }
 ```
 
-#### Upgrading code that writes to `File` dataobjects, or writes files to the 'assets' folder
+#### <a name="write-file-dataobject"></a>Upgrading code that writes to `File` dataobjects, or writes files to the 'assets' folder
 
 In the past all that was necessary to write a `File` DataObject to the database was to ensure a physical file
 existed in the assets folder, and that the Filename of the DataObject was set to the same location.
@@ -1118,7 +1134,7 @@ There are a few differences in this new API:
   A generic `manipulate` method may be used, although the callback for this method both is given, and should return,
   an `AssetStore` instance and file tuple (Filename, Hash, and Variant) rather than an Image_Backend.
 
-#### Upgrading code that uses File or Image shortcode handler
+#### <a name="file-shortcode"></a>Upgrading code that uses File or Image shortcode handler
 
 The `handle_shortcode` methods have been removed from the core File and Image classes and moved to separate classes in their own respective namespace. Image and File do not implement the ShortcodeHandler interface anymore.
 
@@ -1130,10 +1146,7 @@ Before this change, to use the handle_shortcode method, you would do something l
 <?php
 
 class MyShortcodeUser extends Object 
-
 {
-
-
     private $content;
 
     public function Content($arguments, $parser, $shortcode) 
@@ -1151,9 +1164,7 @@ In the new situation, this would look like this:
 use SilverStripe\Assets\Shortcodes\FileShortcodeProvider;
 
 class MyShortcodeUser extends Object 
-
 {
-
     private $content;
 
     public function Content($arguments, $parser, $shortcode) 
@@ -1163,7 +1174,7 @@ class MyShortcodeUser extends Object
 }
 ```
 
-#### Upgrading code that uses composite db fields.
+#### <a name="compositedbfield"></a>Upgrading code that uses composite db fields.
 
 The `CompositeDBField` interface has been replaced with an abstract class, `DBComposite`. In many cases, custom code
 that handled saving of content into composite fields can be removed, as it is now handled by the base class.
@@ -1173,7 +1184,7 @@ The below describes the minimum amount of effort required to implement a composi
 ```php
 use SilverStripe\ORM\FieldType\DBComposite;
 
-class MyAddressField extends DBComposite
+class MyAddressField extends
 {
     private static $composite_db = [
         'Street' => 'Varchar(200)',
@@ -1189,7 +1200,7 @@ class MyAddressField extends DBComposite
 }
 ```
 
-#### Upgrading code that references `DataObject::database_fields` or `DataObject::db`
+#### <a name="dataobject-db-database-fields"></a>Upgrading code that references `DataObject::database_fields` or `DataObject::db`
 
 These methods have been updated to include base fields (such as ID, ClassName, Created, and LastEdited), as
 well as composite DB fields.
@@ -1216,7 +1227,7 @@ these references should be replaced with `SQLSelect`. Legacy code which generate
 `SQLQuery` can still communicate with new code that expects `SQLSelect` as it is a
 subclass of `SQLSelect`, but the inverse is not true.
 
-#### Upgrade BuildTask classes
+#### <a name="buildtask-segment"></a>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
@@ -1523,7 +1534,7 @@ class MyObject extends DataObject
 
 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
+#### <a name="restfulservice"></a>Upgrading from deprecated RestfulService
 
 Install Guzzle to get an API consuming library.
 `composer require guzzlehttp/guzzle` or add `guzzlehttp/guzzle: "^6.0"` to your composer.json.
@@ -1532,7 +1543,7 @@ For information on how to use Guzzle, please see the extensive [Guzzle documenta
 
 In case you want to keep using RestfulService, you can use `Firesphere/silverstripe-restfulservice`, but it is unmaintained and deprecated.
 
-#### Upgrading from deprecated Oembed
+#### <a name="oembed"></a>Upgrading from deprecated Oembed
 
 Instead of Oembed, the framework now relies on [oscarotero/Embed](https://github.com/oscarotero/Embed) to handle getting the shortcode-data for embedding.
 If you have custom embedding-code relying on Oembed, please refer to the documentation provided by oscarotero.
@@ -1545,7 +1556,7 @@ to update those with the appropriate function or config call. See
 [CMS architecture](/developer_guides/customising_the_admin_interface/cms-architecture#the-admin-url) for language
 specific functions.
 
-#### Upgrading custom Authenticators
+#### <a name="custom-authenticators"></a>Upgrading custom Authenticators
 
 The methods `register` and `unregister` on `Authenticator` are deprecated in favor of the `Config` system. This means that any custom Authenticator needs to be registered through the yml config. For further information on how to create a custom authentication method, [see the Authentication documentation](/developer_guides/Security/Authentication).
 
@@ -1589,7 +1600,7 @@ One removed feature is the `Config::FIRST_SET` option. Either use uninherited co
 directly, or use the inherited config lookup. As falsey values now overwrite all parent class values, it is
 now generally safer to use the default inherited config, where in the past you would need to use `FIRST_SET`.
 
-#### Upgrading Cache API
+#### <a name="cache"></a>Upgrading Cache API
 
 We have replaced the unsupported `Zend_Cache` library with [symfony/cache](https://github.com/symfony/cache).
 This also allowed us to remove SilverStripe's `Cache` API and use dependency injection with a standard
@@ -1850,7 +1861,7 @@ that it belongs to, e.g. `themes/mytheme/templates/MyVendor/Foobar/Model/MyModel
 * Admin URL can now be configured via custom Director routing rule
 * `Controller::init` visibility changed to protected. Use `Controller::doInit()` instead.
 * `Controller::join_links` supports an array of link sections.
-* `Object::useCustomClass` has been removed. You should use the config API with Injector instead.
+* <a name="object-usecustomclass"></a>`Object::useCustomClass` has been removed. You should use the config API with Injector instead.
 * `Object::invokeWithExtensions` now has the same method signature as `Object::extend` and behaves the same way.
 * `ServiceConfigurationLocator` is now an interface not a class.
 * `i18nTextCollectorTask` merge is now true by default.
@@ -2163,18 +2174,18 @@ The below methods have been added or had their functionality updated to `DBDate`
 * `DataModel` removed
 * `DataObject::can*` methods no longer accept a member ID. These must now be passed a Member object or left null
 * `DataObject::db` removed and replaced with `DataObjectSchema::fieldSpec` and `DataObjectSchema::fieldSpecs`
-* `DataObject::manyManyComponent` moved to `DataObjectSchema`
+* `DataObject::manyManyComponent` moved to `DataObjectSchema` (access through `DataObject->getSchema()`)
-* `DataObject::belongsToComponent` moved to `DataObjectSchema`
+* `DataObject::belongsToComponent` moved to `DataObjectSchema` (access through `DataObject->getSchema()`)
-* `DataObject::hasOneComponent` moved to `DataObjectSchema`
+* `DataObject::hasOneComponent` moved to `DataObjectSchema` (access through `DataObject->getSchema()`)
-* `DataObject::hasManyComponent` moved to `DataObjectSchema`
+* `DataObject::hasManyComponent` moved to `DataObjectSchema` (access through `DataObject->getSchema()`)
-* `DataObject::getRemoteJoinField` moved to `DataObjectSchema`
+* `DataObject::getRemoteJoinField` moved to `DataObjectSchema` (access through `DataObject->getSchema()`)
-* `DataObject::database_fields` renamed and moved to `DataObjectSchema::databaseFields`
+* `DataObject::database_fields()` renamed and moved to `DataObjectSchema::databaseFields`
-* `DataObject::has_own_table` renamed and moved to `DataObjectSchema::classHasTable`
+* `DataObject::has_own_table()` renamed and moved to `DataObjectSchema::classHasTable`
-* `DataObject::composite_fields` renamed and moved to `DataObjectSchema::compositeFields``
+* `DataObject::composite_fields()` renamed and moved to `DataObjectSchema::compositeFields`
-* `DataObject::manyManyExtraFieldsForComponent` moved to `DataObjectSchema`
+* `DataObject::manyManyExtraFieldsForComponent()` moved to `DataObjectSchema`
 * `DataObject::$destroyed` is now deprecated
 * Removed `DataObject::validateModelDefinitions`. Relations are now validated within `DataObjectSchema`
-* Removed `DataObject` methods `hasOwnTableDatabaseField`, `has_own_table_database_field` and
+* <a name="dataobject-has-own"></a>Removed `DataObject` methods `hasOwnTableDatabaseField`, `has_own_table_database_field` and
   `hasDatabaseFields` are superceded by `DataObjectSchema::fieldSpec`.
   Use `$schema->fieldSpec($class, $field, DataObjectSchema::DB_ONLY | DataObjectSchema::UNINHERITED )`.
   Exclude `uninherited` option to search all tables in the class hierarchy.