From 0096f53b25e68c3fc79429253f816fff4a4ee596 Mon Sep 17 00:00:00 2001 From: Jon Leighton Date: Fri, 19 Oct 2012 15:56:18 +0100 Subject: nodoc the first_or_create methods and document alternatives --- activerecord/CHANGELOG.md | 14 ++++++-- activerecord/lib/active_record/relation.rb | 55 ++++++++++-------------------- activerecord/test/cases/relations_test.rb | 10 ++++++ 3 files changed, 39 insertions(+), 40 deletions(-) (limited to 'activerecord') diff --git a/activerecord/CHANGELOG.md b/activerecord/CHANGELOG.md index 1edcd7cfc8..ed5d0eebdf 100644 --- a/activerecord/CHANGELOG.md +++ b/activerecord/CHANGELOG.md @@ -24,9 +24,17 @@ Which obviously does not affect the scoping of queries within callbacks. - The `find_or_create_by` version also reads better, frankly. But note - that it does not allow attributes to be specified for the `create` - that are not included in the `find_by`. + The `find_or_create_by` version also reads better, frankly. + + If you need to add extra attributes during create, you can do one of: + + User.create_with(active: true).find_or_create_by(first_name: 'Jon') + User.find_or_create_by(first_name: 'Jon') { |u| u.active = true } + + The `first_or_create` family of methods have been nodoc'ed in favour + of this API. They may be deprecated in the future but their + implementation is very small and it's probably not worth putting users + through lots of annoying deprecation warnings. *Jon Leighton* diff --git a/activerecord/lib/active_record/relation.rb b/activerecord/lib/active_record/relation.rb index d106fceca2..2e2286e4fd 100644 --- a/activerecord/lib/active_record/relation.rb +++ b/activerecord/lib/active_record/relation.rb @@ -129,60 +129,41 @@ module ActiveRecord scoping { @klass.create!(*args, &block) } end - # Tries to load the first record; if it fails, then create is called with the same arguments as this method. - # - # Expects arguments in the same format as +Base.create+. - # - # Note that the create will execute within the context of this scope, and that may for example - # affect the result of queries within callbacks. If you don't want this, use the find_or_create_by - # method. + def first_or_create(attributes = nil, &block) # :nodoc: + first || create(attributes, &block) + end + + def first_or_create!(attributes = nil, &block) # :nodoc: + first || create!(attributes, &block) + end + + def first_or_initialize(attributes = nil, &block) # :nodoc: + first || new(attributes, &block) + end + + # Finds the first record with the given attributes, or creates a record with the attributes + # if one is not found. # # ==== Examples # # Find the first user named Penélope or create a new one. - # User.where(:first_name => 'Penélope').first_or_create + # User.find_or_create_by(first_name: 'Penélope') # # => # # # Find the first user named Penélope or create a new one. # # We already have one so the existing record will be returned. - # User.where(:first_name => 'Penélope').first_or_create + # User.find_or_create_by(first_name: 'Penélope') # # => # # # Find the first user named Scarlett or create a new one with a particular last name. - # User.where(:first_name => 'Scarlett').first_or_create(:last_name => 'Johansson') + # User.create_with(last_name: 'Johansson').find_or_create_by(first_name: 'Scarlett') # # => # # # Find the first user named Scarlett or create a new one with a different last name. # # We already have one so the existing record will be returned. - # User.where(:first_name => 'Scarlett').first_or_create do |user| + # User.find_or_create_by(first_name: 'Scarlett') do |user| # user.last_name = "O'Hara" # end # # => - def first_or_create(attributes = nil, &block) - first || create(attributes, &block) - end - - # Like first_or_create but calls create! so an exception is raised if the created record is invalid. - # - # Expects arguments in the same format as Base.create!. - def first_or_create!(attributes = nil, &block) - first || create!(attributes, &block) - end - - # Like first_or_create but calls new instead of create. - # - # Expects arguments in the same format as Base.new. - def first_or_initialize(attributes = nil, &block) - first || new(attributes, &block) - end - - # Finds the first record with the given attributes, or creates it if one does not exist. - # - # See also first_or_create. - # - # ==== Examples - # # Find the first user named Penélope or create a new one. - # User.find_or_create_by(first_name: 'Penélope') - # # => def find_or_create_by(attributes, &block) find_by(attributes) || create(attributes, &block) end diff --git a/activerecord/test/cases/relations_test.rb b/activerecord/test/cases/relations_test.rb index 7504da01d5..5f96145b47 100644 --- a/activerecord/test/cases/relations_test.rb +++ b/activerecord/test/cases/relations_test.rb @@ -1067,6 +1067,16 @@ class RelationTest < ActiveRecord::TestCase assert_equal bird, Bird.find_or_create_by(name: 'bob') end + def test_find_or_create_by_with_create_with + assert_nil Bird.find_by(name: 'bob') + + bird = Bird.create_with(color: 'green').find_or_create_by(name: 'bob') + assert bird.persisted? + assert_equal 'green', bird.color + + assert_equal bird, Bird.create_with(color: 'blue').find_or_create_by(name: 'bob') + end + def test_find_or_create_by! assert_raises(ActiveRecord::RecordInvalid) { Bird.find_or_create_by!(color: 'green') } end -- cgit v1.2.3