1 <?php
2 namespace Slack\Message;
3
4 /**
5 * A builder object for creating new message attachment objects.
6 */
7 class AttachmentBuilder
8 {
9 // An array of data to pass to the built attachment.
10 private $data = [];
11
12 // Keep track of which text values should be parsed as Markdown.
13 private $markdownInText = false;
14 private $markdownInPretext = false;
15 private $markdownInFields = false;
16
17 /**
18 * Sets the attachment title with an optional link.
19 *
20 * @param string $title The attachment title text.
21 * @param string $link An optional URL the title should link to.
22 * @return $this
23 */
24 public function setTitle($title, $link = null)
25 {
26 $this->data['title'] = $title;
27 if ($link) {
28 $this->data['title_link'] = $link;
29 }
30
31 return $this;
32 }
33
34 /**
35 * Sets the main text of the attachment.
36 *
37 * @param string $text The attachment text.
38 * @param bool $markdown Enables or disables Markdown parsing in the text.
39 * @return $this
40 */
41 public function setText($text, $markdown = false)
42 {
43 $this->data['text'] = $text;
44 $this->markdownInText = $markdown;
45
46 return $this;
47 }
48
49 /**
50 * Sets a plain-text summary of the attachment.
51 *
52 * This text will be used in clients that don't show formatted text.
53 *
54 * @param string $fallbackText The fallback text.
55 * @return $this
56 */
57 public function setFallbackText($fallbackText)
58 {
59 $this->data['fallback'] = $fallbackText;
60
61 return $this;
62 }
63
64 /**
65 * Sets the attachment pretext.
66 *
67 * This is optional text that appears above the message attachment block.
68 *
69 * @param string $pretext The attachment pretext.
70 * @param bool $markdown Enables or disables Markdown parsing in the pretext.
71 * @return $this
72 */
73 public function setPretext($pretext, $markdown = false)
74 {
75 $this->data['pretext'] = $pretext;
76 $this->markdownInPretext = $markdown;
77
78 return $this;
79 }
80
81 /**
82 * Sets the attachment border color.
83 *
84 * @param string $color The attachment border color. Can be "good", "warning", "danger", or a hex color code.
85 * @return $this
86 */
87 public function setColor($color)
88 {
89 $this->data['color'] = $color;
90
91 return $this;
92 }
93
94 /**
95 * Sets the message author.
96 *
97 * @param string $name The author name.
98 * @param string $link An optional URL that the author text should link to.
99 * @param string $icon An optional URL to an image to show to the left of the author name.
100 * @return $this
101 */
102 public function setAuthor($name, $link = null, $icon = null)
103 {
104 $this->data['author_name'] = $name;
105 if ($link) {
106 $this->data['author_link'] = $link;
107 }
108 if ($icon) {
109 $this->data['author_icon'] = $icon;
110 }
111
112 return $this;
113 }
114
115 /**
116 * Sets the URL to an image to display in the attachment body.
117 *
118 * @param string $url The image URL.
119 * @return $this
120 */
121 public function setImageUrl($url)
122 {
123 $this->data['image_url'] = $url;
124
125 return $this;
126 }
127
128 /**
129 * Sets the URL to an image to display as a thumbnail.
130 *
131 * @param string $url The thumbnail URL.
132 * @return $this
133 */
134 public function setThumbUrl($url)
135 {
136 $this->data['thumb_url'] = $url;
137
138 return $this;
139 }
140
141 /**
142 * Sets an attachment footer shown beneath the attachment body.
143 *
144 * @param string $text Brief footer text.
145 * @param string $icon An optional URL to an image to show to the left of the footer text.
146 * @return $this
147 */
148 public function setFooter($text, $icon = null)
149 {
150 $this->data['footer'] = $text;
151 if ($icon) {
152 $this->data['footer_icon'] = $icon;
153 }
154
155 return $this;
156 }
157
158 /**
159 * Sets an additional timestamp to show in the attachment footer.
160 *
161 * @param \DateTime $time A timestamp.
162 * @return $this
163 */
164 public function setTimestamp(\DateTime $time)
165 {
166 $this->data['ts'] = $time->getTimestamp();
167
168 return $this;
169 }
170
171 /**
172 * Adds a field to the attachment.
173 *
174 * @param AttachmentField $field The field to add.
175 * @return $this
176 */
177 public function addField(AttachmentField $field)
178 {
179 if (!isset($this->data['fields'])) {
180 $this->data['fields'] = [];
181 }
182
183 $this->data['fields'][] = $field->data;
184
185 return $this;
186 }
187
188 /**
189 * Enables or disables Markdown parsing in fields.
190 *
191 * @param bool $enable Whether Markdown should be enabled.
192 * @return $this
193 */
194 public function enableMarkdownFields($enable = true)
195 {
196 $this->markdownInFields = !!$enable;
197
198 return $this;
199 }
200
201 /**
202 * Creates and returns a new attachment object specified by the builder.
203 *
204 * @return Attachment A new attachment object.
205 */
206 public function create()
207 {
208 $this->data['mrkdwn_in'] = [];
209
210 if ($this->markdownInText) {
211 $this->data['mrkdwn_in'][] = 'text';
212 }
213
214 if ($this->markdownInPretext) {
215 $this->data['mrkdwn_in'][] = 'pretext';
216 }
217
218 if ($this->markdownInFields) {
219 $this->data['mrkdwn_in'][] = 'fields';
220 }
221
222 return Attachment::fromData($this->data);
223 }
224 }
225