Skip to content
Permalink
Browse files

Ported the documentation to Docsify

  • Loading branch information
cedx committed Nov 26, 2020
1 parent db5c1f3 commit 2f568401d7652b5d8251c29a35881136e9faaad1
@@ -3,7 +3,7 @@
!/.vscode/

/build/
/doc/api/
/docs/api/
/var/
/vendor/
/www/
@@ -1,5 +1,5 @@
# MIT License
Copyright © 2016 - 2020 Cédric Belin
Copyright © 2016 - 2021 Cédric Belin

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
BIN -13.3 KB doc/img/akismet.png
Binary file not shown.
BIN -7.23 KB doc/img/favicon.ico
Binary file not shown.
Empty file.
@@ -1,26 +1,22 @@
# Akismet <small>for PHP</small>
![Runtime](https://badgen.net/packagist/php/cedx/akismet) ![Release](https://badgen.net/packagist/v/cedx/akismet) ![License](https://badgen.net/packagist/license/cedx/akismet) ![Downloads](https://badgen.net/packagist/dt/cedx/akismet) ![Coverage](https://badgen.net/coveralls/c/github/cedx/akismet.php) ![Build](https://badgen.net/github/checks/cedx/akismet.php/main)

![Akismet](img/akismet.png)

## Stop spam
Used by millions of websites, [Akismet](https://akismet.com) filters out hundreds of millions of spam comments from the Web every day.
Add Akismet to your [PHP](https://www.php.net) applications so you don't have to worry about spam again.
> Used by millions of websites, [Akismet](https://akismet.com) filters out hundreds of millions of spam comments from the Web every day.
> Add Akismet to your [PHP](https://www.php.net) applications so you don't have to worry about spam again.
## Quick start

### Get a developer key
You first need to [sign up for a developer key](https://akismet.com/signup/?plan=developer).
This will give you access to the API and will allow Akismet to monitor its results to make sure things are running as smoothly as possible.

!!! warning
All Akismet endpoints require an API key. If you are not already registered,
[join the developer program](https://akismet.com/signup/?plan=developer).
!> All Akismet endpoints require an API key. If you are not already registered, [join the developer program](https://akismet.com/signup/?plan=developer).

### Get the library
Install the latest version of **Akismet for PHP** with [Composer](https://getcomposer.org):

``` shell
```shell
composer require cedx/akismet
```

@@ -0,0 +1,13 @@
- [Installation](installation.md)
- [Usage](usage.md)
- Features
- [Key verification](features/key_verification.md)
- [Comment check](features/comment_check.md)
- [Submit spam](features/submit_spam.md)
- [Submit ham](features/submit_ham.md)
- Further reading
- [Events](advanced/events.md)
- [Testing](advanced/testing.md)
- About
- [License](about/license.md)
- [See also](about/see_also.md)
@@ -1,5 +1,5 @@
# MIT License
Copyright &copy; 2016 - 2020 Cédric Belin
Copyright &copy; 2016 - 2021 Cédric Belin

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
File renamed without changes.
@@ -1,16 +1,10 @@
---
path: src/branch/main
source: src/Client.php
---

# Events
The `Akismet\Client` class, used to query the Akismet service, is an [EventDispatcher](https://symfony.com/doc/current/components/event_dispatcher.html) that triggers some events during its life cycle.

### The `Client::eventRequest` event
### The "request" event
Emitted every time a request is made to the remote service:

``` php
<?php
```php
use Akismet\{Blog, Client, RequestEvent};
use Nyholm\Psr7\Uri;
@@ -22,11 +16,10 @@ function main(): void {
}
```

### The `Client::eventResponse` event
### The "response" event
Emitted every time a response is received from the remote service:

``` php
<?php
```php
use Akismet\{Blog, Client, ResponseEvent};
use Nyholm\Psr7\Uri;
@@ -2,12 +2,11 @@
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->getName()` set to `"viagra-test-123"` or `Author->getEmail()` set to <code>&quot;akismet-guaranteed-spam&commat;example.com&quot;</code>. Populate all other required fields with typical values.
Make a [comment check](features/comment_check.md) API call with the `Author->getName()` set to `"viagra-test-123"` or `Author->getEmail()` set to <code>&quot;akismet-guaranteed-spam&commat;example.com&quot;</code>. Populate all other required fields with typical values.

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
```php
use Akismet\{Author, Blog, Client, Comment};
use Nyholm\Psr7\Uri;
@@ -24,12 +23,11 @@ function main(): void {
```

## Simulate a negative (not spam) result
Make a [comment check](../features/comment_check.md) API call with the `Author->getRole()` set to `"administrator"` and all other required fields populated with typical values.
Make a [comment check](features/comment_check.md) API call with the `Author->getRole()` set to `"administrator"` and all other required fields populated with typical values.

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

``` php
<?php
```php
use Akismet\{Author, Blog, Client, Comment};
use Nyholm\Psr7\Uri;
@@ -50,8 +48,7 @@ Enable the `Client->isTest()` option in your tests.

That will tell Akismet not to change its behaviour based on those API calls: they will have no training effect. That means your tests will be somewhat repeatable, in the sense that one test won't influence subsequent calls.

``` php
<?php
```php
use Akismet\{Author, Blog, Client, Comment};
use Nyholm\Psr7\Uri;
BIN +14.7 KB docs/favicon.ico
Binary file not shown.
BIN +15.1 KB docs/favicon.png
Binary file not shown.
@@ -1,18 +1,13 @@
---
path: src/branch/main
source: src/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.

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

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.
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.

@@ -26,16 +21,14 @@ The `Comment` providing the user message to be checked.
## Return value
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.
?> 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.

## Example

``` php
<?php
```php
use Akismet\{Author, Blog, CheckResult, Client, ClientException, Comment, CommentType};
use Nyholm\Psr7\Uri;
@@ -1,13 +1,8 @@
---
path: src/branch/main
source: src/Client.php
---

# Key verification
Key verification authenticates your key before calling the [comment check](comment_check.md),
[submit spam](submit_spam.md) or [submit ham](submit_ham.md) methods.
Key verification authenticates your key before calling the [comment check](features/comment_check.md),
[submit spam](features/submit_spam.md) or [submit ham](features/submit_ham.md) methods.

```
```php
Client->verifyKey(): bool
```

@@ -27,8 +22,7 @@ The exception `getMessage()` usually includes some debug information, provided b

## Example

``` php
<?php
```php
use Akismet\{Blog, Client, ClientException};
use Nyholm\Psr7\Uri;
@@ -1,13 +1,13 @@
# Submit ham
This call is intended for the submission of false positives - items that were incorrectly classified as spam by Akismet.
It takes identical arguments as [comment check](comment_check.md) and [submit spam](submit_spam.md).
It takes identical arguments as [comment check](features/comment_check.md) and [submit spam](features/submit_spam.md).

```
```php
Client->submitHam(Comment $comment): void
```

Remember that, as explained in the [submit spam](submit_spam.md) documentation, you should ensure
that any values you're passing here match up with the original and corresponding [comment check](comment_check.md) call.
Remember that, as explained in the [submit spam](features/submit_spam.md) documentation, you should ensure
that any values you're passing here match up with the original and corresponding [comment check](features/comment_check.md) call.

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

@@ -16,8 +16,7 @@ See the [Akismet API documentation](https://akismet.com/development/api/#submit-
### Comment **$comment**
The user `Comment` to be submitted, incorrectly classified as spam.

!!! tip
Ideally, it should be the same object as the one passed to the original [comment check](comment_check.md) API call.
?> Ideally, it should be the same object as the one passed to the original [comment check](features/comment_check.md) API call.

## Return value
None.
@@ -27,8 +26,7 @@ The exception `getMessage()` usually includes some debug information, provided b

## Example

``` php
<?php
```php
use Akismet\{Author, Blog, Client, ClientException, Comment};
use Nyholm\Psr7\Uri;
@@ -1,14 +1,14 @@
# Submit spam
This call is for submitting comments that weren't marked as spam but should have been.

```
```php
Client->submitSpam(Comment $comment): void
```

It is very important that the values you submit with this call match those of your [comment check](comment_check.md) calls as closely as possible.
It is very important that the values you submit with this call match those of your [comment check](features/comment_check.md) calls as closely as possible.
In order to learn from its mistakes, Akismet needs to match your missed spam and false positive reports
to the original [comment check](comment_check.md) API calls made when the content was first posted. While it is normal for less information
to be available for [submit spam](submit_spam.md) and [submit ham](submit_ham.md) calls (most comment systems and forums will not store all metadata),
to the original [comment check](features/comment_check.md) API calls made when the content was first posted. While it is normal for less information
to be available for [submit spam](features/submit_spam.md) and [submit ham](features/submit_ham.md) calls (most comment systems and forums will not store all metadata),
you should ensure that the values that you do send match those of the original content.

See the [Akismet API documentation](https://akismet.com/development/api/#submit-spam) for more information.
@@ -18,8 +18,7 @@ See the [Akismet API documentation](https://akismet.com/development/api/#submit-
### Comment **$comment**
The user `Comment` to be submitted, incorrectly classified as ham.

!!! tip
Ideally, it should be the same object as the one passed to the original [comment check](comment_check.md) API call.
?> Ideally, it should be the same object as the one passed to the original [comment check](features/comment_check.md) API call.

## Return value
None.
@@ -29,8 +28,7 @@ The exception `getMessage()` usually includes some debug information, provided b

## Example

``` php
<?php
```php
use Akismet\{Author, Blog, Client, ClientException, Comment};
use Nyholm\Psr7\Uri;
@@ -0,0 +1,40 @@
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>Akismet for PHP</title>

<meta name="application-name" content="Akismet for PHP">
<meta name="author" content="Cédric Belin - cedric@belin.io">
<meta name="description" content="Prevent comment spam using the Akismet service, in PHP.">
<meta name="format-detection" content="telephone=no">
<meta name="referrer" content="same-origin">
<meta name="theme-color" content="#617cbe">
<meta name="viewport" content="initial-scale=1, maximum-scale=1, shrink-to-fit=no, user-scalable=no, width=device-width">

<link rel="icon" href="favicon.ico" sizes="16x16 32x32 48x48" type="image/x-icon">
<link rel="icon" href="favicon.png" sizes="192x192" type="image/png">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify/lib/themes/vue.css">

<script>
window.$docsify = {
alias: {"/.*/_sidebar.md": "/_sidebar.md"},
auto2top: true,
ga: "UA-38560031-41",
loadSidebar: true,
name: "Akismet for PHP",
repo: "https://git.belin.io/cedx/akismet.php",
themeColor: "#617cbe"
};
</script>

<script defer src="https://cdn.jsdelivr.net/npm/docsify"></script>
<script defer src="https://cdn.jsdelivr.net/npm/docsify/lib/plugins/ga.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/prismjs/components/prism-bash.min.js"></script>
<script defer src="https://cdn.jsdelivr.net/npm/prismjs/components/prism-php.min.js"></script>
</head>

<body>
<div id="app"></div>
</body>
</html>
@@ -6,32 +6,29 @@ and [Composer](https://getcomposer.org), the PHP package manager, up and running

You can verify if you're already good to go with the following commands:

``` shell
```shell
php --version
# PHP 7.4.12 (cli) (built: Oct 27 2020 17:18:33) ( NTS Visual C++ 2017 x64 )
# PHP 8.0.0 (cli) (built: Nov 24 2020 22:02:58) ( NTS Visual C++ 2019 x64 )
composer --version
# Composer version 2.0.7 2020-11-13 17:31:06
```

!!! info
If you plan to play with the package sources, you will also need the latest versions of
[PowerShell](https://docs.microsoft.com/en-us/powershell) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material).
?> If you plan to play with the package sources, you will also need the latest versions of [PowerShell](https://docs.microsoft.com/en-us/powershell).

## Installing with Composer package manager

### 1. Install it
From a command prompt, run:

``` shell
```shell
composer require cedx/akismet
```

### 2. Import it
Now in your [PHP](https://www.php.net) code, you can use:

``` php
<?php
```php
use Akismet\{
Author,
Blog,
@@ -12,4 +12,4 @@ See the detailed documentation of each feature for more information about their
## Further reading
Before integrating this library into your application, you should [test your API calls](advanced/testing.md) to ensure a proper usage.

If you want to be notified when a call is made to the Akismet service, or to log the service responses for further processing, you should take a look at the [events triggered by the `Client` class](advanced/events.md).
If you want to be notified when a call is made to the Akismet service, or to log the service responses for further processing, you should take a look at the [events triggered by the client](advanced/events.md).

0 comments on commit 2f56840

Please sign in to comment.