From f7946aec3391139ae1b4029c353c327a36552b36 Mon Sep 17 00:00:00 2001
From: Damian Mooyman <damian@silverstripe.com>
Date: Tue, 20 Jun 2017 16:00:40 +1200
Subject: [PATCH] Docs and minor cleanup

---
 docs/en/04_Changelogs/4.0.0.md | 33 +++++++++++++++++++++++++++++++++
 src/Core/Environment.php       |  4 +++-
 src/Core/HTTPApplication.php   | 20 ++++++++++----------
 3 files changed, 46 insertions(+), 11 deletions(-)

diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md
index 54d3a80f4..a150386a9 100644
--- a/docs/en/04_Changelogs/4.0.0.md
+++ b/docs/en/04_Changelogs/4.0.0.md
@@ -245,6 +245,30 @@ Extensions
     $has = DataObject::has_extension(File::class, Versioned::class); // alternate
     $extensions = DataObject::get_extensions(File::class);
 
+#### Upgrade references to Session object
+
+Session object is no longer statically accessible via `Session::inst()`. Instead, Session
+is a member of the current request.
+
+Before:
+
+    :::php
+    public function httpSubmission($data, $form, $request) {
+        Session::set('loggedIn', null);
+    }
+
+
+After:
+
+    :::php
+    public function httpSubmission($data, $form, $request) {
+        $requset->getSession()->set('loggedIn', null);
+    }
+
+
+In some places it may still be necessary to access the session object where no request is available.
+In rare cases it is still possible to access the request of the current controller via
+`Controller::curr()->getRequest()` to gain access to the current session.
 
 #### Compatibility with the new front-end building tools
 
@@ -1340,6 +1364,15 @@ After (`mysite/_config/config.yml`):
 
 #### <a name="overview-general-removed"></a>General and Core Removed API
 
+* `Session` object has had significant refactoring. This object no longer is accessed via
+  Session::inst(), but instead should be queried from the current request via `$request->getSession()`.
+  All static methods have been removed, and the `inst_` prefix removed from all instance members.
+  Please see the upgrading section on Session object for more details.
+* Request handling has changed slightly. `Director.rules` confing no longer support
+ `redirect:<url>` directly via config.
+* `Director::get_environment_type()` and `Director::set_environment_type()` are removed.
+  Get the `Kernel` instance via injector and query `getEnvironment()` instead.
+  E.g. `$type = Injector::inst()->get(Kernel::class)->getEnvironment();`.
 * Many global methods have been refactored into `Environment` or `Convert` class.
   * `increase_xdebug_nesting_level_to` removed (functionality has been inlined into `AppKernel`)
   * `set_increase_time_limit_max` moved to `Environment::setTimeLimitMax()`
diff --git a/src/Core/Environment.php b/src/Core/Environment.php
index c68415bde..f7d5aadb7 100644
--- a/src/Core/Environment.php
+++ b/src/Core/Environment.php
@@ -3,7 +3,9 @@
 namespace SilverStripe\Core;
 
 /**
- * Look wrapper around global environment variables
+ * Consolidates access and modification of PHP global variables and settings.
+ * This class should be used sparingly, and only if information cannot be obtained
+ * from a current {@link HTTPRequest} object.
  */
 class Environment
 {
diff --git a/src/Core/HTTPApplication.php b/src/Core/HTTPApplication.php
index 73eba9061..1e7a327d0 100644
--- a/src/Core/HTTPApplication.php
+++ b/src/Core/HTTPApplication.php
@@ -16,6 +16,16 @@ class HTTPApplication implements Application
      */
     protected $middlewares = [];
 
+    /**
+     * @var Kernel
+     */
+    protected $kernel;
+
+    public function __construct(Kernel $kernel)
+    {
+        $this->kernel = $kernel;
+    }
+
     /**
      * @return HTTPMiddleware[]
      */
@@ -64,16 +74,6 @@ class HTTPApplication implements Application
         return call_user_func($next, $request);
     }
 
-    /**
-     * @var Kernel
-     */
-    protected $kernel;
-
-    public function __construct(Kernel $kernel)
-    {
-        $this->kernel = $kernel;
-    }
-
     /**
      * Get the kernel for this application
      *