silverstripe-framework/docs/en/04_Changelogs/3.7.0.md

# 3.7.0

## SilverStripe 3.7 and PHP 7.2 and Object subclasses

### For Project Code

SilverStripe 3.7 now supports PHP 7.2, which is exciting, but PHP 7.2 introduces an `object` keyword.
To use it, you can replace any uses of `Object` with `SS_Object` in your own project code.

```diff
-class MyClass extends Object
+class MyClass extends SS_Object
{
	public function myFunction()
	{
-		$foo = Object::has_extension('MyExtension');
+		$foo = SS_Object::has_extension('MyExtension');
	}
}
```

You are also reliant on any SilverStripe modules directly using `Object` to upgrade their codebase.
Matches for `SS_Object` in the module codebase will tell you it's been upgraded.
A search for `extends Object` or `Object::` isn't fool proof, but will give you an indication
that the module still needs to be upgraded. If in doubt, check the module README.

### For Module Authors

If you are publishing a 3.x-compatible module that directly references the `Object` class,
we recommend that you replace all references to `Object` with `SS_Object`,
and add the following line to your module's `_config.php`
in order to support both current SilverStripe 3.x and SilverStripe 3.7 releases running on PHP 7.2:

```php
// Ensure compatibility with PHP 7.2 ("object" is a reserved word),
// with SilverStripe 3.6 (using Object) and SilverStripe 3.7 (using SS_Object)
if (!class_exists('SS_Object')) class_alias('Object', 'SS_Object');
```

Don't forget to mention explicit PHP 7.2 and SilverStripe 3.7 compatibility in your module README.

Note that in SilverStripe 4.x, the `Object` class was deleted so there isn’t an `SS_Object` class there either
(see [https://docs.silverstripe.org/en/4/changelogs/4.0.0/](changelog))

## Versioned cache segmentation

`SS_Cache` now maintains separate cache pools for each versioned stage. This prevents developers from caching draft data and then accidentally exposing it on the live stage without potentially required authorisation checks. Unless you rely on caching across stages, you don't need to change your own code for this change to take effect. Note that cache keys will be internally rewritten, causing any existing cache items to become invalid when this change is deployed.

```php
// Before:
$cache = SS_Cache::factory('myapp');
Versioned::set_reading_mode('Stage.Stage');
$cache->save('Some draft content. Not for public viewing yet.', 'my_key');
Versioned::set_reading_mode('Stage.Live');
$cache->load('my_key'); // 'Some draft content. Not for public viewing yet'

// After:
$cache = SS_Cache::factory('myapp');
Versioned::set_reading_mode('Stage.Stage');
$cache->save('Some draft content. Not for public viewing yet.', 'my_key');
Versioned::set_reading_mode('Stage.Live');
$cache->load('my_key'); // null
```
Data that is not content sensitive can be cached across stages by simply opting out of the segmented cache with the `disable-segmentation` argument.

```php
$cache = SS_Cache::factory('myapp', 'Output', array('disable-segmentation' => true));
``` 

## HTTP Cache Header changes

### Overview

In order to support developers in making safe choices around HTTP caching,
we've introduced a `HTTPCacheControl` class to control if a response
should be considered public or private. This is an abstraction on existing
lowlevel APIs like `HTTP::add_cache_headers()` and `SS_HTTPResponse->addHeader()`.

This change introduces smaller but necessary changes to HTTP caching headers
sent by SilverStripe. If you are relying on HTTP caching in your implementation,
or use modules such as [silverstripe/controllerpolicy](https://github.com/silverstripe/silverstripe-controllerpolicy),
please review the implications of these changes below. 

In short, these APIs make it easier to express your caching preferences
without running the risk of overriding essential core safety measures.
Most commonly, these APIs will prevent HTTP caching of draft content.

It will also prevent caching of content generated with an active session,
since the system can't tell whether session data was used to vary the output.
In this case, it's up to the developer to opt-in to caching,
after ensuring that certain execution paths are safe despite of using sessions.

The system behaviour does not guard against accidentally caching "private" content,
since there are too many variations under which output could be considered private
(e.g. a custom "approval" flag on a comment object). It is up to
the developer to ensure caching is used appropriately there.

By default, SilverStripe sends headers which signal to HTTP caches
that the response should be considered not cacheable.

See [Developer Guide: Performance > HTTP Cache Headers](/developer_guide/performance/http_cache_headers)
for details on the new API.

### Example Usage

#### Global opt-in for page content 

Enable caching for all page content (through `Page_Controller`).

```diff
class Page_Controller extends ContentController
{
    public function init()
    {
-        HTTP::set_cache_age(60);
+        HTTPCacheControl::inst()
+           ->enableCache()
+           ->setMaxAge(60); // 1 minute

        
        parent::init();
    }
}
```

Note: SilverStripe will still override this preference when a session is active,
a [CSRF token](/developer_guides/forms/form_security) token is present,
or draft content has been requested.

#### Opt-out for a particular controller action

If a controller output relies on session data, cookies,
permission checks or other triggers for conditional output,
you can disable caching either on a controller level
(through `init()`) or for a particular action.

```diff
class MyPage_Controller extends Page_Controller
{
    public function myprivateaction($request)
    {
        $response = $this->myPrivateResponse();
-        HTTP::set_cache_age(0);
+        HTTPCacheControl::inst()
+           ->disableCache();

        
        return $response;
    }
}
```

Note: SilverStripe will still override this preference when a session is active,
a [CSRF token](/developer_guides/forms/form_security) token is present,
or draft content has been requested.

#### Global opt-in, ignoring session (advanced)

This can be helpful in situations where forms are embedded on the website.
SilverStripe will still override this preference when draft content has been requested.
CAUTION: This mode relies on a developer examining each execution path to ensure
that no session data is used to vary output. 

Use case: By default, forms include a [CSRF token](/developer_guides/forms/form_security)
which starts a session with a value that's unique to the visitor, which makes the output uncacheable.
But any subsequent requests by this visitor will also carry a session, leading to uncacheable output
for this visitor. This is the case even if the output does not contain any forms,
and does not vary for this particular visitor.

```diff
class Page_Controller extends ContentController
{
    public function init()
    {
-        HTTP::set_cache_age(60);
+        HTTPCacheControl::inst()
+           ->enableCache($force=true) // DANGER ZONE
+           ->setMaxAge(60); // 1 minute

        
        parent::init();
    }
}
```

### Detailed Changes

 * Added `Cache-Control: no-store` header to default responses,
   to prevent intermediary HTTP proxies (e.g. CDNs) from caching unless developers opt-in
 * Removed `Cache-Control: no-transform` header from default responses
 * Removed `Vary: Cookie` as an unreliable cache buster,
   rely on the existing `Cache-Control: no-store` defaults instead
 * Removed `Vary: Accept`, since it's very uncommon to vary content on
   the `Content-Type` headers submitted through the request,
   and it can significantly decrease the likelyhood of a cache hit.
   Note this is different from `Vary: Accept-Encoding`,
   which is important for compression (e.g. gzip), and usually added by
   other layers such as Apache's mod_gzip.