Skip to content
Permalink
Browse files

Updated the documentation

  • Loading branch information
cedx committed Dec 11, 2020
1 parent bcbf605 commit 60dde73b38b7d8ea7986d46247329660654909c8
Showing with 73 additions and 200 deletions.
  1. +15 −44 src/Author.php
  2. +8 −27 src/Blog.php
  3. +3 −3 src/CheckResult.php
  4. +13 −37 src/Client.php
  5. +2 −10 src/ClientException.php
  6. +18 −52 src/Comment.php
  7. +7 −7 src/CommentType.php
  8. +2 −8 src/RequestEvent.php
  9. +2 −9 src/ResponseEvent.php
  10. +3 −3 test/ClientTest.php
@@ -7,39 +7,31 @@
/** Represents the author of a comment. */
class Author implements \JsonSerializable {

/** @var string The author's mail address. */
/** The author's mail address. */
private string $email = "";

/** @var string The author's IP address. */
/** The author's IP address. */
private string $ipAddress;

/** @var string The author's name. */
/** The author's name. */
private string $name = "";

/** @var string The author's role. */
/** The author's role. */
private string $role = "";

/** @var UriInterface|null The URL of the author's website. */
/** The URL of the author's website. */
private ?UriInterface $url = null;

/** @var string The author's user agent, that is the string identifying the Web browser used to submit comments. */
/** The author's user agent, that is the string identifying the Web browser used to submit comments. */
private string $userAgent;

/**
* Creates a new author.
* @param string|null $ipAddress The author's IP address. Defaults to `$_SERVER["REMOTE_ADDR"]`.
* @param string|null $userAgent The author's user agent. Defaults to `$_SERVER["HTTP_USER_AGENT"]`.
*/
/** Creates a new author. */
function __construct(?string $ipAddress = null, ?string $userAgent = null) {
$this->ipAddress = $ipAddress ?? ($_SERVER["REMOTE_ADDR"] ?? "");
$this->userAgent = $userAgent ?? ($_SERVER["HTTP_USER_AGENT"] ?? "");
}

/**
* Creates a new author from the specified JSON object.
* @param object $map A JSON object representing an author.
* @return self The instance corresponding to the specified JSON object.
*/
/** Creates a new author from the specified JSON object. */
static function fromJson(object $map): self {
$author = new self(
isset($map->user_ip) && is_string($map->user_ip) ? $map->user_ip : "",
@@ -53,58 +45,37 @@ static function fromJson(object $map): self {
->setUrl(isset($map->comment_author_url) && is_string($map->comment_author_url) ? new Uri($map->comment_author_url) : null);
}

/**
* Gets the author's mail address.
* @return string The author's mail address.
*/
/** Gets the author's mail address. */
function getEmail(): string {
return $this->email;
}

/**
* Gets the author's IP address.
* @return string The author's IP address.
*/
/** Gets the author's IP address. */
function getIPAddress(): string {
return $this->ipAddress;
}

/**
* Gets the author's name.
* @return string The author's name.
*/
/** Gets the author's name. */
function getName(): string {
return $this->name;
}

/**
* Gets the author's role.
* @return string The author's role.
*/
/** Gets the author's role. */
function getRole(): string {
return $this->role;
}

/**
* Gets the URL of the author's website.
* @return UriInterface|null The URL of the author's website.
*/
/** Gets the URL of the author's website. */
function getUrl(): ?UriInterface {
return $this->url;
}

/**
* Gets the author's user agent, that is the string identifying the Web browser used to submit comments.
* @return string The author's user agent.
*/
/** Gets the author's user agent, that is the string identifying the Web browser used to submit comments. */
function getUserAgent(): string {
return $this->userAgent;
}

/**
* Converts this object to a map in JSON format.
* @return \stdClass The map in JSON format corresponding to this object.
*/
/** Converts this object to a map in JSON format. */
function jsonSerialize(): \stdClass {
$map = new \stdClass;
$map->user_agent = $this->getUserAgent();
@@ -7,59 +7,40 @@
/** Represents the front page or home URL transmitted when making requests. */
class Blog implements \JsonSerializable {

/** @var string The character encoding for the values included in comments. */
/** The character encoding for the values included in comments. */
private string $charset = "";

/** @var \ArrayObject<int, string> The languages in use on the blog or site, in ISO 639-1 format. */
/** The languages in use on the blog or site, in ISO 639-1 format. */
private \ArrayObject $languages;

/**
* Creates a new blog.
* @param UriInterface|null $url The blog or site URL.
*/
/** Creates a new blog. */
function __construct(private ?UriInterface $url) {
$this->languages = new \ArrayObject;
}

/**
* Creates a new blog from the specified JSON object.
* @param object $map A JSON object representing a blog.
* @return self The instance corresponding to the specified JSON object.
*/
/** Creates a new blog from the specified JSON object. */
static function fromJson(object $map): self {
return (new self(isset($map->blog) && is_string($map->blog) ? new Uri($map->blog) : null))
->setCharset(isset($map->blog_charset) && is_string($map->blog_charset) ? $map->blog_charset : "")
->setLanguages(isset($map->blog_lang) && is_string($map->blog_lang) ? array_map("trim", explode(",", $map->blog_lang)) : []);
}

/**
* Gets the character encoding for the values included in comments.
* @return string The character encoding for the values included in comments.
*/
/** Gets the character encoding for the values included in comments. */
function getCharset(): string {
return $this->charset;
}

/**
* Gets the languages in use on the blog or site, in ISO 639-1 format.
* @return \ArrayObject<int, string> The languages in use on the blog or site.
*/
/** Gets the languages in use on the blog or site, in ISO 639-1 format. */
function getLanguages(): \ArrayObject {
return $this->languages;
}

/**
* Gets the blog or site URL.
* @return UriInterface|null The blog or site URL.
*/
/** Gets the blog or site URL. */
function getUrl(): ?UriInterface {
return $this->url;
}

/**
* Converts this object to a map in JSON format.
* @return \stdClass The map in JSON format corresponding to this object.
*/
/** Converts this object to a map in JSON format. */
function jsonSerialize(): \stdClass {
$map = new \stdClass;
$map->blog = (string) $this->getUrl();
@@ -4,12 +4,12 @@
/** Specifies the result of a comment check. */
abstract class CheckResult {

/** @var string The comment is not a spam (i.e. a ham). */
/** The comment is not a spam (i.e. a ham). */
const isHam = "isHam";

/** @var string The comment is a pervasive spam (i.e. it can be safely discarded). */
/** The comment is a pervasive spam (i.e. it can be safely discarded). */
const isPervasiveSpam = "isPervasiveSpam";

/** @var string The comment is a spam. */
/** The comment is a spam. */
const isSpam = "isSpam";
}
@@ -8,29 +8,25 @@
/** Submits comments to the [Akismet](https://akismet.com) service. */
class Client extends EventDispatcher {

/** @var string An event that is triggered when a request is made to the remote service. */
/** An event that is triggered when a request is made to the remote service. */
const eventRequest = RequestEvent::class;

/** @var string An event that is triggered when a response is received from the remote service. */
/** An event that is triggered when a response is received from the remote service. */
const eventResponse = ResponseEvent::class;

/** @var UriInterface The URL of the API end point. */
/** The URL of the API end point. */
private UriInterface $endPoint;

/** @var Psr18Client The HTTP client. */
/** The HTTP client. */
private Psr18Client $http;

/** @var bool Value indicating whether the client operates in test mode. */
/** Value indicating whether the client operates in test mode. */
private bool $isTest = false;

/** @var string The user agent string to use when making requests. */
/** The user agent string to use when making requests. */
private string $userAgent;

/**
* Creates a new client.
* @param string $apiKey The Akismet API key.
* @param Blog $blog The front page or home URL of the instance making requests.
*/
/** Creates a new client. */
function __construct(private string $apiKey, private Blog $blog) {
parent::__construct();

@@ -44,11 +40,7 @@ function __construct(private string $apiKey, private Blog $blog) {
$this->userAgent = "PHP/$phpVersion | Akismet/$pkgVersion";
}

/**
* Checks the specified comment against the service database, and returns a value indicating whether it is spam.
* @param Comment $comment The comment to be checked.
* @return string A `CheckResult` value indicating whether the specified comment is spam.
*/
/** Checks the specified comment against the service database, and returns a value indicating whether it is spam. */
function checkComment(Comment $comment): string {
$apiUrl = $this->getEndPoint();
$endPoint = $this->http->createUri("{$apiUrl->getScheme()}://{$this->getApiKey()}.{$apiUrl->getAuthority()}{$apiUrl->getPath()}comment-check");
@@ -58,43 +50,30 @@ function checkComment(Comment $comment): string {
return $response->getHeaderLine("X-akismet-pro-tip") == "discard" ? CheckResult::isPervasiveSpam : CheckResult::isSpam;
}

/**
* Gets the Akismet API key.
* @return string The Akismet API key.
*/
/** Gets the Akismet API key. */
function getApiKey(): string {
return $this->apiKey;
}

/**
* Gets the front page or home URL of the instance making requests.
* @return Blog The front page or home URL.
*/
/** Gets the front page or home URL of the instance making requests. */
function getBlog(): Blog {
return $this->blog;
}

/**
* Gets the URL of the API end point.
* @return UriInterface The URL of the API end point.
*/
/** Gets the URL of the API end point. */
function getEndPoint(): UriInterface {
return $this->endPoint;
}

/**
* Gets the user agent string to use when making requests.
* If possible, the user agent string should always have the following format: `Application Name/Version | Plugin Name/Version`.
* @return string The user agent string to use when making requests.
*/
function getUserAgent(): string {
return $this->userAgent;
}

/**
* Gets a value indicating whether the client operates in test mode.
* @return bool `true` if the client operates in test mode, otherwise `false`.
*/
/** Gets a value indicating whether the client operates in test mode. */
function isTest(): bool {
return $this->isTest;
}
@@ -162,10 +141,7 @@ function verifyKey(): bool {
}

/**
* Queries the service by posting the specified fields to a given end point, and returns the response as a string.
* @param UriInterface $endPoint The URL of the end point to query.
* @param array<string, string> $fields The fields describing the query body.
* @return ResponseInterface The server response.
* Queries the service by posting the specified fields to a given end point, and returns the server response.
* @throws ClientException An error occurred while querying the end point.
*/
private function fetch(UriInterface $endPoint, array $fields = []): ResponseInterface {
@@ -6,20 +6,12 @@
/** An exception caused by an error in a `Client` request. */
class ClientException extends \RuntimeException {

/**
* Creates a new client exception.
* @param string $message A message describing the error.
* @param UriInterface|null $uri The URL of the HTTP request or response that failed.
* @param \Throwable|null $previous The previous exception used for the exception chaining.
*/
/** Creates a new client exception. */
function __construct(string $message, private ?UriInterface $uri = null, ?\Throwable $previous = null) {
parent::__construct($message, 0, $previous);
}

/**
* Gets the URL of the HTTP request or response that failed.
* @return UriInterface|null The URL of the HTTP request or response that failed.
*/
/** Gets the URL of the HTTP request or response that failed. */
function getUri(): ?UriInterface {
return $this->uri;
}

0 comments on commit 60dde73

Please sign in to comment.