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 ++++++ guides/source/active_record_querying.md | 39 ++++++--------------- 4 files changed, 50 insertions(+), 68 deletions(-) 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 diff --git a/guides/source/active_record_querying.md b/guides/source/active_record_querying.md index 5e6799e786..76548a3397 100644 --- a/guides/source/active_record_querying.md +++ b/guides/source/active_record_querying.md @@ -1227,7 +1227,7 @@ Find or build a new object It's common that you need to find a record or create it if it doesn't exist. You can do that with the `find_or_create_by` and `find_or_create_by!` methods. -### `find_or_create_by` and `first_or_create` +### `find_or_create_by` The `find_or_create_by` method checks whether a record with the attributes exists. If it doesn't, then `create` is called. Let's see an example. @@ -1251,13 +1251,18 @@ COMMIT The new record might not be saved to the database; that depends on whether validations passed or not (just like `create`). -Suppose we want to set the 'locked' attribute to true, if we're +Suppose we want to set the 'locked' attribute to true if we're creating a new record, but we don't want to include it in the query. So we want to find the client named "Andy", or if that client doesn't exist, create a client named "Andy" which is not locked. -We can achive this in two ways. The first is passing a block to the -`find_or_create_by` method: +We can achive this in two ways. The first is to use `create_with`: + +```ruby +Client.create_with(locked: false).find_or_create_by(first_name: 'Andy') +``` + +The second way is using a block: ```ruby Client.find_or_create_by(first_name: 'Andy') do |c| @@ -1268,23 +1273,7 @@ end The block will only be executed if the client is being created. The second time we run this code, the block will be ignored. -The second way is using the `first_or_create` method: - -```ruby -Client.where(first_name: 'Andy').first_or_create(locked: false) -``` - -In this version, we are building a scope to search for Andy, and getting -the first record if it existed, or else creating it with `locked: -false`. - -Note that these two are slightly different. In the second version, the -scope that we build will affect any other queries that may happens while -creating the record. For example, if we had a callback that ran -another query, that would execute within the `Client.where(first_name: -'Andy')` scope. - -### `find_or_create_by!` and `first_or_create!` +### `find_or_create_by!` You can also use `find_or_create_by!` to raise an exception if the new record is invalid. Validations are not covered on this guide, but let's assume for a moment that you temporarily add @@ -1299,10 +1288,7 @@ Client.find_or_create_by!(first_name: 'Andy') # => ActiveRecord::RecordInvalid: Validation failed: Orders count can't be blank ``` -There is also a `first_or_create!` method which does a similar thing for -`first_or_create`. - -### `find_or_initialize_by` and `first_or_initialize` +### `find_or_initialize_by` The `find_or_initialize_by` method will work just like `find_or_create_by` but it will call `new` instead of `create`. This @@ -1334,9 +1320,6 @@ nick.save # => true ``` -There is also a `first_or_initialize` method which does a similar thing -for `first_or_create`. - Finding by SQL -------------- -- cgit v1.2.3