Class: Akismet::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/akismet/client.rb

Instance Attribute Summary collapse

Constructors collapse

Managing Connections collapse

Verifying Keys collapse

Checking collapse

Reporting collapse

Constructor Details

#initialize(api_key, app_url, options = {}) ⇒ Client

Returns a new instance of Client.

Parameters:

  • api_key (String)

    The API key obtained at akismet.com

  • app_url (String)

    The URL of the home page of the application making the request

  • options (Hash) (defaults to: {})

    a customizable set of options

Options Hash (options):

  • :app_name (String)

    The name of the application making the request, e.g. “jonahb.com”. Forms part of the User-Agent header submitted to Akismet.

  • :app_version (String)

    The version of the application making the request, e.g. “1.0”. Forms part of the User-Agent header submitted to Akismet. Ignored if :app_name is not provided.



39
40
41
42
43
44
45
# File 'lib/akismet/client.rb', line 39

def initialize(api_key, app_url, options = {})
  @api_key = api_key
  @app_url = app_url
  @app_name = options[ :app_name ]
  @app_version = options[ :app_version ]
  @http_session = nil
end

Instance Attribute Details

#api_keyString (readonly)

The API key obtained at akismet.com

Returns:

  • (String)


11
12
13
# File 'lib/akismet/client.rb', line 11

def api_key
  @api_key
end

#app_nameString (readonly)

The name of the application making the request

Returns:

  • (String)


19
20
21
# File 'lib/akismet/client.rb', line 19

def app_name
  @app_name
end

#app_urlString (readonly)

A URL that identifies the application making the request

Returns:

  • (String)


15
16
17
# File 'lib/akismet/client.rb', line 15

def app_url
  @app_url
end

#app_versionString (readonly)

The version of the application making the request

Returns:

  • (String)


23
24
25
# File 'lib/akismet/client.rb', line 23

def app_version
  @app_version
end

Class Method Details

.open(api_key, app_url, options = {}) {|client| ... } ⇒ Object

Initializes a client, opens it, yields it to the given block, and closes it when the block returns. Allows you to perform several operations over a single TCP connection.

Parameters:

  • api_key (String)

    The API key obtained at akismet.com

  • app_url (String)

    The URL of the home page of the application making the request

  • options (Hash) (defaults to: {})

    a customizable set of options

Options Hash (options):

  • :app_name (String)

    The name of the application making the request, e.g. “jonahb.com”. Forms part of the User-Agent header submitted to Akismet.

  • :app_version (String)

    The version of the application making the request, e.g. “1.0”. Forms part of the User-Agent header submitted to Akismet. Ignored if :app_name is not provided.

Yield Parameters:

Returns:

  • (Object)

    The return value of the block

See Also:



59
60
61
62
63
# File 'lib/akismet/client.rb', line 59

def self.open(api_key, app_url, options = {})
  raise "Block required" unless block_given?
  client = new(api_key, app_url)
  client.open { yield client }
end

Instance Method Details

#check(user_ip, user_agent, params = {}) ⇒ (Boolean, Boolean) Also known as: comment_check

Checks whether a comment is spam and whether it is “blatant.”

Parameters:

  • user_ip (String)

    The comment author’s IP address

  • user_agent (String)

    The comment author’s user-agent

  • params (Hash{Symbol => Object}) (defaults to: {})

    Optional parameters. To maximize accuracy, pass as many as possible.

Options Hash (params):

  • :referrer (String)

    The value of the HTTP_REFERER header. Note that the parameter is spelled with two consecutive ‘r’s.

  • :post_url (String)

    The URL of the post, article, etc. on which the comment was made

  • :post_modified_at (DateTime)

    The date and time the post was last modified

  • :type (String)

    Suggested values include ‘comment’, ‘trackback’, and ‘pingback’

  • :text (String)

    The text of the comment

  • :created_at (DateTime)

    The date and time the comment was created

  • :author (String)

    The comment author’s name

  • :author_email (String)

    The comment author’s email address

  • :author_url (String)

    The comment author’s personal URL

  • :languages (Array<String>)

    The ISO 639-1 codes of the languages in use on the site where the comment appears

  • :test (Boolean)

    When set to true, Akismet does not use the comment to train the filter

  • :env (Hash{Symbol, String => Object})

    Environment variables such as HTTP headers related to the comment submission

