Add Groups API

Example/GroupsExample.php

@@ -0,0 +1,68 @@
+<?php
+
+/*
+ * This file is part of the Pushover package.
+ *
+ * (c) Serhiy Lunak <https://github.com/slunak>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Serhiy\Pushover\Example;
+
+use Serhiy\Pushover\Api\Groups\Group;
+use Serhiy\Pushover\Application;
+use Serhiy\Pushover\Client\Response\AddUserToGroupResponse;
+use Serhiy\Pushover\Client\Response\DisableUserInGroupResponse;
+use Serhiy\Pushover\Client\Response\EnableUserInGroupResponse;
+use Serhiy\Pushover\Client\Response\RemoveUserFromGroupResponse;
+use Serhiy\Pushover\Client\Response\RenameGroupResponse;
+use Serhiy\Pushover\Client\Response\RetrieveGroupResponse;
+use Serhiy\Pushover\Recipient;
+
+/**
+ * Work with groups example.
+ *
+ * @author Serhiy Lunak
+ */
+class GroupsExample
+{
+    public function groupsExample()
+    {
+        // instantiate pushover application and recipient to verify (can be injected into service using Dependency Injection)
+        $application = new Application("replace_with_pushover_application_api_token");
+        $recipient = new Recipient("replace_with_pushover_user_key");
+
+        // instantiate pushover group (can be injected into service using Dependency Injection)
+        $group = new Group("replace_with_pushover_group_key", $application);
+
+        // Retrieve information about the group from the API and populate the object with it.
+        /** @var RetrieveGroupResponse $retrieveGroupResponse */
+        $retrieveGroupResponse = $group->retrieveGroupInformation();
+
+        // rename the group
+        /** @var RenameGroupResponse $renameGroupResponse */
+        $renameGroupResponse = $group->rename("Rename Group Test");
+
+        // add user to the group
+        $recipient->setMemo("This is a test memo"); // optional
+        $recipient->addDevice("android"); // optional
+        /** @var AddUserToGroupResponse $addUserToGroupResponse */
+        $addUserToGroupResponse = $group->addUser($recipient);
+
+        // remove user from the group
+        /** @var RemoveUserFromGroupResponse $removeUserFromGroupResponse */
+        $removeUserFromGroupResponse = $group->removeUser($recipient);
+
+        // enable user
+        /** @var EnableUserInGroupResponse $EnableUserInGroupResponse */
+        $EnableUserInGroupResponse = $group->enableUser($recipient);
+
+        // disable user
+        /** @var DisableUserInGroupResponse $disableUserInGroupResponse */
+        $disableUserInGroupResponse = $group->disableUser($recipient);
+
+        // work with responses as usually
+    }
+}

README.md

@@ -23,6 +23,11 @@ Light, simple and fast wrapper for the Pushover API.
 - Receipt API ([Example](Example/ReceiptExample.php))
   - Query emergency priority receipt
   - Cancel emergency priority retry
+- Groups API ([Example](Example/GroupsExample.php))
+  - Retrieve information about the group
+  - Add / Remove users
+  - Enable / Disable users
+  - Rename the group
 
 *Note: Project is in constant development; update to newer versions with caution.*
 

src/Api/Groups/Group.php

