README.md in rakismet-0.4.2 vs README.md in rakismet-1.0.0
- old
+ new
@@ -1,71 +1,75 @@
Rakismet
========
**Akismet** (<http://akismet.com/>) is a collaborative spam filtering service.
-**Rakismet** is easy Akismet integration with your Rails app, including
-support for TypePad's AntiSpam service.
+**Rakismet** is easy Akismet integration with Rails and rack apps. TypePad's
+AntiSpam service and generic Akismet endpoints are supported.
+Compatibility
+=============
-Setup
-=====
+**Rakismet 1.0.0** works with Rails 3 and other Rack-based frameworks.
+**Rakismet 0.4.2** is compatible with Rails 2.
-As a plugin
------------
+Getting Started
+===============
-Install with `script/plugin install git://github.com/joshfrench/rakismet`
+Once you've installed the Rakismet gem and added it to your application's Gemfile,
+you'll need an API key from the folks at WordPress. Head on over to
+http://wordpress.com/api-keys/ and sign up for a new username.
-Rakismet installation should have created a file called rakismet.rb in
-config/initializers. If not, you can copy the template from:
-vendor/plugins/rakismet/generators/rakismet/templates/config/initializers/rakismet.rb.
+Configure the Rakismet key and the URL of your application by setting the following
+in an initializer or application.rb:
-As a gem
---------
+ config.rakismet.key = 'your wordpress key'
+ config.rakismet.url = 'http://yourdomain.com/'
-`gem install rakismet`
+If you wish to use another Akismet-compatible API provider such as TypePad's
+antispam service, you'll also need to set `config.rakismet.host` to your service
+provider's endpoint.
-In config/environment.rb, require the gem by adding `config.gem 'rakismet'`
-within the config block.
+Checking For Spam
+-----------------
-From your app root, run `./script/generate rakismet` to create the Rakismet
-initializer.
+First, introduce Rakismet to your model:
-Getting Started
-===============
+ class Comment
+ include Rakismet::Model
+ end
-Once you've installed Rakismet via your method of choice, you'll need an API
-key from the folks at WordPress. Head on over to http://wordpress.com/api-keys/
-and sign up for a new username.
+With Rakismet mixed in to your model, you'll get three methods for interacting with
+Akismet:
-Edit config/initializers/rakismet.rb and fill in `Rakismet::URL` and
-`Rakismet::KEY` with the URL of your application and the key you received
-from WordPress.
+ * `spam?`
-If you wish to use another Akismet-compatible API provider such as TypePad's
-antispam service, you'll also need to change the `Rakismet::HOST` to your
-service provider's endpoint.
+Simply call `@comment.spam?` to get a true/false response. True means it's spam,
+false means it's not.
-Rakismet::Model
----------------
+ * `ham!` and
+ * `spam!`
-First, introduce Rakismet to your model:
+Akismet works best with your feedback. If you spot a comment that was
+erroneously marked as spam, `@comment.ham!` will resubmit to Akismet, marked
+as a false positive. Likewise if they missed a spammy comment,
+`@comment.spam!` will resubmit marked as spam.
- class Comment
- include Rakismet::Model
- end
+Configuring Your Model
+----------------------
+
Rakismet sends the following information to the spam-hungry robots at Akismet:
author : name submitted with the comment
author_url : URL submitted with the comment
author_email : email submitted with the comment
- comment_type : 'comment', 'trackback', 'pingback', or whatever you fancy
+ comment_type : Defaults to comment but you can set it to trackback, pingback, or something more appropriate
content : the content submitted
permalink : the permanent URL for the entry the comment belongs to
user_ip : IP address used to submit this comment
user_agent : user agent string
- referrer : http referer
+ referrer : referring URL (note the spelling)
By default, Rakismet just looks for attributes or methods on your class that
match these names. You don't have to have accessors that match these exactly,
however. If yours differ, just tell Rakismet what to call them:
@@ -83,74 +87,94 @@
belongs_to :author
rakismet_attrs :author => proc { author.name },
:author_email => proc { author.email }
end
-Rakismet::Controller
---------------------
-Perhaps you want to check a comment's spam status at creation time, and you
-have no need to keep track of request-specific information such as the user's
-IP, user agent, or referrer.
+You can even hard-code specific fields:
-You can add Rakismet to a controller and the IP, user agent, and referrer will
-be taken from the current request instead of your model instance.
+ class Trackback
+ include Rakismet::Model
+ rakismet_attrs :comment_type => "trackback"
+ end
- class MyController < ActionController::Base
- include Rakismet::Controller
- end
+Optional Request Variables
+--------------------------
-Since you probably won't be checking for spam in every action, Rakismet takes
-`:only` and `:except` options just like other filters. You can reduce overhead
-by specifying just the appropriate actions:
+Akismet wants certain information about the request environment: remote IP, the
+user agent string, and the HTTP referer when available. Normally, Rakismet
+asks your model for these. Storing this information on your model allows you to
+call the `spam?` method at a later time. For instance, maybe you're storing your
+comments in an administrative queue or processing them with a background job.
- class MyController < ActionController::Base
- include Rakismet::Controller
- rakismet_filter :only => :create
- end
+You don't need to have these three attributes on your model, however. If you
+choose to omit them, Rakismet will instead look at the current request (if one
+exists) and take the values from the request object instead.
-Checking For Spam
-=================
+This means that if you are **not storing the request variables**, you must call
+`spam?` from within the controller action that handles comment submissions. That
+way the IP, user agent, and referer will belong to the person submitting the
+comment. If you're not storing the request variables and you call `spam?` at a later
+time, the request information will be missing or invalid and Akismet won't be
+able to do its job properly.
-Rakismet provides three methods for interacting with Akismet:
+If you've decided to handle the request variables yourself, you can add this to your
+app initialization to disable the middleware responsible for tracking the request
+information:
- * `spam?`
+ config.rakismet.use_middleware = false
-Simply call `@comment.spam?` to get a true/false response. True means it's spam, false means it's not. Well, usually; it's possible something went wrong
-and Akismet returned an error message. `@comment.spam?` will return false if
-this happens. You can check `@comment.akismet_response` to be certain;
-anything other than 'true' or 'false' means you got an error. That said, as
-long as you're collecting the data listed above it's probably sufficient to
-check `spam?` alone.
+Verifying Responses
+-------------------
-Keep in mind that if you call `spam?` from within a controller action that
-uses the Rakismet filter, the user IP, user agent, and referrer will be taken
-from the current request regardless of what your model attributes are. In
-other words: if you're not verifying comments at the moment they're submitted,
-you probably want to store those attributes rather than rely on the controller
-methods.
+If you want to see what's happening behind the scenes, after you call one of
+`@comment.spam?`, `@comment.spam!` or `@comment.ham!` you can check
+`@comment.akismet_response`.
- * `ham!` and
- * `spam!`
+This will contain the last response from the Akismet server. In the case of `spam?`
+it should be `true` or `false.` For `spam!` and `ham!` it should be `Feedback received.`
+If Akismet returned an error instead (e.g. if you left out some required information)
+this will contain the error message.
-Akismet works best with your feedback. If you spot a comment that was
-erroneously marked as spam, `@comment.ham!` will resubmit to Akismet, marked
-as a false positive. Likewise if they missed a spammy comment,
-`@comment.spam!` will resubmit marked as spam.
+FAQ
+===
-Updating from Rakismet < 0.4
-----------------------------
-There were some significant changes to the API in version 0.4. This was done
-to make Rakismet easier to use with persistence layers other than
-ActiveRecord.
+Why does Akismet think all of my test data is spam?
+---------------------------------------------------
-If you're updating from an older version, please note:
+Akismet needs enough information to decide if your test data is spam or not.
+Try to supply as much as possible, especially the author name and request
+variables.
- * Rakismet is no longer automatically injected into ActiveRecord and
- ActionController. You'll need to manually include Rakismet with
- `include Rakismet::Model` and `include Rakismet::Controller`.
- * `ActiveRecord::Base#has_rakismet` now becomes
- `Rakismet::Model#rakismet_attrs`.
- * `ActionController::Base#has_rakismet` now becomes
- `Rakismet::Controller#rakismet_filter`.
+How can I simulate a spam submission?
+-------------------------------------
---------------------------------------------------------------
+Most people have the opposite problem, where Akismet doesn't think anything is
+spam. The only guaranteed way to trigger a positive spam response is to set the
+comment author to "viagra-test-123".
+
+If you've done this and `spam?` is still returning false, you're probably
+missing the user IP or one of the key/url config variables. One way to check is
+to call `@comment.akismet_response`. If you are missing a required field or
+there was another error, this will hold the Akismet error message. If your comment
+was processed normally, this value will simply be `true` or `false`.
+
+Can I use Rakismet with a different ORM or framework?
+-----------------------------------------------------
+
+Sure. Rakismet doesn't care what your persistence layer is. It will work with
+Datamapper, a NoSQL store, or whatever next month's DB flavor is.
+
+Rakismet also has no dependencies on Rails or any of its components, and only uses
+a small Rack middleware object to do some of its magic. Depending on your
+framework, you may have to modify this slightly and/or manually place it in your
+stack.
+
+You'll also need to set a few config variables by hand. Instead of
+`config.rakismet.key`, `config.rakismet.url`, and `config.rakismet.host`, set
+these values directly with `Rakismet.key`, `Rakismet.url`, and `Rakismet.host`.
+
+---------------------------------------------------------------------------
+
+If you have any implementation or usage questions, don't hesitate to get in
+touch: josh@vitamin-j.com.
+
Copyright (c) 2008 Josh French, released under the MIT license