PHP wrapper for https://www.stopforumspam.com/usage web service API as a standalone library.
Installation
Clone this repository
git clone git@github.com:psilocyberunner/stop-forum-spam.git
Or require package via composer
composer require psilocyberunner/stop-forum-spam
First of all - bootstrap the application (see public/bootstrap.php for details)
<?php
require_once '../vendor/autoload.php';
# Add exception handler, Whoops is a good choice for your experiments
$whoops = new \Whoops\Run;
$whoops->prependHandler(new \Whoops\Handler\PrettyPageHandler);
$whoops->register();
<?php
use StopForumSpam\SearchByEmail;
require_once 'bootstrap.php';
# --- Search by email address
$client = new SearchByEmail('shamrykenkokatya@gmail.com');
$client->asJSON();
$client->withConfidence(); # If you need confidence score
/** @var Psr\Http\Message\ResponseInterface $result */
$result = $client->search();
return $result->getBody()->getContents();
Example response
{
"success": 1,
"email": {
"lastseen": "2019-03-24 14:19:15",
"frequency": 5027,
"appears": 1,
"confidence": 97.01
}
}
This search is almost equal to email search except that it uses wildcard list of hostile domains. No additional options are available as just a list of domains is used: https://www.stopforumspam.com/downloads/toxic_domains_whole.txt
<?php
use StopForumSpam\SearchByDomain;
require_once 'bootstrap.php';
# --- Search by domain
$client = new SearchByDomain('kinogomyhit.ru');
$result = $client->search();
return $result->getBody()->getContents();
Example response
{
"success": 1,
"domain": {
"appears": 1
}
}
For not found domains you'll get
{
"success": 1,
"domain": {
"appears": 0
}
}
Email hash is plain md5 checksum for email address
<?php
use StopForumSpam\SearchByEmailHash;
require_once 'bootstrap.php';
# --- Search by email hash (hash is md5 checksum for desired email)
$client = new SearchByEmailHash(md5('shamrykenkokatya@gmail.com'));
$client->withConfidence(); # If you need confidence score
$result = $client->search();
return $result->getBody()->getContents();
Example response
{
"success": 1,
"emailhash": {
"lastseen": "2019-03-24 14:19:15",
"frequency": 5027,
"appears": 1,
"confidence": 97.01
}
}
<?php
use StopForumSpam\SearchByIp;
require_once 'bootstrap.php';
# --- Search by ip address
$client = new SearchByIp('77.111.247.62');
$client->asJSON();
$client->withConfidence(); # If you need confidence score
$result = $client->search();
return $result->getBody()->getContents();
Example response
{
"success": 1,
"ip": {
"lastseen": "2018-10-02 11:48:41",
"frequency": 8,
"appears": 1,
"confidence": 0.46,
"delegated": "fr",
"country": "fr",
"asn": 205016
}
}
<?php
use StopForumSpam\SearchByUsername;
require_once 'bootstrap.php';
# --- Search by user name
$client = new SearchByUsername('Nicole');
$client->asJSON();
$client->withConfidence(); # If you need confidence score
$result = $client->search();
return $result->getBody()->getContents();
Example response
{
"success": 1,
"username": {
"lastseen": "2019-03-04 02:07:58",
"frequency": 12,
"appears": 1,
"confidence": 3.01
}
}
<?php
use StopForumSpam\SearchMultiple;
require_once 'bootstrap.php';
# --- Search multiple targets at once
$client = new SearchMultiple([
'email' => 'test@test.tld',
'ip' => '77.111.247.62',
'username' => 'c0dex',
]);
$client->withConfidence(); # If you need confidence score
$result = $client->search();
return $result->getBody()->getContents();
Example response
{
"success": 1,
"username": {
"frequency": 0,
"appears": 0
},
"email": {
"frequency": 0,
"appears": 0
},
"ip": {
"lastseen": "2018-10-02 11:48:41",
"frequency": 8,
"appears": 1,
"confidence": 0.46,
"delegated": "fr",
"country": "fr",
"asn": 205016
}
}
If you want to search for several IPs, usernames or emails at once - you can use SearchByBulk class. Up to 15 queries of any field combination can be made by constructing the fields as an array, as below.
<?php
use StopForumSpam\SearchByBulk;
require_once 'bootstrap.php';
# --- Search multiple targets at once
$client = new SearchByBulk([
'ip' => [
'127.0.0.1',
'77.111.247.62',
],
'username' => [
'Nicole',
'some-random-username-for-test',
],
'email' => [
'shamrykenkokatya@gmail.com',
'some-email@test.tld',
],
]);
$client->withConfidence(); # If you need confidence score
$result = $client->search();
return $result->getBody()->getContents();
Example response
{
"success": 1,
"ip": [
{
"value": "127.0.0.1",
"frequency": 0,
"appears": 0,
"country": "us",
"asn": 14618
},
{
"value": "77.111.247.62",
"lastseen": "2018-10-02 11:48:41",
"frequency": 8,
"appears": 1,
"confidence": 0.34,
"delegated": "fr",
"country": "us",
"asn": 14618
}
],
"username": [
{
"value": "Nicole",
"lastseen": "2019-06-22 01:20:24",
"frequency": 14,
"appears": 1,
"confidence": 11.82
},
{
"value": "some-random-username-for-test",
"frequency": 0,
"appears": 0
}
],
"email": [
{
"value": "shamrykenkokatya@gmail.com",
"lastseen": "2019-06-26 07:25:30",
"frequency": 5112,
"appears": 1,
"confidence": 98.92
},
{
"value": "some-email@test.tld",
"frequency": 0,
"appears": 0
}
]
}
You'll need your personal API token to use this feature. Register at https://www.stopforumspam.com/ and get one.
<?php
use StopForumSpam\SearchMultiple;
require_once 'bootstrap.php';
# --- Report spam data
$client = new SubmitSpamReport();
$client->setApiToken('token');
$client->setIpAddress('178.159.37.84'); # already listed as spam source
$client->setEmail('test@test.com');
$client->setEvidence('evidence');
$client->setUsername('tester');
$result = $client->submit();
return $result->getStatusCode();
For submit spam requests only response codes are indicators of success/failure. No JSON in returned.
After submit request you can see all of your spammers data in special section of https://www.stopforumspam.com/ web site called https://www.stopforumspam.com/myspammers.
SFS operate a list of email domains, usernames and IP addresses which are considered hostile. You may wish to ignore these lists, in this case you need to add the following URL parameters
To ignore the email/domain list checks
$client->withNoBadEmail();
To ignore the username (partial string) list checks
$client->withNoBadUsername();
To ignore the IP lists (which includes some of the Internets most hostile spam friendly networks)
$client->withNoBadIp();
Or to ignore all wildcard checks
$client->withNoBadAll();
The API provides several geographically diverse locations.
api.stopforumspam.org should be used as this will direct your query to the closest regional server in order to provide the quickest response. Should you wish to restrict traffic to a specific region, such as for compliance with company or country privacy regulations, then you can force a connection to a specific region.
<?php
$client = new SearchByEmail('test@email.com');
$client->useEuropeRegion(); # If you want to use Europe region servers
<?php
$client = new SearchByIp('127.0.0.1');
$client->useUSRegion(); # If you want to use US region servers
Logic available in IP search only. Known Tor exit nodes will be included in all serialised replies. If you wish to ignore the listing for any known Tor exit node, then include the
<?php
$client->withNoTorExit();
call in the request. Any IP address listed that is known as a Tor exit node will return a frequency of 0.
{
"success":1,
"ip":{
"torexit":1,
"frequency":0,
"appears":0
}
}
Some administrators may wish to block a known Tor exit node regardless of it's listing. A result for an IP that is recorded as a Tor exit node will return a frequency of 255 regardless of being listed or not. Use as:
<?php
$client->withBadTorExit();
{
"success":1,
"ip":{
"torexit":1,
"lastseen":"2016-06-22 17:36:47",
"frequency":255,
"appears":1
}
}
Method call withConfidence() will include in response additional info about confidence score
$client->withConfidence();
Method call withUnixTimestamp() will return data/time results as UNIXTIME format, that being seconds since Unix epoch
$client->withUnixTimestamp();
Method call withExpire(10) provides the ability to have API results filtered if the lastseen date is older than the age (in days).
$client->withExpire(10);
Method call asJSONP('function name') provide ajax/jquery support with JSONP, which allows for a callback function to be specified around a json result.
$client->asJSONP('test');
Response example
test({
"success":1,
"email":{
"lastseen":"2019-03-24 14:19:15",
"frequency":5027,
"appears":1,
"confidence":97.01
}
})