From 3dad856a1a116b8c87c178c32d7dfec3b1241860 Mon Sep 17 00:00:00 2001
From: Godfrey Chan <godfreykfc@gmail.com>
Date: Wed, 19 Mar 2014 15:19:44 -0700
Subject: [PATCH] Added a warning about serializing data with JSON cookie jars
 [skip ci]

Closes #14409
---
 guides/source/action_controller_overview.md | 24 +++++++++++++++++++++
 guides/source/upgrading_ruby_on_rails.md    | 24 +++++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/guides/source/action_controller_overview.md b/guides/source/action_controller_overview.md
index 1f9342ca25..0f46ba8698 100644
--- a/guides/source/action_controller_overview.md
+++ b/guides/source/action_controller_overview.md
@@ -619,6 +619,30 @@ It is also possible to pass a custom serializer that responds to `load` and
 Rails.application.config.action_dispatch.cookies_serializer = MyCustomSerializer
 ```
 
+When using the `:json` or `:hybrid` serializer, you should beware that not all
+Ruby objects can be serialized as JSON. For example, `Date` and `Time` objects
+will be serialized as strings, and `Hash`es will have their keys stringified.
+
+```ruby
+class CookiesController < ApplicationController
+  def set_cookie
+    cookies.encrypted[:expiration_date] = Date.tomorrow # => Thu, 20 Mar 2014
+    redirect_to action: 'read_cookie'
+  end
+
+  def read_cookie
+    cookies.encrypted[:expiration_date] # => "2014-03-20"
+  end
+end
+```
+
+It's advisable that you only store simple data (strings and numbers) in cookies.
+If you have to store complex objects, you would need to handle the conversion
+manually when reading the values on subsequent requests.
+
+If you use the cookie session store, this would apply to the `session` and
+`flash` hash as well.
+
 Rendering XML and JSON data
 ---------------------------
 
diff --git a/guides/source/upgrading_ruby_on_rails.md b/guides/source/upgrading_ruby_on_rails.md
index 7467648d49..d58024df3d 100644
--- a/guides/source/upgrading_ruby_on_rails.md
+++ b/guides/source/upgrading_ruby_on_rails.md
@@ -111,6 +111,30 @@ in your application, you can add an initializer file with the following content:
 This would transparently migrate your existing `Marshal`-serialized cookies into the
 new `JSON`-based format.
 
+When using the `:json` or `:hybrid` serializer, you should beware that not all
+Ruby objects can be serialized as JSON. For example, `Date` and `Time` objects
+will be serialized as strings, and `Hash`es will have their keys stringified.
+
+```ruby
+class CookiesController < ApplicationController
+  def set_cookie
+    cookies.encrypted[:expiration_date] = Date.tomorrow # => Thu, 20 Mar 2014
+    redirect_to action: 'read_cookie'
+  end
+
+  def read_cookie
+    cookies.encrypted[:expiration_date] # => "2014-03-20"
+  end
+end
+```
+
+It's advisable that you only store simple data (strings and numbers) in cookies.
+If you have to store complex objects, you would need to handle the conversion
+manually when reading the values on subsequent requests.
+
+If you use the cookie session store, this would apply to the `session` and
+`flash` hash as well.
+
 ### Flash structure changes
 
 Flash message keys are