progress - 2018-03-21

README.md

@@ -5,3 +5,132 @@ ZF3 module for Slack communication
 
 [![Packagist](https://img.shields.io/packagist/v/massimo-filippi/slack-module.svg)](https://packagist.org/packages/massimo-filippi/slack-module)
 [![License](http://img.shields.io/:license-mit-blue.svg)](http://doge.mit-license.org)
+
+## Introduction
+
+There will be more info soon...
+
+## Installation
+
+### 1. Install via Composer
+
+Install the latest stable version via Composer:
+
+```
+composer require massimo-filippi/slack-module
+```
+
+Install the latest develop version via Composer:
+
+```
+composer require massimo-filippi/slack-module:dev-master
+```
+
+### 2. Enable module in your application
+
+Composer should enable `MassimoFilippi\SlackModule` in your project automatically during installation. 
+
+In case it does not, you can enable module manually by adding value `'MassimoFilippi\SlackModule'` to array in file `config/modules.config.php`. At the end, it should look like PHP array below.
+
+```php
+<?php
+
+return [
+    'Zend\Router',
+    'Zend\Validator',
+    'MassimoFilippi\SlackModule', // Add this line, ideally before Application module.
+    'Application',
+];
+```
+
+### 3. Set up your configuration
+
+You have to set settings for SlackService, otherwise you will not be able to use it. 
+
+Here is what I have in my `config/autoload/local.php` file.
+
+```php
+<?php
+
+return [
+    'massimo_filippi' => [
+        'slack_module' => [
+            'config' => [
+                'webhook_url' => 'https://hooks.slack.com/services/#########/#########/########################',
+                // Whether names like @regan should be converted into links by Slack, default: false
+                'link_names' => false,
+                // Whether Slack should unfurl links to text-based content, default: false
+                'unfurl_links' => false,
+                // Whether Slack should unfurl links to media content such as images and YouTube videos, default: true 
+                'unfurl_media' => true,
+                // Whether message text should be interpreted in Slack's Markdown-like language. For formatting options, see Slack's help article: http://goo.gl/r4fsdO, default: true
+                'allow_markdown' => true,
+                // Which attachment fields should be interpreted in Slack's Markdown-like language. By default, Slack assumes that no fields in an attachment should be formatted as Markdown. // default: []
+                'markdown_in_attachments' => [],
+
+                // Allow Markdown in just the text and title fields
+                //// 'markdown_in_attachments' => ['text', 'title']
+                // Allow Markdown in all fields
+                //// 'markdown_in_attachments' => ['pretext', 'text', 'title', 'fields', 'fallback']
+
+                'defaults' => [
+                    // default username, set to null to use the default set on the Slack webhook, default: null
+                    'username' => 'Slack module',
+                    // default channel, channel: #general, user: @john.doe, set to null to use the default set on the Slack webhook, default: null
+                    'channel' => '#general',
+                    // URL to an image or Slack emoji like :ghost: or :+1:, set null to use the default set on the Slack webhook, default: null 
+                    'icon' => null 
+                ],
+            ],
+        ],
+    ],
+];
+
+```
+
+## Usage
+
+Somewhere in business logic classes.
+
+```php
+<?php 
+
+use Maknz\Slack\Message as SlackMessage;
+use MassimoFilippi\SlackModule\Model\Attachment as SlackAttachment;
+
+/** @var SlackMessage $slackMessage */
+$slackMessage = $this->slackService->createMessage();
+$slackMessage->to('#general')
+    ->from('John Doe')
+    ->withIcon(':ghost:')
+    ->setText('This is an amazing message!');
+
+/** @var SlackAttachment $slackAttachment */
+$slackAttachment = $this->slackService->createAttachment([
+        'fallback' => 'Some fallback text',
+        'text' => 'The attachment text'
+    ]);
+$slackMessage->attach($slackAttachment);
+
+try {
+    // Injected MassimoFilippi\SlackModule\Service\SlackService.
+    $this->slackService->sendMessage($slackMessage);
+} catch (\Exception $exception) {
+    var_dump($exception->getMessage());
+}
+```
+
+## Methods
+
+* Create message:
+    * ```$this->slackService->createMessage();```
+* Create attachment:
+    * ```$this->slackService->createAttachment($arguments);```
+    * See Slack documentation: https://api.slack.com/docs/message-attachments
+* Create attachment field:
+    * ```$this->slackService->createAttachementField($arguments);```
+    * See Slack documentation: https://api.slack.com/docs/message-attachments
+
+* Create attachment action:
+    * ```$this->slackService->createAttachementAction($arguments);```
+    * See Slack documentation: https://api.slack.com/docs/message-attachments

composer.json

@@ -14,7 +14,8 @@
   "minimum-stability": "dev",
   "prefer-stable": true,
   "require": {
-    "php": "^5.6 || ^7.0"
+    "php": "^5.6 || ^7.0",
+    "maknz/slack": "^1.7"
   },
   "autoload": {
     "psr-4": {

config-dist/slack-module.local.php

@@ -3,7 +3,31 @@
 return [
     'massimo_filippi' => [
         'slack_module' => [
-            // todo
+            'webhook_url' => 'https://hooks.slack.com/services/#########/#########/########################',
+            // Whether names like @regan should be converted into links by Slack, default: false
+            'link_names' => false,
+            // Whether Slack should unfurl links to text-based content, default: false
+            'unfurl_links' => false,
+            // Whether Slack should unfurl links to media content such as images and YouTube videos, default: true
+            'unfurl_media' => true,
+            // Whether message text should be interpreted in Slack's Markdown-like language. For formatting options, see Slack's help article: http://goo.gl/r4fsdO, default: true
+            'allow_markdown' => true,
+            // Which attachment fields should be interpreted in Slack's Markdown-like language. By default, Slack assumes that no fields in an attachment should be formatted as Markdown. // default: []
+            'markdown_in_attachments' => [],
+
+            // Allow Markdown in just the text and title fields
+            //// 'markdown_in_attachments' => ['text', 'title']
+            // Allow Markdown in all fields
+            //// 'markdown_in_attachments' => ['pretext', 'text', 'title', 'fields', 'fallback']
+
+            'defaults' => [
+                // default username, set to null to use the default set on the Slack webhook, default: null
+                'username' => 'Slack module',
+                // default channel, channel: #general, user: @john.doe, set to null to use the default set on the Slack webhook, default: null
+                'channel' => '#general',
+                // URL to an image or Slack emoji like :ghost: or :+1:, set null to use the default set on the Slack webhook, default: null
+                'icon' => null
+            ],
         ],
     ],
 ];

config/module.config.php

@@ -2,4 +2,10 @@
 
 namespace MassimoFilippi\SlackModule;
 
-return [];
+return [
+    'service_manager' => [
+        'factories' => [
+            Service\SlackService::class => Service\Factory\SlackServiceFactory::class,
+        ]
+    ]
+];

src/Model/Attachment.php

@@ -0,0 +1,115 @@
+<?php
+namespace MassimoFilippi\SlackModule\Model;
+
+/**
+ * Class Attachment
+ * @package MassimoFilippi\SlackModule\Model
+ */
+class Attachment extends \Maknz\Slack\Attachment
+{
+    /**
+     * The actions of the attachment
+     *
+     * @var array
+     */
+    protected $actions = [];
+
+    /**
+     * Attachment constructor.
+     * @param array $attributes
+     */
+    public function __construct(array $attributes)
+    {
+        parent::__construct($attributes);
+
+        if(isset($attributes['actions'])) $this->setActions($attributes['actions']);
+    }
+
+    /**
+     * Get the actions for the attachment
+     *
+     * @return array
+     */
+    public function getActions()
+    {
+        return $this->actions;
+    }
+
+    /**
+     * Set the actions for the attachment
+     *
+     * @param array $actions
+     * @return $this
+     */
+    public function setActions(array $actions)
+    {
+        $this->clearActions();
+
+        foreach ($actions as $action) {
+            $this->addAction($action);
+        }
+
+        return $this;
+    }
+
+    /**
+     * Add a action to the attachment
+     *
+     * @param mixed $action
+     * @return $this
+     */
+    public function addAction($action)
+    {
+        if ($action instanceof AttachmentAction) {
+            $this->actions[] = $action;
+
+            return $this;
+        } elseif (is_array($action)) {
+            $this->actions[] = new AttachmentAction($action);
+
+            return $this;
+        }
+
+        throw new \InvalidArgumentException('The attachment action must be an instance of '. AttachmentAction::class .' or a keyed array');
+    }
+
+    /**
+     * Clear the actions for the attachment
+     *
+     * @return $this
+     */
+    public function clearActions() {
+        $this->actions = [];
+
+        return $this;
+    }
+
+    /**
+     * Convert this attachment to its array representation
+     *
+     * @return array
+     */
+    public function toArray()
+    {
+        $data = parent::toArray();
+
+        $data['actions'] = $this->getActionsAsArrays();
+
+        return $data;
+    }
+
+    /**
+     * Iterates over all actions in this attachment and returns
+     * them in their array form
+     *
+     * @return array
+     */
+    protected function getActionsAsArrays()
+    {
+        $actions = [];
+
+        foreach ($this->getActions() as $action) $actions[] = $action->toArray();
+
+        return $actions;
+    }
+}