* update readme, license

* introduce modern structure

Author: ivastly

.env.example

@@ -1,2 +1,2 @@
-.env
-vendor
+vendor/
+app/config/config.php

.gitignore

@@ -0,0 +1,3 @@
+# Contributions are welcome
+
+* just create a PR on Github and let me know

CONTRIBUTING.md

@@ -0,0 +1,13 @@
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+                    Version 2, December 2004
+
+ Copyright (C) 2004 Sam Hocevar <[email protected]>
+
+ Everyone is permitted to copy and distribute verbatim or modified
+ copies of this license document, and changing it is allowed as long
+ as the name is changed.
+
+            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.

LICENSE

@@ -1,7 +1,40 @@
-## How To Start
-* create `.env` file in the root
+# Rationale
+Surprised to see your key colleague ran out for vacation again?
+Yes, *there was an email about it 2 months ago*..
+Usually we forget about it same minute, and realize the fact when it is too late.
+You don't want another vacation to ruin your sprint again, do you?
+
+Then welcome a solution to **sync all vacations from any HR system to any Calendar**, so you always know who is going to be AFK!
+
+# How To Start
+* install dependencies
 ```bash
-copy .env.example .env
-nano .env
+composer install
 ```
-* finally, put the script to be run every day. It will export all vacations to your Outlook Calendar. 
+* create and fill `app/config/config.php` file
+```bash
+cp app/config/config.example.php app/config/config.php
+nano app/config/config.php
+```
+* finally, put the script to be run every minute. It will export all vacations to your Outlook Calendar. 
+```php
+php sync.php
+```
+
+# Security concerns
+MS Exchange API (known as Exchange Web Services) requires plain-text user password to be specified.
+To workaround this, the password is requested when the script starts. So, it is never stored on disk or github as plain text.
+Thus, the solution is enterprise ready and 100% IT-security compliant.  
+
+# Known Limitations
+Only [Securex HR Online](https://www.securex.lu/en/our-it-tool-hronline/9) -> MS Exchange Calendar is supported.
+
+# TODO
+* delete vacation events from Calendar if they disappear from Securex
+* support custom observable periods (current hardcoded to 1 month)
+* support more Calendars - Google Calendar, Zoho Calendar, etc.
+* support more ATS - BambooHR, Recruitee, Manatal, Oracle Taleo, etc.
+* tests
+
+# LICENSE
+See LICENSE file

README.md

@@ -0,0 +1,15 @@
+<?php declare(strict_types=1);
+
+use jamesiarmes\PhpEws\Client;
+
+return [
+	'email'               => '[email protected]',
+	'plain_text_password' => 'secret',
+	'team'                => [
+		'[email protected]' => 'Developer',
+		'[email protected]'    => 'Scrum Master',
+		'[email protected]'  => 'Team Lead',
+	],
+	'ms_exchange_host'    => 'webmail.company.com',
+	'ms_exchange_version' => Client::VERSION_2016, // must be a constant from vendor/php-ews/php-ews/src/Client.php
+];

app/config/config.example.php

@@ -1,16 +1,21 @@
 {
-    "name": "ivastly/securex-outlook-intgrtn",
+  "name": "ivastly/ats-calendar-integration",
     "type": "project",
-    "description": "Exports vacations from securex (securexhrservices.eu) to MS Outlook calendar",
+  "description": "Exports vacations from any ATS to any Calendar system, e.g. Securex => MS Outlook Calendar",
     "keywords": [
         "outlook",
         "securex",
         "securexhrservices",
-        "Graph API"
+      "ews"
     ],
     "license": "WTFPL",
     "require": {
-        "php-ews/php-ews":  "~1.0",
-        "symfony/dotenv": "^4.3"
+      "php": "^7.3",
+      "php-ews/php-ews": "~1.0"
+    },
+  "autoload": {
+    "psr-4": {
+      "Src\\": "src"
+    }
     }
 }

composer.json

@@ -0,0 +1,17 @@
+<?php declare(strict_types=1);
+
+namespace Src\Calendar\MsExchange\Business\Domain;
+
+use DateTime;
+
+class Event
+{
+	/** @var string */
+	private $title;
+
+	/** @var DateTime */
+	private $startDate;
+
+	/** @var DateTime */
+	private $endDate;
+}

composer.lock

@@ -0,0 +1,11 @@
+<?php
+
+namespace Src\Calendar\DataAccess\Api;
+
+interface CalendarClientInterface
+{
+	/**
+	 * @return Event[]
+	 */
+	public function searchForVacationEvents(): array;
+}

src/Calendar/Business/Domain/Event.php

@@ -0,0 +1,83 @@
+<?php declare(strict_types=1);
+
+namespace Src\MsExchange;
+
+use DateTime;
+use jamesiarmes\PhpEws\ArrayType\NonEmptyArrayOfBaseFolderIdsType;
+use jamesiarmes\PhpEws\Client as PhpEwsClient;
+use jamesiarmes\PhpEws\Enumeration\DefaultShapeNamesType;
+use jamesiarmes\PhpEws\Enumeration\DistinguishedFolderIdNameType;
+use jamesiarmes\PhpEws\Enumeration\ResponseClassType;
+use jamesiarmes\PhpEws\Request\FindItemType;
+use jamesiarmes\PhpEws\Type\CalendarViewType;
+use jamesiarmes\PhpEws\Type\DistinguishedFolderIdType;
+use jamesiarmes\PhpEws\Type\ItemResponseShapeType;
+use Src\Calendar\DataAccess\Api\CalendarClientInterface;
+use Src\Config;
+
+class Client implements CalendarClientInterface
+{
+	/** @var PhpEwsClient */
+	private $client;
+
+	public function __construct(Config $config)
+	{
+		$this->client =
+			new PhpEwsClient(
+				$config->getMsExchangeHost(),
+				$config->getEmail(),
+				$config->getPassword(),
+				$config->getMsExchangeVersion()
+			);
+	}
+
+	public function searchForVacationEvents(): array
+	{
+		$startDate = new DateTime('now');
+		$endDate   = new DateTime('+1 month');
+		$timezone  = 'E. Europe Standard Time';
+		$this->client->setTimezone($timezone);
+		$request                                           = new FindItemType();
+		$request->ParentFolderIds                          = new NonEmptyArrayOfBaseFolderIdsType();
+		$request->ItemShape                                = new ItemResponseShapeType();
+		$request->ItemShape->BaseShape                     = DefaultShapeNamesType::ALL_PROPERTIES;
+		$folder_id                                         = new DistinguishedFolderIdType();
+		$folder_id->Id                                     = DistinguishedFolderIdNameType::CALENDAR;
+		$request->ParentFolderIds->DistinguishedFolderId[] = $folder_id;
+		$request->CalendarView                             = new CalendarViewType();
+		$request->CalendarView->StartDate                  = $startDate->format('c');
+		$request->CalendarView->EndDate                    = $endDate->format('c');
+		$response                                          = $this->client->FindItem($request);
+
+// Iterate over the results, printing any error messages or event ids.
+		$ResponseMessages = $response->ResponseMessages->FindItemResponseMessage;
+		foreach ($ResponseMessages as $response_message)
+		{
+			if ($response_message->ResponseClass != ResponseClassType::SUCCESS)
+			{
+				$code    = $response_message->ResponseCode;
+				$message = $response_message->MessageText;
+				fwrite(
+					STDERR,
+					"Failed to search for events with \"$code: $message\"\n"
+				);
+				continue;
+			}
+
+			// Iterate over the events that were found, printing some data for each.
+			$items = $response_message->RootFolder->Items->CalendarItem;
+			foreach ($items as $item)
+			{
+				$id     = $item->ItemId->Id;
+				$start  = new DateTime($item->Start);
+				$end    = new DateTime($item->End);
+				$output = 'Found event ' . $item->ItemId->Id . "\n"
+					. '  Change Key: ' . $item->ItemId->ChangeKey . "\n"
+					. '  Title: ' . $item->Subject . "\n"
+					. '  Start: ' . $start->format('l, F jS, Y g:ia') . "\n"
+					. '  End:   ' . $end->format('l, F jS, Y g:ia') . "\n\n";
+				fwrite(STDOUT, $output);
+			}
+		}
+	}
+}

src/Calendar/DataAccess/Api/CalendarClientInterface.php

@@ -0,0 +1,55 @@
+<?php declare(strict_types=1);
+
+namespace Src;
+
+class Config
+{
+	/** @var string */
+	private $email;
+
+	/** @var string */
+	private $password;
+
+	/** @var array */
+	private $team;
+
+	/** @var string */
+	private $msExchangeHost;
+
+	/** @var string */
+	private $msExchangeVersion;
+
+	public function __construct(array $config)
+	{
+		$this->email             = $config['email'];
+		$this->password          = $config['plain_text_password'];
+		$this->team              = $config['team'];
+		$this->msExchangeHost    = $config['ms_exchange_host'];
+		$this->msExchangeVersion = $config['ms_exchange_version'];
+	}
+
+	public function getEmail(): string
+	{
+		return $this->email;
+	}
+
+	public function getPassword(): string
+	{
+		return $this->password;
+	}
+
+	public function getTeam(): array
+	{
+		return $this->team;
+	}
+
+	public function getMsExchangeHost(): string
+	{
+		return $this->msExchangeHost;
+	}
+
+	public function getMsExchangeVersion(): string
+	{
+		return $this->msExchangeVersion;
+	}
+}

src/Calendar/MsExchange/DataAccess/Api/Client.php

@@ -1,11 +1,11 @@
 <?php declare(strict_types=1);
 
-use Symfony\Component\Dotenv\Dotenv;
+use Src\Config;
+use Src\MsExchange\Client;
 
 require_once 'vendor/autoload.php';
 
-$dotenv = new Dotenv();
-$dotenv->load(__DIR__.'/.env');
-
-
+$config         = new Config(require_once __DIR__ . '/app/config/config.php');
+$exchangeClient = new Client($config);
 
+$exchangeClient->searchForVacationEvents();