{"id":20121800,"url":"https://github.com/parseword/sfsquery","last_synced_at":"2025-10-09T09:14:30.264Z","repository":{"id":57036006,"uuid":"130731322","full_name":"parseword/sfsquery","owner":"parseword","description":"A PHP class to query the StopForumSpam API","archived":false,"fork":false,"pushed_at":"2019-03-01T04:51:49.000Z","size":18,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-10-09T09:14:13.471Z","etag":null,"topics":["dnsbl-checker","php","spam-detection","spam-protection","stopforumspam","stopforumspam-api"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/parseword.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-23T17:19:54.000Z","updated_at":"2021-03-25T16:54:22.000Z","dependencies_parsed_at":"2022-08-24T06:40:30.965Z","dependency_job_id":null,"html_url":"https://github.com/parseword/sfsquery","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/parseword/sfsquery","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseword%2Fsfsquery","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseword%2Fsfsquery/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseword%2Fsfsquery/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseword%2Fsfsquery/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/parseword","download_url":"https://codeload.github.com/parseword/sfsquery/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/parseword%2Fsfsquery/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279001114,"owners_count":26083021,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-09T02:00:07.460Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["dnsbl-checker","php","spam-detection","spam-protection","stopforumspam","stopforumspam-api"],"created_at":"2024-11-13T19:32:44.835Z","updated_at":"2025-10-09T09:14:30.248Z","avatar_url":"https://github.com/parseword.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SFSQuery\n\nA PHP class to query the [StopForumSpam](https://stopforumspam.com/) web API or DNSBL for \ninformation about an IP address. Help protect your comments, contact form, or \nother user-generated content from spammers by checking the StopForumSpam \ndatabase in real time. \n\n### Usage\n\nSFSQuery is platform-agnostic and can be used with any project. \nSimply `require()` the class file or place it where your autoloader can find it; \nComposer installation is supported.\n\nThe simplest implementation uses an anonymous object to check whether or not an \nIP meets one of several criteria. For example, you might want to reject an action \nif the user's IP has been reported to StopForumSpam in the past 7 days:\n\n```php\n\u003c?php\nuse parseword\\SFSQuery\\SFSQuery;\n\nif ((new SFSQuery($_SERVER['REMOTE_ADDR']))-\u003ewasReportedInPastDays(7)) {\n    header('HTTP/1.1 403 Forbidden');\n    echo \"Sorry, you don't have access to this resource.\";\n    exit;\n}\nelse {\n    //Process the action\n}\n```\n\nBecause IP addresses frequently change hands, it's wise to use a more refined \nassessment based upon multiple factors. Just instantiate an `SFSQuery` object \nand call as many getter methods as you need. Let's check to see if an IP has \nbeen reported in the past 30 days, *and* has a spammer confidence level greater \nthan 25%:\n\n```php\n\u003c?php\nuse parseword\\SFSQuery\\SFSQuery;\n\n$sfs = new SFSQuery($_SERVER['REMOTE_ADDR']);\nif ($sfs-\u003ewasReportedInPastDays(30) \u0026\u0026 $sfs-\u003egetConfidence() \u003e 25) {\n    //Reject the comment\n    exit;\n}\nelse {\n    //Process the comment\n}\n```\nPerhaps you want to reject IPs from Russia which have been reported to \nStopForumSpam more than 10 times:\n\n```php\n\u003c?php\nuse parseword\\SFSQuery\\SFSQuery;\n\n$sfs = new SFSQuery($_SERVER['REMOTE_ADDR']);\nif ($sfs-\u003egetFrequency() \u003e 10 \u0026\u0026 $sfs-\u003egetCountry() == 'ru') {\n    //Reject the comment\n    exit;\n}\nelse {\n    //Process the comment\n}\n```\nYou should experiment to figure out what combination of factors is too \"spammy\" \nfor your liking. You don't want to let a bunch of spammers through, but you \ndon't want to cause a lot of false positives either. Consider a multi-tiered \napproach where high confidence spammers get rejected outright, lower scoring \nIPs have their comments flagged for moderator review, and totally clean IPs are \nfree to submit content at will.\n\n### Method overview\n\nStopForumSpam offers several data points about each IP in their \ndatabase. `SFSQuery` exposes them all through getter methods.\n\n* `getAppears()` - Whether or not the IP is in the StopForumSpam database. \n\n* `getAsn()` - The Autonomous System Number that announces the IP. (Web API only.)\n\n* `getConfidence()` - A score from 0 to 100 calculated by StopForumSpam \nindicating how likely the IP is to be a spammer. \n\n* `getCountry()` - Two-letter country code corresponding to the IP; reasonably \naccurate. (Web API only.)\n\n* `getFrequency()` - How many times the IP has been reported to StopForumSpam. \n\n* `getLastSeen()` - The epoch timestamp of the most recent time an IP was reported. \n\nThere are several additional methods available:\n\n* `setQueryMethod()` - Switch from querying the web API (default) to the DNSBL, \nsee next section.\n\n* `getApiResponse()` - If an API query succeeds, this will contain the JSON reply \nfrom StopForumSpam.\n\n* `getDnsResponse()` - If a DNSBL query succeeds, this will contain the A record \nor `NXDOMAIN`.\n\n* `getError()` - If an error was encountered, this should tell you why.\n\n* `wasReportedInLastDays()` - Whether or not the IP has been reported in the \nspecified number of days.\n\n* `wasReportedSince()` - Whether or not the IP has been reported since the \ngiven epoch timestamp.\n\nTo prevent unnecessary network traffic, the StopForumSpam API is queried only \nonce during the lifetime of an `SFSQuery` object, with all of the data points \nbeing set during the initial query. If you use an object caching layer on top \nof PHP, consider forcing `SFSQuery` objects to be garbage collected at some \nregular interval so you aren't seeing stale results. \n\n### Querying the StopForumSpam DNSBL\n\n`SFSQuery` version 1.1.0 introduces the ability to query StopForumSpam's DNSBL \nservice instead of the web API. Using the DNSBL offers several advantages:\n\n* Requests are smaller, decreasing network traffic\n* DNS typically uses UDP, eliminating TCP setup/teardown time\n* Responses are cached by the DNS infrastructure, reducing load on StopForumSpam\n\nThe trade-off is that StopForumSpam's DNSBL doesn't provide information about \nthe target IP's ASN or country code. The `getAsn()` and `getCountry()` methods \naren't compatible with DNSBL mode and will return 0 and null, respectively.\n\nTo make `SFSQuery` use the DNSBL instead of the web API, you *must* instantiate \nan SFSQuery object and call `setQueryMethod(SFSQuery::QUERYMETHOD_DNS);`\n\n```php\n\u003c?php\nuse parseword\\SFSQuery\\SFSQuery;\n\n$sfs = new SFSQuery($_SERVER['REMOTE_ADDR']);\n$sfs-\u003esetQueryMethod(SFSQuery::QUERYMETHOD_DNS);\n\nif ($sfs-\u003ewasReportedInPastDays(7) \u0026\u0026 $sfs-\u003egetConfidence() \u003e 50) {\n    //Reject the comment\n    exit;\n}\nelse {\n    //Process the comment\n}\n```\nRemember that if you use the DNSBL service, you won't be able to test for \nthe IP's ASN or country code.\n\n### Requirements\n\n`SFSQuery` is written for PHP 7. To perform API connections, it requires \n*one* of the following to be available: `fopen()` URL wrappers, curl, or `fsockopen()`. \nTo query the DNSBL, the `gethostbyname()` function must be available.\n\n### Limitations\n\nAt present, only queries for IP addresses are supported. Web API queries can be \nmade for both IPv4 and IPv6 addresses. DNSBL queries are currently limited to IPv4 \naddresses only. The ability to query email addresses may come in a future release. \n\n### Disclaimer\n\nThe author is not affiliated with the StopForumSpam project. Any use of their \nservice must comply with their [Acceptable Use Policy](https://www.stopforumspam.com/legal).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparseword%2Fsfsquery","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fparseword%2Fsfsquery","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fparseword%2Fsfsquery/lists"}