Browse Source

Updated the documentation

pull/4/head
Cédric Belin 4 months ago
parent
commit
0a9f8cd0ee
6 changed files with 10 additions and 102 deletions
  1. +2
    -1
      .gitattributes
  2. +0
    -93
      README.md
  3. +4
    -4
      doc/advanced/events.md
  4. +1
    -1
      doc/advanced/testing.md
  5. +2
    -2
      doc/index.md
  6. +1
    -1
      doc/installation.md

+ 2
- 1
.gitattributes View File

@@ -1,6 +1,7 @@
* text=auto

.* text

*.cmd text
*.http text
*.json text
*.md text


+ 0
- 93
README.md View File

@@ -12,98 +12,5 @@ Prevent comment spam using the [Akismet](https://akismet.com) connector for [Yii
- [Packagist package](https://packagist.org/packages/cedx/yii2-akismet)
- [Submit an issue](https://github.com/cedx/yii2-akismet/issues)

## Features
- [Key verification](https://akismet.com/development/api/#verify-key): checks an Akismet API key and gets a value indicating whether it is valid.
- [Comment check](https://akismet.com/development/api/#comment-check): checks a comment and gets a value indicating whether it is spam.
- [Submit spam](https://akismet.com/development/api/#submit-spam): submits a comment that was not marked as spam but should have been.
- [Submit ham](https://akismet.com/development/api/#submit-ham): submits a comment that was incorrectly marked as spam but should not have been.

## Requirements
The latest [PHP](https://www.php.net) and [Composer](https://getcomposer.org) versions to use the Akismet library.

If you plan to play with the sources, you will also need the latest [Robo](https://robo.li) and [Material for MkDocs](https://squidfunk.github.io/mkdocs-material) versions.

## Installing via [Composer](https://getcomposer.org)
From a command prompt, run:

```shell
composer require cedx/yii2-akismet
```

## Usage
In your application configuration file, you can use the following component:

```php
<?php return [
'components' => [
'akismet' => [
'class' => 'yii\akismet\Client',
'apiKey' => '123YourAPIKey',
'blog' => [
'class' => 'yii\akismet\Blog',
'url' => 'http://www.yourblog.com'
]
]
]
];
```

Once the `yii\akismet\Client` component initialized with your credentials, you can use its methods.

### Key verification

```php
<?php
use yii\akismet\{ClientException};

try {
$client = \Yii::$app->akismet;
$isValid = $client->verifyKey();
echo $isValid ? 'The API key is valid' : 'The API key is invalid';
}

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

### Comment check

```php
<?php
use yii\akismet\{Author, Comment};

try {
$comment = new Comment(
new Author('127.0.0.1', 'Mozilla/5.0'),
['content' => 'A user comment', 'date' => new \DateTimeImmutable]
);

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

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

### Submit spam / ham

```php
<?php
try {
$client->submitSpam($comment);
echo 'Spam submitted';

$client->submitHam($comment);
echo 'Ham submitted';
}

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

## License
[Akismet for Yii](https://dev.belin.io/yii2-akismet) is distributed under the MIT License.

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

@@ -1,10 +1,10 @@
path: blob/master
source: lib/http/Client.php
source: lib/Client.php

# Events
The `yii\akismet\Client`, used to query the Akismet service, class triggers some events during its life cycle.
The `yii\akismet\Client` class, used to query the Akismet service, triggers some events during its life cycle.

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

```php
@@ -17,7 +17,7 @@ $client->on(Client::eventRequest, fn(RequestEvent $event) =>
);
```

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

```php


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

@@ -46,7 +46,7 @@ print("It should be 'false': $isSpam");
## Automated testing
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.
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


+ 2
- 2
doc/index.md View File

@@ -10,12 +10,12 @@ Add Akismet to your [Yii Framework](https://www.yiiframework.com) applications s
## Quick start

### Get a developer key
You first need to [sign up for a developer key](https://akismet.com/signup/?connect=yes&plan=developer).
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/?connect=yes&plan=developer).
[join the developer program](https://akismet.com/signup/?plan=developer).

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


+ 1
- 1
doc/installation.md View File

@@ -11,7 +11,7 @@ You can verify if you're already good to go with the following commands:

```shell
php --version
# PHP 7.4.3 (cli) (built: Feb 18 2020 17:29:57) ( NTS Visual C++ 2017 x64 )
# PHP 7.4.4 (cli) (built: Mar 17 2020 13:49:13) ( NTS Visual C++ 2017 x64 )

composer --version
# Composer version 1.10.1 2020-03-13 20:34:27


Loading…
Cancel
Save