Browse Source

Updated the documentation

pull/4/head
Cédric Belin 5 months ago
parent
commit
b9a00c800d
6 changed files with 29 additions and 37 deletions
  1. +4
    -1
      CHANGELOG.md
  2. +0
    -0
      doc/advanced/client_setup.md
  3. +0
    -1
      doc/advanced/lifecycle.md
  4. +0
    -21
      doc/advanced/structuring_api_calls.md
  5. +4
    -4
      doc/advanced/testing.md
  6. +21
    -10
      doc/features/comment_check.md

+ 4
- 1
CHANGELOG.md View File

@@ -4,8 +4,11 @@
- Breaking change: raised the required [PHP](https://www.php.net) version.
- Breaking change: using camelcase instead of all caps for constants.
- Breaking change: using PHP 7.4 features, like arrow functions and typed properties.
- Added support for the `X-akismet-pro-tip` HTTP header.
- Added a user guide based on [MkDocs](http://www.mkdocs.org).
- Added the `ClientException` class.
- Added the `CheckResult` enumeration.
- Added the `ClientException` exception class.
- Added the `Comment->recheckReason` property.
- Modified the package layout.
- Updated the package dependencies.



+ 0
- 0
doc/advanced/client_setup.md View File


+ 0
- 1
doc/advanced/lifecycle.md View File

@@ -1 +0,0 @@
# Lifecycle

+ 0
- 21
doc/advanced/structuring_api_calls.md View File

@@ -1,21 +0,0 @@
# Structuring your API calls
There are three different types of calls to Akismet:

1. [Key verification](../features/key_verification.md) will verify whether or not a valid API key is being used. This is especially useful if you will have multiple users with their own Akismet subscriptions using your application.
2. [Comment check](../features/comment_check.md) is used to ask Akismet whether or not a given post, comment, profile, etc. is spam.
3. [Submit spam](../features/submit_spam.md) and [submit ham](../features/submit_ham.md) are follow-ups to let Akismet know when it got something wrong (missed spam and false positives). These are very important, and you shouldn't develop using the Akismet API without a facility to include reporting missed spam and false positives.

## Setting up the client


## Checking comments

## Setting your user agent
If possible, your user agent string should always use the following format:

```
Application Name/Version | Plugin Name/Version
```

!!! info
The default user agent string looks like: `Yii Framework/2.0.17 | Akismet/8.0.0`

+ 4
- 4
doc/advanced/testing.md View File

@@ -1,10 +1,10 @@
# Testing
When you will integrate the library with your own application, you will of course need to test it. Often we see developers get ahead of themselves, making a few trivial API calls with minimal values and drawing the wrong conclusions about Akismet's accuracy.
When you will integrate this library with your own application, you will of course need to test it. Often we see developers get ahead of themselves, making a few trivial API calls with minimal values and drawing the wrong conclusions about Akismet's accuracy.

## Simulate a positive (spam) result
Make a [comment check](../features/comment_check.md) API call with the `Author->name` set to `"viagra-test-123"` or `Author->email` set to `"akismet-guaranteed-spam@example.com"`. Populate all other required fields with typical values.

The Akismet API will always return a `true` response to a valid request with one of those values. If you receive anything else, something is wrong in your client, data, or communications.
The Akismet API will always return a `CheckResult::isSpam` response to a valid request with one of those values. If you receive anything else, something is wrong in your client, data, or communications.

```php
<?php
@@ -26,7 +26,7 @@ print("It should be 'true': $isSpam");
## Simulate a negative (not spam) result
Make a [comment check](../features/comment_check.md) API call with the `Author->role` set to `"administrator"` and all other required fields populated with typical values.

The Akismet API will always return a `false` response. Any other response indicates a data or communication problem.
The Akismet API will always return a `CheckResult::isHam` response. Any other response indicates a data or communication problem.

```php
<?php
@@ -64,6 +64,6 @@ $client = new Client([
$author = new Author('127.0.0.1', 'Mozilla/5.0');
$comment = new Comment($author, 'A user comment');

echo 'It should not influence subsequent calls';
echo 'It should not influence subsequent calls.';
$client->checkComment($comment);
```

+ 21
- 10
doc/features/comment_check.md View File

@@ -1,22 +1,31 @@
path: blob/master
source: lib/Comment.php

# Comment check
This is the call you will make the most. It takes a number of arguments and characteristics about the submitted content and then returns a thumbs up or thumbs down. **Performance can drop dramatically if you choose to exclude data points.** The more data you send Akismet about each comment, the greater the accuracy. We recommend erring on the side of including too much data.
This is the call you will make the most. It takes a number of arguments and characteristics about the submitted content
and then returns a thumbs up or thumbs down. **Performance can drop dramatically if you choose to exclude data points.**
The more data you send Akismet about each comment, the greater the accuracy. We recommend erring on the side of including too much data.

```
Client->checkComment(Comment $comment): bool
Client->checkComment(Comment $comment): string
```

!!! tip "Testing your data"
It is important to test Akismet with a significant amount of real, live data in order to draw any conclusions on accuracy.
Akismet works by comparing content to genuine spam activity happening right now (and this is based on more than just the content itself),
so artificially generating spam comments is not a viable approach.
It is important to [test Akismet](../advanced/testing.md) with a significant amount of real, live data in order to draw any conclusions on accuracy.
Akismet works by comparing content to genuine spam activity happening **right now** (and this is based on more than just the content itself),
so artificially generating spam comments is not a viable approach.

See the [Akismet API documentation](https://akismet.com/development/api/#comment-check) for more information.

## Parameters

### $comment
### Comment **$comment**
The `Comment` providing the user message to be checked.

## Return value
A `bool` value indicating whether the given `Comment` is spam.
A `CheckResult` value indicating whether the given `Comment` is ham, spam or pervasive spam.

!!! tip
A comment classified as pervasive spam can be safely discarded.

The method throws a `ClientException` when an error occurs.
The exception `getMessage()` usually includes some debug information, provided by the `X-akismet-debug-help` HTTP header, about what exactly was invalid about the call.
@@ -39,11 +48,13 @@ try {
['content' => 'A user comment', 'date' => new \DateTimeImmutable]
);

$isSpam = $client->checkComment($comment);
echo $isSpam ? 'The comment is spam' : 'The comment is ham';
$result = $client->checkComment($comment);
echo $result == CheckResult::isHam ? 'The comment is ham.' : 'The comment is spam.';
}

catch (ClientException $e) {
echo 'An error occurred: ', $e->getMessage();
}
```

See the [API reference](https://dev.belin.io/yii2-akismet/api) of this library for detailed information about the `Author` and `Comment` classes, and their properties.

Loading…
Cancel
Save