Module: Devise::Models::Confirmable
- Extended by:
- ActiveSupport::Concern
- Defined in:
- lib/devise/models/confirmable.rb
Overview
Confirmable is responsible to verify if an account is already confirmed to sign in, and to send emails with confirmation instructions. Confirmation instructions are sent to the user email after creating a record and when manually requested by a new confirmation instruction request.
Confirmable tracks the following columns:
-
confirmation_token - A unique random token
-
confirmed_at - A timestamp when the user clicked the confirmation link
-
confirmation_sent_at - A timestamp when the confirmation_token was generated (not sent)
-
unconfirmed_email - An email address copied from the email attr. After confirmation
this value is copied to the email attr then cleared
Options
Confirmable adds the following options to devise
:
* +allow_unconfirmed_access_for+: the time you want to allow the user to access their account
before confirming it. After this period, the user access is denied. You can
use this to let your user access some features of your application without
confirming the account, but blocking it after a certain period (ie 7 days).
By default allow_unconfirmed_access_for is zero, it means users always have to confirm to sign in.
* +reconfirmable+: requires any email changes to be confirmed (exactly the same way as
initial account confirmation) to be applied. Requires additional unconfirmed_email
db field to be set up (t.reconfirmable in migrations). Until confirmed, new email is
stored in unconfirmed email column, and copied to email column on successful
confirmation.
* +confirm_within+: the time before a sent confirmation token becomes invalid.
You can use this to force the user to confirm within a set period of time.
Confirmable will not generate a new token if a repeat confirmation is requested
during this time frame, unless the user's email changed too.
Examples
User.find(1).confirm # returns true unless it's already confirmed
User.find(1).confirmed? # true/false
User.find(1).send_confirmation_instructions # manually send instructions
Defined Under Namespace
Modules: ClassMethods
Class Method Summary collapse
Instance Method Summary collapse
-
#active_for_authentication? ⇒ Boolean
Overwrites active_for_authentication? for confirmation by verifying whether a user is active to sign in or not.
-
#after_confirmation ⇒ Object
protected
A callback initiated after successfully confirming.
-
#confirm(args = {}) ⇒ Object
Confirm a user by setting it’s confirmed_at to actual time.
-
#confirmation_period_expired? ⇒ Boolean
protected
Checks if the user confirmation happens before the token becomes invalid Examples:.
-
#confirmation_period_valid? ⇒ Boolean
protected
Checks if the confirmation for the user is within the limit time.
-
#confirmation_required? ⇒ Boolean
protected
Callback to overwrite if confirmation is required or not.
-
#confirmed? ⇒ Boolean
Verifies whether a user is confirmed or not.
-
#generate_confirmation_token ⇒ Object
protected
Generates a new random token for confirmation, and stores the time this token is being generated in confirmation_sent_at.
- #generate_confirmation_token! ⇒ Object protected
-
#inactive_message ⇒ Object
The message to be shown if the account is inactive.
- #initialize(*args, &block) ⇒ Object
-
#pending_any_confirmation ⇒ Object
protected
Checks whether the record requires any confirmation.
- #pending_reconfirmation? ⇒ Boolean
- #postpone_email_change? ⇒ Boolean protected
- #postpone_email_change_until_confirmation_and_regenerate_confirmation_token ⇒ Object protected
- #reconfirmation_required? ⇒ Boolean protected
-
#resend_confirmation_instructions ⇒ Object
Resend confirmation token.
-
#send_confirmation_instructions ⇒ Object
Send confirmation instructions by email.
- #send_confirmation_notification? ⇒ Boolean protected
-
#send_on_create_confirmation_instructions ⇒ Object
protected
A callback method used to deliver confirmation instructions on creation.
- #send_reconfirmation_instructions ⇒ Object
-
#skip_confirmation! ⇒ Object
If you don’t want confirmation to be sent on create, neither a code to be generated, call skip_confirmation!.
-
#skip_confirmation_notification! ⇒ Object
Skips sending the confirmation/reconfirmation notification email after_create/after_update.
-
#skip_reconfirmation! ⇒ Object
If you don’t want reconfirmation to be sent, neither a code to be generated, call skip_reconfirmation!.
-
#skip_reconfirmation_in_callback! ⇒ Object
protected
To not require reconfirmation after creating with #save called in a callback call skip_create_confirmation!.
Class Method Details
.required_fields(klass) ⇒ Object
66 67 68 69 70 |
# File 'lib/devise/models/confirmable.rb', line 66 def self.required_fields(klass) required_methods = [:confirmation_token, :confirmed_at, :confirmation_sent_at] required_methods << :unconfirmed_email if klass.reconfirmable required_methods end |
Instance Method Details
#active_for_authentication? ⇒ Boolean
Overwrites active_for_authentication? for confirmation by verifying whether a user is active to sign in or not. If the user is already confirmed, it should never be blocked. Otherwise we need to calculate if the confirm time has not expired for this user.
140 141 142 |
# File 'lib/devise/models/confirmable.rb', line 140 def active_for_authentication? super && (!confirmation_required? || confirmed? || confirmation_period_valid?) end |
#after_confirmation ⇒ Object (protected)
A callback initiated after successfully confirming. This can be used to insert your own logic that is only run after the user successfully confirms.
Example:
def after_confirmation
self.update_attribute(:invite_code, nil)
end
290 291 |
# File 'lib/devise/models/confirmable.rb', line 290 def after_confirmation end |
#confirm(args = {}) ⇒ Object
Confirm a user by setting it’s confirmed_at to actual time. If the user is already confirmed, add an error to email field. If the user is invalid add errors
75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 |
# File 'lib/devise/models/confirmable.rb', line 75 def confirm(args={}) pending_any_confirmation do if confirmation_period_expired? self.errors.add(:email, :confirmation_period_expired, period: Devise::TimeInflector.time_ago_in_words(self.class.confirm_within.ago)) return false end self.confirmed_at = Time.now.utc saved = if pending_reconfirmation? skip_reconfirmation! self.email = unconfirmed_email self.unconfirmed_email = nil # We need to validate in such cases to enforce e-mail uniqueness save(validate: true) else save(validate: args[:ensure_valid] == true) end after_confirmation if saved saved end end |
#confirmation_period_expired? ⇒ Boolean (protected)
Checks if the user confirmation happens before the token becomes invalid Examples:
# confirm_within = 3.days and confirmation_sent_at = 2.days.ago
confirmation_period_expired? # returns false
# confirm_within = 3.days and confirmation_sent_at = 4.days.ago
confirmation_period_expired? # returns true
# confirm_within = nil
confirmation_period_expired? # will always return false
225 226 227 |
# File 'lib/devise/models/confirmable.rb', line 225 def confirmation_period_expired? self.class.confirm_within && self.confirmation_sent_at && (Time.now > self.confirmation_sent_at + self.class.confirm_within) end |
#confirmation_period_valid? ⇒ Boolean (protected)
Checks if the confirmation for the user is within the limit time. We do this by calculating if the difference between today and the confirmation sent date does not exceed the confirm in time configured. allow_unconfirmed_access_for is a model configuration, must always be an integer value.
Example:
# allow_unconfirmed_access_for = 1.day and confirmation_sent_at = today
confirmation_period_valid? # returns true
# allow_unconfirmed_access_for = 5.days and confirmation_sent_at = 4.days.ago
confirmation_period_valid? # returns true
# allow_unconfirmed_access_for = 5.days and confirmation_sent_at = 5.days.ago
confirmation_period_valid? # returns false
# allow_unconfirmed_access_for = 0.days
confirmation_period_valid? # will always return false
# allow_unconfirmed_access_for = nil
confirmation_period_valid? # will always return true
209 210 211 |
# File 'lib/devise/models/confirmable.rb', line 209 def confirmation_period_valid? self.class.allow_unconfirmed_access_for.nil? || (confirmation_sent_at && confirmation_sent_at.utc >= self.class.allow_unconfirmed_access_for.ago) end |
#confirmation_required? ⇒ Boolean (protected)
Callback to overwrite if confirmation is required or not.
183 184 185 |
# File 'lib/devise/models/confirmable.rb', line 183 def confirmation_required? !confirmed? end |
#confirmed? ⇒ Boolean
Verifies whether a user is confirmed or not
102 103 104 |
# File 'lib/devise/models/confirmable.rb', line 102 def confirmed? !!confirmed_at end |
#generate_confirmation_token ⇒ Object (protected)
Generates a new random token for confirmation, and stores the time this token is being generated in confirmation_sent_at
241 242 243 244 245 246 247 248 |
# File 'lib/devise/models/confirmable.rb', line 241 def generate_confirmation_token if self.confirmation_token && !confirmation_period_expired? @raw_confirmation_token = self.confirmation_token else self.confirmation_token = @raw_confirmation_token = Devise.friendly_token self.confirmation_sent_at = Time.now.utc end end |
#generate_confirmation_token! ⇒ Object (protected)
250 251 252 |
# File 'lib/devise/models/confirmable.rb', line 250 def generate_confirmation_token! generate_confirmation_token && save(validate: false) end |
#inactive_message ⇒ Object
The message to be shown if the account is inactive.
145 146 147 |
# File 'lib/devise/models/confirmable.rb', line 145 def !confirmed? ? :unconfirmed : super end |
#initialize(*args, &block) ⇒ Object
57 58 59 60 61 62 63 64 |
# File 'lib/devise/models/confirmable.rb', line 57 def initialize(*args, &block) @bypass_confirmation_postpone = false @skip_reconfirmation_in_callback = false @reconfirmation_required = false @skip_confirmation_notification = false @raw_confirmation_token = nil super end |
#pending_any_confirmation ⇒ Object (protected)
Checks whether the record requires any confirmation.
230 231 232 233 234 235 236 237 |
# File 'lib/devise/models/confirmable.rb', line 230 def pending_any_confirmation if (!confirmed? || pending_reconfirmation?) yield else self.errors.add(:email, :already_confirmed) false end end |
#pending_reconfirmation? ⇒ Boolean
106 107 108 |
# File 'lib/devise/models/confirmable.rb', line 106 def pending_reconfirmation? self.class.reconfirmable && unconfirmed_email.present? end |
#postpone_email_change? ⇒ Boolean (protected)
262 263 264 265 266 267 268 269 270 |
# File 'lib/devise/models/confirmable.rb', line 262 def postpone_email_change? postpone = self.class.reconfirmable && email_changed? && !@bypass_confirmation_postpone && self.email.present? && (!@skip_reconfirmation_in_callback || !self.email_was.nil?) @bypass_confirmation_postpone = false postpone end |
#postpone_email_change_until_confirmation_and_regenerate_confirmation_token ⇒ Object (protected)
254 255 256 257 258 259 260 |
# File 'lib/devise/models/confirmable.rb', line 254 def postpone_email_change_until_confirmation_and_regenerate_confirmation_token @reconfirmation_required = true self.unconfirmed_email = self.email self.email = self.email_was self.confirmation_token = nil generate_confirmation_token end |
#reconfirmation_required? ⇒ Boolean (protected)
272 273 274 |
# File 'lib/devise/models/confirmable.rb', line 272 def reconfirmation_required? self.class.reconfirmable && @reconfirmation_required && (self.email.present? || self.unconfirmed_email.present?) end |
#resend_confirmation_instructions ⇒ Object
Resend confirmation token. Regenerates the token if the period is expired.
130 131 132 133 134 |
# File 'lib/devise/models/confirmable.rb', line 130 def resend_confirmation_instructions pending_any_confirmation do send_confirmation_instructions end end |
#send_confirmation_instructions ⇒ Object
Send confirmation instructions by email
111 112 113 114 115 116 117 118 |
# File 'lib/devise/models/confirmable.rb', line 111 def send_confirmation_instructions unless @raw_confirmation_token generate_confirmation_token! end opts = pending_reconfirmation? ? { to: unconfirmed_email } : { } send_devise_notification(:confirmation_instructions, @raw_confirmation_token, opts) end |
#send_confirmation_notification? ⇒ Boolean (protected)
276 277 278 |
# File 'lib/devise/models/confirmable.rb', line 276 def send_confirmation_notification? confirmation_required? && !@skip_confirmation_notification && self.email.present? end |
#send_on_create_confirmation_instructions ⇒ Object (protected)
A callback method used to deliver confirmation instructions on creation. This can be overridden in models to map to a nice sign up e-mail.
178 179 180 |
# File 'lib/devise/models/confirmable.rb', line 178 def send_on_create_confirmation_instructions send_confirmation_instructions end |
#send_reconfirmation_instructions ⇒ Object
120 121 122 123 124 125 126 |
# File 'lib/devise/models/confirmable.rb', line 120 def send_reconfirmation_instructions @reconfirmation_required = false unless @skip_confirmation_notification send_confirmation_instructions end end |
#skip_confirmation! ⇒ Object
If you don’t want confirmation to be sent on create, neither a code to be generated, call skip_confirmation!
151 152 153 |
# File 'lib/devise/models/confirmable.rb', line 151 def skip_confirmation! self.confirmed_at = Time.now.utc end |
#skip_confirmation_notification! ⇒ Object
Skips sending the confirmation/reconfirmation notification email after_create/after_update. Unlike #skip_confirmation!, record still requires confirmation.
157 158 159 |
# File 'lib/devise/models/confirmable.rb', line 157 def skip_confirmation_notification! @skip_confirmation_notification = true end |
#skip_reconfirmation! ⇒ Object
If you don’t want reconfirmation to be sent, neither a code to be generated, call skip_reconfirmation!
163 164 165 |
# File 'lib/devise/models/confirmable.rb', line 163 def skip_reconfirmation! @bypass_confirmation_postpone = true end |
#skip_reconfirmation_in_callback! ⇒ Object (protected)
To not require reconfirmation after creating with #save called in a callback call skip_create_confirmation!
171 172 173 |
# File 'lib/devise/models/confirmable.rb', line 171 def skip_reconfirmation_in_callback! @skip_reconfirmation_in_callback = true end |