Returns:

  • ((Boolean, Boolean))

    An array containing two booleans. The first indicates whether the comment is spam. The second indicates whether it is “blatant,” i.e. whether it can be deleted without review.

Raises:

  • (Akismet::Error)

    The Akismet service returned an error

  • (ArgumentError)

    An environment variable conflicts with a built-in parameter

  • (ArgumentError)

    Invalid param



191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
# File 'lib/akismet/client.rb', line 191

def check(user_ip, user_agent, params = {})
  response = invoke_comment_method('comment-check',
    user_ip,
    user_agent,
    params)

  unless %w{ true false }.include?(response.body)
    raise_with_response response
  end

  [
    response.body == 'true',
    response['X-akismet-pro-tip'] == 'discard'
  ]
end

#closeself

Closes the Client.

Returns:

  • (self)

See Also:



111
112
113
114
115
# File 'lib/akismet/client.rb', line 111

def close
  @http_session.finish if open?
  @http_session = nil
  self
end

#ham(user_ip, user_agent, params = {}) ⇒ void Also known as: submit_ham

This method returns an undefined value.

Submits a comment that has been identified as not-spam (ham).

Parameters:

  • user_ip (String)

    The comment author’s IP address

  • user_agent (String)

    The comment author’s user-agent

  • params (Hash{Symbol => Object}) (defaults to: {})

    Optional parameters. To maximize accuracy, pass as many as possible.

Options Hash (params):

  • :referrer (String)

    The value of the HTTP_REFERER header. Note that the parameter is spelled with two consecutive ‘r’s.

  • :post_url (String)

    The URL of the post, article, etc. on which the comment was made

  • :post_modified_at (DateTime)

    The date and time the post was last modified

  • :type (String)

    Suggested values include ‘comment’, ‘trackback’, and ‘pingback’

  • :text (String)

    The text of the comment

  • :created_at (DateTime)

    The date and time the comment was created

  • :author (String)

    The comment author’s name

  • :author_email (String)

    The comment author’s email address

  • :author_url (String)

    The comment author’s personal URL

  • :languages (Array<String>)

    The ISO 639-1 codes of the languages in use on the site where the comment appears

  • :test (Boolean)

    When set to true, Akismet does not use the comment to train the filter

  • :env (Hash{Symbol, String => Object})

    Environment variables such as HTTP headers related to the comment submission

Raises:

  • (Akismet::Error)

    The Akismet service returned an error

  • (ArgumentError)

    An environment variable conflicts with a built-in parameter

  • (ArgumentError)

    Invalid param



222
223
224
225
226
227
228
229
230
231
# File 'lib/akismet/client.rb', line 222

def ham(user_ip, user_agent, params = {})
  response = invoke_comment_method('submit-ham',
    user_ip,
    user_agent,
    params)

  unless response.body == 'Thanks for making the web a better place.'
    raise_with_response response
  end
end

#open { ... } ⇒ Object #openself

Opens the client, creating a new TCP connection.

If a block is given, yields to the block, closes the client when the block returns, and returns the return value of the block. If a block is not given, returns self and leaves the client open, relying on the caller to close the client with #close.

Note that opening and closing the client is only required if you want to make several calls over one TCP connection. Otherwise, you can simply call #spam?, #check, #ham, or #spam, which call #open for you if necessary.

Due to a peculiarity of the Akismet API, #verify_key always creates its own connection.

Overloads:

  • #open { ... } ⇒ Object

    Opens the client, yields to the block, and closes the client when the block returns.

    Yields:

    • A block to be called when the client is open

    Returns:

    • (Object)

      The return value of the block

    Raises:

    • (StandardError)

      The client is already open

  • #openself

    Returns:

    • (self)

    Raises:

    • (StandardError)

      The client is already open



94
95
96
97
98
99
100
101
102
103
104
105
# File 'lib/akismet/client.rb', line 94

def open
  raise "Already open" if open?

  @http_session = Net::HTTP.new( "#{ api_key }.rest.akismet.com", 80 )

  begin
    @http_session.start
    block_given? ? yield : self
  ensure
    close if block_given?
  end
end

#open?Boolean

