AnySMS
Simple and flexible solution to send sms in ruby, supporting variety of sms services.
Installation and usage
Add this line to your application's Gemfile:
gem "any_sms", "~> 0.4.0"Then somewhere in your initialization code:
require "any_sms"
require "logger"
AnySMS.configure do |config|
config.register_backend :my_backend_name,
AnySMS::Backend::Logger,
logger: Logger.new(STDOUT),
severity: :info
config.default_backend = :my_backend_name
endNow, whenever you need to send SMS, just do:
phone = "+10000000000"
text = "My sms text"
# Should print to console [SMS] +10000000000: text
AnySMS.send_sms(phone, text)Now your code is capable of sending sms. Later you may add any sms-backend you want, or even write your own.
Adding real sms backend
If you followed steps above, you code still doesn't really send sms.
It uses AnySMS::Backend::Logger
which actually just print sms contents to console.
To actually send sms you need gem-provider
or your own simple class.
Here's a list of my implementations for some sms services.
| Gem name | Sms service name |
|---|---|
| any_sms-backend-aws | Amazon Web Services SNS |
| any_sms-backend-smsru (russian) | sms.ru |
These gems documentation should be self explanatory.
Writing your own sms backend
Here's simple class that can be used by AnySMS:
require "any_sms"
class AnySMS::Backend::MyCustomBackend < AnySMS::Backend::Base
def initialize(params = {})
# your initialization which parses params if needed.
# the params here is the ones you set in initializer
# (you may also use keyword arguments instead)
@token = params.delete(:token)
end
def send_sms(phone, sms_text)
# your code to call your sms service
# or somehow else send actual sms
# if everything went fine, you may use helper from base class:
respond_with_status :success
# any other than :success response considered as failure
respond_with_status :not_enough_funds
# optionally you may return some metadata
respond_with_status :success, meta: { funds_left: 42 }
end
endThen in initializer:
require "any_sms"
require_relative "mycustombackend"
AnySMS.configure do |c|
c.register_backend :my_custom_backend,
AnySMS::Backend::MyCustomBackend,
token: ENV["token"]
c.default_backend = :my_custom_backend
endUsage:
# somewhere in your code
result = AnySMS.send_sms(phone, text)
if result.success?
# do stuff
else
# request failed
fail_status = result.status
# :not_enough_funds for example
end
# (optionally) Read metadata if any.
# Not recommended for control flow.
result.metaMultiple backends
You can specify which backend to use per call:
require "any_sms"
require_relative "mycustombackend"
AnySMS.configure do |c|
c.register_backend :my_custom_backend,
AnySMS::Backend::MyCustomBackend,
token: ENV["token"]
c.register_backend :null_sender, AnySMS::Backend::NullSender
c.default_backend = :my_custom_backend
end
phone = "799999999"
text = "My sms text"
# Uses default backend
AnySMS.send_sms(phone, text)
# Uses backend you specify
AnySMS.send_sms(phone, text, backend: :null_sender)Real life example
If you develop application in group, you probably don't want them all to send real SMS, and instead you would prefer to emulate sending, including SMS text preview (like SMS codes for registration).
However, on production you want to actually send them using your service. Here's how you can achieve that:
require "any_sms"
require_relative "mycustombackend"
require_relative "mycustombackend2"
AnySMS.configure do |c|
if development?
c.register_backend :my_custom_backend,
AnySMS::Backend::Logger,
logger: Logger.new(STDOUT),
severity: :info
# You can also, for example, specify different formatter for second one
logger = Logger.new(STDOUT)
logger.formatter = proc do |severity, datetime, progname, msg|
"[MYBackend2]: #{msg}\n"
end
c.register_backend :my_custom_backend2,
AnySMS::Backend::Logger,
logger: logger,
severity: :info
end
if test?
# Null sender does nothing when called for sending sms
c.register_backend :my_custom_backend, AnySMS::Backend::NullSender
c.register_backend :my_custom_backend2, AnySMS::Backend::NullSender
end
if production?
c.register_backend :my_custom_backend,
AnySMS::Backend::MyCustomBackend,
token: ENV["token"]
c.register_backend :my_custom_backend2,
AnySMS::Backend::MyCustomBackend2,
token: ENV["token2"]
end
c.default_backend = :my_custom_backend
end
phone = "799999999"
text = "My sms text"
# Uses default backend
AnySMS.send_sms(phone, text)
# Uses backend you specify
AnySMS.send_sms(phone, text, backend: :my_custom_backend2)
# depending on your initializer it may use different backends (like in this example)
# in different environments.Of course development?, test? and production? are not real methods.
You have to detect environment yourself somehow.
While possible, i strongly discourage to use more than two backends (One default, another is required in certain situations for some reason). It may make your code mess ;)
Testing
I am planning to make rspec matcher to test if sms was sent.
For now you may just mock AnySMS.send_sms and check it was executed.
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/Fedcomp/any_sms
Submitting a Pull Request
- Fork the official repository.
- Create a feature/bugfix branch.
- Implement your feature or bug fix.
- Add, commit, and push your changes.
- Submit a pull request.
- Please add tests if you changed code. Contributions without tests won't be accepted.
- If you don't know how to add tests, please put in a PR and leave a comment asking for help.
- Please don't update the Gem version.
( Inspired by https://github.com/thoughtbot/factory_girl/blob/master/CONTRIBUTING.md )
License
The gem is available as open source under the terms of the MIT License.
