diff --git a/CHANGELOG.md b/CHANGELOG.md index 240401c..1529cdb 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index 991c59e..f843532 100644 --- a/README.md +++ b/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(); diff --git a/src/Message/Attachment.php b/src/Message/Attachment.php index 1eb49bb..194e5b0 100644 --- a/src/Message/Attachment.php +++ b/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. * diff --git a/src/Message/AttachmentBuilder.php b/src/Message/AttachmentBuilder.php new file mode 100644 index 0000000..ad9c6d4 --- /dev/null +++ b/src/Message/AttachmentBuilder.php @@ -0,0 +1,224 @@ +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); + } +} diff --git a/src/Message/AttachmentField.php b/src/Message/AttachmentField.php index c7ff4ca..e689052 100644 --- a/src/Message/AttachmentField.php +++ b/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) { diff --git a/src/Message/Message.php b/src/Message/Message.php index a12d5fe..035b3c3 100644 --- a/src/Message/Message.php +++ b/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. * diff --git a/src/Message/MessageBuilder.php b/src/Message/MessageBuilder.php index 8ca89d5..fddea29 100644 --- a/src/Message/MessageBuilder.php +++ b/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; } diff --git a/tests/Message/AttachmentBuilderTest.php b/tests/Message/AttachmentBuilderTest.php new file mode 100644 index 0000000..a927d5c --- /dev/null +++ b/tests/Message/AttachmentBuilderTest.php @@ -0,0 +1,49 @@ +builder = new AttachmentBuilder(); + } + + public function testCreateReturnsAttachment() + { + $attachment = $this->builder->create(); + $this->assertInstanceOf(Attachment::class, $attachment); + } + + public function testSetText() + { + $attachment = $this->builder->setText('text')->create(); + $this->assertEquals('text', $attachment->getText()); + } + + public function testSetTimestamp() + { + $now = new \DateTime(); + $attachment = $this->builder->setTimestamp($now)->create(); + + $this->assertEquals($now->getTimestamp(), $attachment->getTimestamp()->getTimestamp()); + } + + public function testAddField() + { + $field = new AttachmentField('title', 'text'); + $attachment = $this->builder->addField($field)->create(); + + $this->assertTrue($attachment->hasFields()); + $this->assertCount(1, $attachment->getFields()); + $this->assertEquals($field, $attachment->getFields()[0]); + } +}