@@ -0,0 +1,213 @@
+<?php
+
+/*
+ * This file is part of the Pushover package.
+ *
+ * (c) Serhiy Lunak <https://github.com/slunak>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Serhiy\Pushover\Api\Groups;
+
+use Serhiy\Pushover\Application;
+use Serhiy\Pushover\Client\Curl\Curl;
+use Serhiy\Pushover\Client\GroupsClient;
+use Serhiy\Pushover\Client\Request\Request;
+use Serhiy\Pushover\Client\Response\AddUserToGroupResponse;
+use Serhiy\Pushover\Client\Response\DisableUserInGroupResponse;
+use Serhiy\Pushover\Client\Response\EnableUserInGroupResponse;
+use Serhiy\Pushover\Client\Response\RemoveUserFromGroupResponse;
+use Serhiy\Pushover\Client\Response\RenameGroupResponse;
+use Serhiy\Pushover\Client\Response\RetrieveGroupResponse;
+use Serhiy\Pushover\Exception\InvalidArgumentException;
+use Serhiy\Pushover\Recipient;
+
+/**
+ * @author Serhiy Lunak
+ */
+class Group
+{
+    /**
+     * @var string Group key.
+     */
+    private $key;
+
+    /**
+     * @var Application Pushover application this group belongs to.
+     */
+    private $application;
+
+    /**
+     * @var string Name of the group.
+     */
+    private $name;
+
+    /**
+     * @var Recipient[] Group users.
+     */
+    private $users;
+
+    public function __construct(string $key, Application $application)
+    {
+        if (1 != preg_match("/^[a-zA-Z0-9]{30}$/", $key)) {
+            throw new InvalidArgumentException(sprintf('Group identifiers are 30 characters long, case-sensitive, and may contain the character set [A-Za-z0-9]. "%s" given."', $key));
+        }
+
+        $this->key = $key;
+        $this->application = $application;
+    }
+
+    /**
+     * @return string
+     */
+    public function getKey(): string
+    {
+        return $this->key;
+    }
+
+    /**
+     * @return Application
+     */
+    public function getApplication(): Application
+    {
+        return $this->application;
+    }
+
+    /**
+     * @return Recipient[]
+     */
+    public function getUsers(): array
+    {
+        return $this->users;
+    }
+
+    /**
+     * @return string
+     */
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    /**
+     * Retrieves information about the group from the API and populates the object with it.
+     *
+     * @return RetrieveGroupResponse
+     */
+    public function retrieveGroupInformation(): RetrieveGroupResponse
+    {
+        $client = new GroupsClient($this, GroupsClient::ACTION_RETRIEVE_GROUP);
+        $request = new Request($client->buildApiUrl(), Request::GET);
+
+        $curlResponse = Curl::do($request);
+
+        $response = new RetrieveGroupResponse($curlResponse);
+        $response->setRequest($request);
+
+        if ($response->isSuccessful()) {
+            $this->name = $response->getName();
+            $this->users = $response->getUsers();
+        }
+
+        return $response;
+    }
+
+    /**
+     * Adds an existing Pushover user to your Delivery Group.
+     *
+     * @param Recipient $recipient
+     * @return AddUserToGroupResponse
+     */
+    public function addUser(Recipient $recipient)
+    {
+        $client = new GroupsClient($this, GroupsClient::ACTION_ADD_USER);
+        $request = new Request($client->buildApiUrl(), Request::POST, $client->buildCurlPostFields($recipient));
+
+        $curlResponse = Curl::do($request);
+
+        $response = new AddUserToGroupResponse($curlResponse);
+        $response->setRequest($request);
+
+        return $response;
+    }
+
+    /**
+     * Removes user to from Delivery Group.
+     *
+     * @param Recipient $recipient
+     * @return RemoveUserFromGroupResponse
+     */
+    public function removeUser(Recipient $recipient): RemoveUserFromGroupResponse
+    {
+        $client = new GroupsClient($this, GroupsClient::ACTION_REMOVE_USER);
+        $request = new Request($client->buildApiUrl(), Request::POST, $client->buildCurlPostFields($recipient));
+
+        $curlResponse = Curl::do($request);
+
+        $response = new RemoveUserFromGroupResponse($curlResponse);
+        $response->setRequest($request);
+
+        return $response;
+    }
+
+    /**
+     * Enables user in Delivery Group.
+     *
+     * @param Recipient $recipient
+     * @return EnableUserInGroupResponse
+     */
+    public function enableUser(Recipient $recipient): EnableUserInGroupResponse
+    {
+        $client = new GroupsClient($this, GroupsClient::ACTION_ENABLE_USER);
+        $request = new Request($client->buildApiUrl(), Request::POST, $client->buildCurlPostFields($recipient));
+
+        $curlResponse = Curl::do($request);
+
+        $response = new EnableUserInGroupResponse($curlResponse);
+        $response->setRequest($request);
+
+        return $response;
+    }
+
+    /**
+     * Disables user in Delivery Group.
+     *
+     * @param Recipient $recipient
+     * @return DisableUserInGroupResponse
+     */
+    public function disableUser(Recipient $recipient): DisableUserInGroupResponse
+    {
+        $client = new GroupsClient($this, GroupsClient::ACTION_DISABLE_USER);
+        $request = new Request($client->buildApiUrl(), Request::POST, $client->buildCurlPostFields($recipient));
+
+        $curlResponse = Curl::do($request);
+
+        $response = new DisableUserInGroupResponse($curlResponse);
+        $response->setRequest($request);
+
+        return $response;
+    }
+
+    /**
+     * Renames the group. Reflected in the API and in the group editor on our website.
+     *
+     * @param string $name
+     * @return RenameGroupResponse
+     */
+    public function rename(string $name): RenameGroupResponse
+    {
+        $this->name = $name;
+
+        $client = new GroupsClient($this, GroupsClient::ACTION_RENAME_GROUP);
+        $request = new Request($client->buildApiUrl(), Request::POST, $client->buildCurlPostFields());
+
+        $curlResponse = Curl::do($request);
+
+        $response = new RenameGroupResponse($curlResponse);
+        $response->setRequest($request);
+
+        return $response;
+    }
+}