MONGOID-5365 Change #attributes return value to Hash with a flag (#5301)

* MONGOID-5365 Change #attributes return value to Hash with a flag

* MONGOID-5365 add config_override to tests

* MONGOID-5365 rename flag and flip default

* MONGOID-5365 fix old flag ref

Author: neilshweky

docs/reference/configuration.txt

@@ -368,6 +368,12 @@ for details on driver options.
       # to parent contexts by default. (default: false)
       join_contexts: false
 
+      # When this flag is true, the attributes method on a document will return
+      # a BSON::Document when that document is retrieved from the database, and
+      # a Hash otherwise. When this flag is false, the attributes method will
+      # always return a Hash. (default: false)
+      #legacy_attributes: true
+
       # Maintain legacy behavior of pluck and distinct, which does not demongoize
       # values on returning them. Setting this option to false will cause
       # pluck and distinct to return demongoized values. Setting this option to

docs/release-notes/mongoid-7.5.txt

@@ -87,3 +87,42 @@ The following functions are affected by this change:
 Mongoid 7.5 fixes incorrect usage of the driver's ``update_one`` method from
 Mongoid's ``upsert`` method. Mongoid's ``upsert`` actually performs a
 replacing upsert, and Mongoid 7.5 correctly calls ``replace_one``.
+
+
+Force the ``attributes`` Method to Always Return a ``Hash``
+```````````````````````````````````````````````````````````
+
+Mongoid 7.5 with the ``Mongoid.legacy_attributes`` option set to ``false``
+will always return a ``Hash`` when calling the ``attributes`` method.
+For example:
+
+.. code-block:: ruby
+
+  class Band
+    include Mongoid::Document
+
+    field :name
+  end
+
+  band = Band.create!(name: "The Rolling Stones")
+  p band.attributes.class
+  # => Hash
+
+  band = Band.first
+  p band.attributes.class
+  # => Hash
+
+In Mongoid 7.4 and earlier, and in 7.5 with the ``Mongoid.legacy_attributes``
+option set to ``true``, the ``attributes`` method on a document will return a
+``BSON::Document`` when retrieving that document from the database, but will
+return a ``Hash`` when instantiating a new document:
+
+.. code-block:: ruby
+
+  band = Band.create!(name: "The Rolling Stones")
+  p band.attributes.class
+  # => Hash
+
+  band = Band.first
+  p band.attributes.class
+  # => BSON::Document

docs/release-notes/mongoid-8.0.txt

@@ -31,17 +31,18 @@ Default Option Values Changed
 **Breaking change:** The following options have had their default values
 changed in Mongoid 8.0:
 
-- ``:overwrite_chained_operators`` => ``false``
 - ``:broken_aggregables`` => ``false``
 - ``:broken_alias_handling`` => ``false``
 - ``:broken_and`` => ``false``
 - ``:broken_scoping`` => ``false``
 - ``:broken_updates`` => ``false``
 - ``:compare_time_by_ms`` => ``true``
+- ``:legacy_attributes`` => true
 - ``:legacy_pluck_distinct`` => ``false``
 - ``:legacy_triple_equals`` => ``false``
 - ``:map_big_decimal_to_decimal128`` => ``true``
 - ``:object_id_as_json_oid`` => ``false``
+- ``:overwrite_chained_operators`` => ``false``
 
 Please refer to :ref:`configuration option <configuration-options>` for
 the description and effects of each of these options.

lib/mongoid/config.rb

@@ -119,6 +119,12 @@ module Config
     # using and's instead of overwriting them.
     option :overwrite_chained_operators, default: false
 
+    # When this flag is true, the attributes method on a document will return
+    # a BSON::Document when that document is retrieved from the database, and
+    # a Hash otherwise. When this flag is false, the attributes method will
+    # always return a Hash.
+    option :legacy_attributes, default: false
+
     # Has Mongoid been configured? This is checking that at least a valid
     # client config exists.
     #

lib/mongoid/document.rb

@@ -309,7 +309,12 @@ def instantiate(attrs = nil, selected_fields = nil, &block)
       #
       # @api private
       def instantiate_document(attrs = nil, selected_fields = nil, execute_callbacks: true)
-        attributes = attrs&.to_h || {}
+        attributes = if Mongoid.legacy_attributes
+          attrs
+        else
+          attrs&.to_h
+        end || {}
+
         doc = allocate
         doc.__selected_fields = selected_fields
         doc.instance_variable_set(:@attributes, attributes)

spec/mongoid/association/referenced/has_and_belongs_to_many/proxy_spec.rb

@@ -3815,6 +3815,8 @@ class Distributor
   # a BSON::Document, which applies a transformation to the array before
   # storing it.
   context "when executing concat on foreign key array from the db" do
+    config_override :legacy_attributes, false
+
     before do
       HabtmmContract.create!
       HabtmmSignature.create!

spec/mongoid/association/referenced/has_many/proxy_spec.rb

@@ -4140,6 +4140,8 @@
   end
 
   context "when executing concat on foreign key array from the db" do
+    config_override :legacy_attributes, false
+
     before do
       Agent.create!
       Basic.create!

spec/mongoid/attributes_spec.rb

@@ -1678,6 +1678,7 @@
     end
 
     context "when comparing the object_ids of the written value" do
+      config_override :legacy_attributes, false
 
       before do
         Person.create!

spec/mongoid/config_spec.rb

@@ -342,6 +342,13 @@
     it_behaves_like "a config option"
   end
 
+  context 'when setting the legacy_attributes option in the config' do
+    let(:option) { :legacy_attributes }
+    let(:default) { false }
+
+    it_behaves_like "a config option"
+  end
+
   describe "#load!" do
 
     before(:all) do