Merge branch 'master' of https://github.com/slunak/pushover-php

Example/GlancesExample.php

@@ -0,0 +1,63 @@
+<?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\Glances\Glance;
+use Serhiy\Pushover\Api\Glances\GlanceDataFields;
+use Serhiy\Pushover\Application;
+use Serhiy\Pushover\Client\Response\GlancesResponse;
+use Serhiy\Pushover\Recipient;
+
+/**
+ * @author Serhiy Lunak
+ */
+class GlancesExample
+{
+    public function glancesExample()
+    {
+        // 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");
+
+        // create glance data fields
+        $glanceDataFields = new GlanceDataFields();
+        $glanceDataFields
+            ->setTitle("Title")
+            ->setText("Text")
+            ->setSubtext("Subtext")
+            ->setCount(1)
+            ->setPercent(99)
+        ;
+
+        // instantiate glance
+        $glance = new Glance($application, $glanceDataFields);
+
+        // set recipient
+        $glance->setRecipient($recipient);
+
+        // push it
+        /** @var GlancesResponse $response */
+        $response = $glance->push();
+
+        // or loop over recipients
+        $recipients = array(); // array of Recipient objects
+        foreach ($recipients as $recipient) {
+            $glance->setRecipient($recipient);
+            $response = $glance->push();
+        }
+
+        // work with response
+        if ($response->isSuccessful()) {
+            // ...
+        }
+    }
+}

README.md