Whether the Client is open.

Returns:

  • (Boolean)


120
121
122
# File 'lib/akismet/client.rb', line 120

def open?
  @http_session && @http_session.started?
end

#spam(user_ip, user_agent, params = {}) ⇒ void Also known as: submit_spam

This method returns an undefined value.

Submits a comment that has been identified as spam.

Parameters:

  • user_ip (String)

    The comment author’s IP address

  • user_agent (String)

    The comment author’s user-agent

  • params (Hash{Symbol => Object}) (defaults to: {})

    Optional parameters. To maximize accuracy, pass as many as possible.

Options Hash (params):

  • :referrer (String)

    The value of the HTTP_REFERER header. Note that the parameter is spelled with two consecutive ‘r’s.

  • :post_url (String)

    The URL of the post, article, etc. on which the comment was made

  • :post_modified_at (DateTime)

    The date and time the post was last modified

  • :type (String)

    Suggested values include ‘comment’, ‘trackback’, and ‘pingback’

  • :text (String)

    The text of the comment

  • :created_at (DateTime)

    The date and time the comment was created

  • :author (String)

    The comment author’s name

  • :author_email (String)

    The comment author’s email address

  • :author_url (String)

    The comment author’s personal URL

  • :languages (Array<String>)

    The ISO 639-1 codes of the languages in use on the site where the comment appears

  • :test (Boolean)

    When set to true, Akismet does not use the comment to train the filter

  • :env (Hash{Symbol, String => Object})

    Environment variables such as HTTP headers related to the comment submission

Raises:

  • (Akismet::Error)

    The Akismet service returned an error

  • (ArgumentError)

    An environment variable conflicts with a built-in parameter

  • (ArgumentError)

    Invalid param



238
239
240
241
242
243
244
245
246
247
# File 'lib/akismet/client.rb', line 238

def spam(user_ip, user_agent, params = {})
  response = invoke_comment_method('submit-spam',
    user_ip,
    user_agent,
    params)

  unless response.body == 'Thanks for making the web a better place.'
    raise_with_response response
  end
end

#spam?(user_ip, user_agent, params = {}) ⇒ Boolean

Checks whether a comment is spam.

Parameters:

  • user_ip (String)

    The comment author’s IP address

  • user_agent (String)

    The comment author’s user-agent

  • params (Hash{Symbol => Object}) (defaults to: {})

    Optional parameters. To maximize accuracy, pass as many as possible.

Options Hash (params):

  • :referrer (String)

    The value of the HTTP_REFERER header. Note that the parameter is spelled with two consecutive ‘r’s.

  • :post_url (String)

    The URL of the post, article, etc. on which the comment was made

  • :post_modified_at (DateTime)

    The date and time the post was last modified

  • :type (String)

    Suggested values include ‘comment’, ‘trackback’, and ‘pingback’

  • :text (String)

    The text of the comment

  • :created_at (DateTime)

    The date and time the comment was created

  • :author (String)

    The comment author’s name

  • :author_email (String)

    The comment author’s email address

  • :author_url (String)

    The comment author’s personal URL

  • :languages (Array<String>)

    The ISO 639-1 codes of the languages in use on the site where the comment appears

  • :test (Boolean)

    When set to true, Akismet does not use the comment to train the filter

  • :env (Hash{Symbol, String => Object})

    Environment variables such as HTTP headers related to the comment submission

Returns:

  • (Boolean)

Raises:

  • (Akismet::Error)

    The Akismet service returned an error

  • (ArgumentError)

    An environment variable conflicts with a built-in parameter

  • (ArgumentError)

    Invalid param



212
213
214
# File 'lib/akismet/client.rb', line 212

def spam?(user_ip, user_agent, params = {})
  check(user_ip, user_agent, params)[0]
end

#verify_keyBoolean

Checks the validity of the API key.

Returns:

  • (Boolean)


129
130
131
132
133
134
135
136
137
138
139
# File 'lib/akismet/client.rb', line 129

def verify_key
  response = Net::HTTP.start('rest.akismet.com', 80) do |session|
    invoke session, 'verify-key', blog: app_url, key: api_key
  end

  unless %w{ valid invalid }.include?(response.body)
    raise_with_response response
  end

  response.body == 'valid'
end