Rich Attachments feature and AttachmentBuilder

CHANGELOG.md

@@ -2,6 +2,10 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org).
 
+## [0.3.0] - 2017-04-19
+### Added
+- Advanced message attachments can now be created using `AttachmentBuilder`.
+
 ## [0.2.5] - 2016-09-21
 ### Added
 - You can now check if a `RealTimeClient` is currently connected with a `isConnected()` method.
@@ -73,7 +77,8 @@ This project adheres to [Semantic Versioning](http://semver.org).
 - Ability to send messages to any open channel, group or DM, either with the web API or with the RTM API.
 
 
-[unreleased]: https://github.com/sagebind/slack-client/compare/v0.2.5...HEAD
+[unreleased]: https://github.com/sagebind/slack-client/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/sagebind/slack-client/compare/v0.2.5...v0.3.0
 [0.2.5]: https://github.com/sagebind/slack-client/compare/v0.2.4...v0.2.5
 [0.2.4]: https://github.com/sagebind/slack-client/compare/v0.2.3...v0.2.4
 [0.2.3]: https://github.com/sagebind/slack-client/compare/v0.2.2...v0.2.3

README.md

@@ -56,16 +56,20 @@ $client->getChannelById('C025YTX9D')->then(function (\Slack\Channel $channel) us
 Slack supports messages much more rich than plain text through attachments. The easiest way to create a custom message is with a `MessageBuilder`:
 
 ```php
-use Slack\Message\{Attachment, AttachmentField};
+use Slack\Message\{Attachment, AttachmentBuilder, AttachmentField};
 
 $message = $client->getMessageBuilder()
     ->setText('Hello, all!')
     ->setChannel($someChannelObject)
     ->addAttachment(new Attachment('My Attachment', 'attachment text'))
-    ->addAttachment(new Attachment('Build Status', 'Build failed! :/', 'build failed', 'danger')))
-    ->addAttachment(new Attachment('Some Fields', 'fields', null, '#BADA55', [
-        new AttachmentField('Title1', 'Text', false),
-        new AttachmentField('Title2', 'Some other text', true)
+    ->addAttachment(new Attachment('Build Status', 'Build failed! :/', 'build failed', 'danger'))
+    ->addAttachment(new AttachmentBuilder()
+        ->setTitle('Some Fields')
+        ->setText('fields')
+        ->setColor('#BADA55')
+        ->addField(new AttachmentField('Title1', 'Text', false))
+        ->addField(new AttachmentField('Title2', 'Some other text', true))
+        ->create()
     ]))
     ->create();
 

src/Message/Attachment.php

@@ -40,8 +40,7 @@ public function getFallbackText()
     /**
      * Gets the attachment border color.
      *
-     * @return string The attachment border color. Can be `good`, `warning`,
-     *                `danger`, or a hex color code.
+     * @return string The attachment border color. Can be "good", "warning", "danger", or a hex color code.
      */
     public function getColor()
     {
@@ -138,6 +137,42 @@ public function getThumbUrl()
         return isset($this->data['thumb_url']) ? $this->data['thumb_url'] : null;
     }
 
+    /**
+     * Gets the footer text.
+     *
+     * @return string The footer text.
+     */
+    public function getFooterText()
+    {
+        return isset($this->data['footer']) ? $this->data['footer'] : null;
+    }
+
+    /**
+     * Gets a URL to an image to show to the left of the footer text.
+     *
+     * @return string The footer icon URL.
+     */
+    public function getFooterIcon()
+    {
+        return isset($this->data['footer_icon']) ? $this->data['footer_icon'] : null;
+    }
+
+    /**
+     * Gets an extra timestamp value in the footer.
+     *
+     * @return \DateTime The time of the timestamp.
+     */
+    public function getTimestamp()
+    {
+        if (!isset($this->data['ts'])) {
+            return null;
+        }
+
+        $time = new \DateTime();
+        $time->setTimestamp($this->data['ts']);
+        return $time;
+    }
+
     /**
      * Checks if the attachment has fields.
      *

src/Message/AttachmentBuilder.php

@@ -0,0 +1,224 @@
+<?php
+namespace Slack\Message;
+
+/**
+ * A builder object for creating new message attachment objects.
+ */
+class AttachmentBuilder
+{
+    // An array of data to pass to the built attachment.
+    private $data = [];
+
+    // Keep track of which text values should be parsed as Markdown.
+    private $markdownInText = false;
+    private $markdownInPretext = false;
+    private $markdownInFields = false;
+
+    /**
+     * Sets the attachment title with an optional link.
+     *
+     * @param string $title The attachment title text.
+     * @param string $link An optional URL the title should link to.
+     * @return $this
+     */
+    public function setTitle($title, $link = null)
+    {
+        $this->data['title'] = $title;
+        if ($link) {
+            $this->data['title_link'] = $link;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Sets the main text of the attachment.
+     *
+     * @param string $text The attachment text.
+     * @param bool $markdown Enables or disables Markdown parsing in the text.
+     * @return $this
+     */
+    public function setText($text, $markdown = false)
+    {
+        $this->data['text'] = $text;
+        $this->markdownInText = $markdown;
+
+        return $this;
+    }
+
+    /**
+     * Sets a plain-text summary of the attachment.
+     *
+     * This text will be used in clients that don't show formatted text.
+     *
+     * @param string $fallbackText The fallback text.
+     * @return $this
+     */
+    public function setFallbackText($fallbackText)
+    {
+        $this->data['fallback'] = $fallbackText;
+
+        return $this;
+    }
+
+    /**
+     * Sets the attachment pretext.
+     *
+     * This is optional text that appears above the message attachment block.
+     *
+     * @param string $pretext The attachment pretext.
+     * @param bool $markdown Enables or disables Markdown parsing in the pretext.
+     * @return $this
+     */
+    public function setPretext($pretext, $markdown = false)
+    {
+        $this->data['pretext'] = $pretext;
+        $this->markdownInPretext = $markdown;
+
+        return $this;
+    }
+
+    /**
+     * Sets the attachment border color.
+     *
+     * @param string $color The attachment border color. Can be "good", "warning", "danger", or a hex color code.
+     * @return $this
+     */
+    public function setColor($color)
+    {
+        $this->data['color'] = $color;
+
+        return $this;
+    }
+
+    /**
+     * Sets the message author.
+     *
+     * @param string $name The author name.
+     * @param string $link An optional URL that the author text should link to.
+     * @param string $icon An optional URL to an image to show to the left of the author name.
+     * @return $this
+     */
+    public function setAuthor($name, $link = null, $icon = null)
+    {
+        $this->data['author_name'] = $name;
+        if ($link) {
+            $this->data['author_link'] = $link;
+        }
+        if ($icon) {
+            $this->data['author_icon'] = $icon;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Sets the URL to an image to display in the attachment body.
+     *
+     * @param string $url The image URL.
+     * @return $this
+     */
+    public function setImageUrl($url)
+    {
+        $this->data['image_url'] = $url;
+
+        return $this;
+    }
+
+    /**
+     * Sets the URL to an image to display as a thumbnail.
+     *
+     * @param string $url The thumbnail URL.
+     * @return $this
+     */
+    public function setThumbUrl($url)
+    {
+        $this->data['thumb_url'] = $url;
+
+        return $this;
+    }
+
+    /**
+     * Sets an attachment footer shown beneath the attachment body.
+     *
+     * @param string $text Brief footer text.
+     * @param string $icon An optional URL to an image to show to the left of the footer text.
+     * @return $this
+     */
+    public function setFooter($text, $icon = null)
+    {
+        $this->data['footer'] = $text;
+        if ($icon) {
+            $this->data['footer_icon'] = $icon;
+        }
+
+        return $this;
+    }
+
+    /**
+     * Sets an additional timestamp to show in the attachment footer.
+     *
+     * @param \DateTime $time A timestamp.
+     * @return $this
+     */
+    public function setTimestamp(\DateTime $time)
+    {
+        $this->data['ts'] = $time->getTimestamp();
+
+        return $this;
+    }
+
+    /**
+     * Adds a field to the attachment.
+     *
+     * @param AttachmentField $field The field to add.
+     * @return $this
+     */
+    public function addField(AttachmentField $field)
+    {
+        if (!isset($this->data['fields'])) {
+            $this->data['fields'] = [];
+        }
+
+        $this->data['fields'][] = $field->data;
+
+        return $this;
+    }
+
+    /**
+     * Enables or disables Markdown parsing in fields.
+     *
+     * @param bool $enable Whether Markdown should be enabled.
+     * @return $this
+     */
+    public function enableMarkdownFields($enable = true)
+    {
+        $this->markdownInFields = !!$enable;
+
+        return $this;
+    }
+
+    /**
+     * Creates and returns a new attachment object specified by the builder.
+     *
+     * @return Attachment A new attachment object.
+     */
+    public function create()
+    {
+        $this->data['mrkdwn_in'] = [];
+
+        if ($this->markdownInText) {
+            $this->data['mrkdwn_in'][] = 'text';
+        }
+
+        if ($this->markdownInPretext) {
+            $this->data['mrkdwn_in'][] = 'pretext';
+        }
+
+        if ($this->markdownInFields) {
+            $this->data['mrkdwn_in'][] = 'fields';
+        }
+
+        return Attachment::fromData($this->data);
+    }
+}

src/Message/AttachmentField.php

@@ -15,7 +15,7 @@ class AttachmentField extends DataObject
      *
      * @param string $title A text heading for the field.
      * @param string $value The text value of the field.
-     * @param bool   $short Indicates if the value can be displayed side-by-side with other values.
+     * @param bool $short Indicates if the value can be displayed side-by-side with other values.
      */
     public function __construct($title, $value, $short = true)
     {

src/Message/Message.php

@@ -18,6 +18,16 @@ public function getText()
         return $this->data['text'];
     }
 
+    /**
+     * Checks if Markdown is enabled for the message text.
+     *
+     * @return bool
+     */
+    public function isMarkdownEnabled()
+    {
+        return isset($this->data['mrkdwn']) ? $this->data['mrkdwn'] == true : true;
+    }
+
     /**
      * Checks if the message has attachments.
      *

src/Message/MessageBuilder.php

@@ -44,11 +44,13 @@ public function create()
      * Sets the message text.
      *
      * @param string $text The message body text.
+     * @param bool $markdown Enable or disable Markdown parsing of the text.
      * @return $this
      */
-    public function setText($text)
+    public function setText($text, $markdown = true)
     {
         $this->data['text'] = $text;
+        $this->data['mrkdwn'] = $markdown;
         return $this;
     }