@@ -28,6 +28,12 @@ Light, simple and fast, yet comprehensive wrapper for the [Pushover](https://pus
   - Add / Remove users
   - Enable / Disable users
   - Rename the group
+- Glances API ([Example](Example/GlancesExample.php))
+  - Title
+  - Text
+  - Subtext
+  - Count
+  - Percent
 
 *Note: Project is in constant development; update to newer versions with caution.*
 

src/Api/Glances/Glance.php

@@ -0,0 +1,148 @@
+<?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\Glances;
+
+use Serhiy\Pushover\Application;
+use Serhiy\Pushover\Client\Curl\Curl;
+use Serhiy\Pushover\Client\GlancesClient;
+use Serhiy\Pushover\Client\Request\Request;
+use Serhiy\Pushover\Client\Response\GlancesResponse;
+use Serhiy\Pushover\Recipient;
+
+/**
+ * Pushover Glances API (Beta).
+ * With Pushover's Glances API, you can push small bits of data directly to a constantly-updated screen,
+ * referred to as a widget, such as a complication on your smart watch or a widget on your phone's lock screen.
+ * Glances API is used for sending short pieces of text or numerical data, such as "Garage door open" in response to an alarm system,
+ * or just "30" representing the number of items sold in your store today.
+ * These pieces of data should be low-priority since they often cannot get updated in real-time or very frequently,
+ * and they must be concise because they are often viewed on small screens such as a watch face.
+ *
+ * @author Serhiy Lunak
+ */
+class Glance
+{
+    /**
+     * @var Application Pushover application.
+     */
+    private $application;
+
+    /**
+     * @var Recipient Pushover user.
+     */
+    private $recipient;
+
+    /**
+     * @var GlanceDataFields Glance Data Fields.
+     */
+    private $glanceDataFields;
+
+    public function __construct(Application $application, GlanceDataFields $glanceDataFields)
+    {
+        $this->application = $application;
+        $this->glanceDataFields = $glanceDataFields;
+    }
+
+    /**
+     * @return Application
+     */
+    public function getApplication(): Application
+    {
+        return $this->application;
+    }
+
+    /**
+     * @param Application $application
+     */
+    public function setApplication(Application $application): void
+    {
+        $this->application = $application;
+    }
+
+    /**
+     * @return Recipient
+     */
+    public function getRecipient(): Recipient
+    {
+        return $this->recipient;
+    }
+
+    /**
+     * @param Recipient $recipient
+     */
+    public function setRecipient(Recipient $recipient): void
+    {
+        $this->recipient = $recipient;
+    }
+
+    /**
+     * @return GlanceDataFields
+     */
+    public function getGlanceDataFields(): GlanceDataFields
+    {
+        return $this->glanceDataFields;
+    }
+
+    /**
+     * @param GlanceDataFields $glanceDataFields
+     */
+    public function setGlanceDataFields(GlanceDataFields $glanceDataFields): void
+    {
+        $this->glanceDataFields = $glanceDataFields;
+    }
+
+    /**
+     * @return bool
+     */
+    public function hasAtLeastOneField(): bool
+    {
+        if (null === $this->getGlanceDataFields()->getTitle() &&
+            null === $this->getGlanceDataFields()->getSubtext() &&
+            null === $this->getGlanceDataFields()->getCount() &&
+            null === $this->getGlanceDataFields()->getPercent()
+        ) {
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * @return bool
+     */
+    public function hasRecipient(): bool
+    {
+        if (null === $this->recipient) {
+            return false;
+        }
+
+        return true;
+    }
+
+    /**
+     * Push glance.
+     *
+     * @return GlancesResponse
+     */
+    public function push()
+    {
+        $client = new GlancesClient();
+        $request = new Request($client->buildApiUrl(), Request::POST, $client->buildCurlPostFields($this));
+
+        $curlResponse = Curl::do($request);
+
+        $response = new GlancesResponse($curlResponse);
+        $response->setRequest($request);
+
+        return $response;
+    }
+}

src/Api/Glances/GlanceDataFields.php

@@ -0,0 +1,166 @@
+<?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\Glances;
+
+use Serhiy\Pushover\Exception\InvalidArgumentException;
+
+/**
+ * Glance Data Fields.
+ * Currently the following fields are available for updating. Each field is shown differently on different screens,
+ * so you may need to experiment with them to find out which field works for you given your screen and type of data.
+ * For example, each watch face on the Apple Watch uses a different sized complication,
+ * with different size specifications and types of data. Some are text strings, some are just numbers.
+ *
+ * @author Serhiy Lunak
+ */
+class GlanceDataFields
+{
+    /**
+     * @var string|null (100 characters) - a description of the data being shown, such as "Widgets Sold".
+     */
+    private $title;
+
+    /**
+     * @var string|null (100 characters) - the main line of data, used on most screens.
+     */
+    private $text;
+
+    /**
+     * @var string|null (100 characters) - a second line of data.
+     */
+    private $subtext;
+
+    /**
+     * @var int|null (integer, may be negative) - shown on smaller screens; useful for simple counts.
+     */
+    private $count;
+
+    /**
+     * @var int|null (integer 0 through 100, inclusive) - shown on some screens as a progress bar/circle.
+     */
+    private $percent;
+
+    public function __construct()
+    {
+    }
+
+    /**
+     * @return string|null
+     */
+    public function getTitle(): ?string
+    {
+        return $this->title;
+    }
+
+    /**
+     * @param string|null $title
+     * @return GlanceDataFields
+     */
+    public function setTitle(?string $title): GlanceDataFields
+    {
+        if (strlen($title) > 100) {
+            throw new InvalidArgumentException(sprintf("Title can be no more than 100 characters long. %s characters long title provided.", strlen($title)));
+        }
+
+        $this->title = $title;
+
+        return $this;
+    }
+
+    /**
+     * @return string|null
+     */
+    public function getText(): ?string
+    {
+        return $this->text;
+    }
+
+    /**
+     * @param string|null $text
+     * @return GlanceDataFields
+     */
+    public function setText(?string $text): GlanceDataFields
+    {
+        if (strlen($text) > 100) {
+            throw new InvalidArgumentException(sprintf("Text can be no more than 100 characters long. %s characters long text provided.", strlen($text)));
+        }
+
+        $this->text = $text;
+
+        return $this;
+    }
+
+    /**
+     * @return string|null
+     */
+    public function getSubtext(): ?string
+    {
+        return $this->subtext;
+    }
+
+    /**
+     * @param string|null $subtext
+     * @return GlanceDataFields
+     */
+    public function setSubtext(?string $subtext): GlanceDataFields
+    {
+        if (strlen($subtext) > 100) {
+            throw new InvalidArgumentException(sprintf("Subtext can be no more than 100 characters long. %s characters long subtext provided.", strlen($subtext)));
+        }
+
+        $this->subtext = $subtext;
+
+        return $this;
+    }
+
+    /**
+     * @return int|null
+     */
+    public function getCount(): ?int
+    {
+        return $this->count;
+    }
+
+    /**
+     * @param int|null $count
+     * @return GlanceDataFields
+     */
+    public function setCount(?int $count): GlanceDataFields
+    {
+        $this->count = $count;
+
+        return $this;
+    }
+
+    /**
+     * @return int|null
+     */
+    public function getPercent(): ?int
+    {
+        return $this->percent;
+    }
+
+    /**
+     * @param int|null $percent
+     * @return GlanceDataFields
+     */
+    public function setPercent(?int $percent): GlanceDataFields
+    {
+        if (! ($percent >= 0 && $percent <= 100)) {
+            throw new InvalidArgumentException(sprintf("Percent should be an integer 0 through 100, inclusive. %s provided.", $percent));
+        }
+
+        $this->percent = $percent;
+
+        return $this;
+    }
+}