Refactoring

* Support DSN in client library (fromDsn)
* Use arguments vs options in CLI for required input
* Use common `BaseCommand` for all CLI commands
* Support .env in CLI
* Update README.md

Author: joostfaassen

.env.dist

@@ -0,0 +1 @@
+HERALD_DSN=https://username:password@herald.dev/my-account/my-library/my-transport

.gitignore

@@ -1,4 +1,5 @@
 vendor/*
 config.ini
 composer.phar
+.env
 example/*

README.md

@@ -13,14 +13,21 @@ composer require herald-project/client-php
 use Herald\Client\Client as HeraldClient;
 use Herald\Client\Message as HeraldMessage;
 
-// get the client
+// get the client with explicit parameters
 $herald = new HeraldClient(
     '[herald api username]',
     '[herald api password]',
     '[herald server uri]',
-    '[herald transport, e.g. smtp]')
+    '[herald transport, e.g. smtp]'),
+    '[herald account]',
+    '[herald library]',
 );
 
+// get the client by DSN
+
+$herald = HeraldClient::fromDsn('https://username:password@herald.dev/myAccount/myLibrary/myTransport');
+
+
 // check template existance.
 if ($herald->templateExists('signup')) {
     // get the message
@@ -37,43 +44,74 @@ if ($herald->templateExists('signup')) {
 }
 ```
 ## CLI usage
-```sh
-#!/bin/sh
 
-common_param="\
---username=api_username \
---password=api_password \
---apiurl=http://localhost:8787/api/v2 \
---account=test \
---library=test"
+You can use the `bin/herald-client` CLI application to run commands against your herald server.
+
+The application needs a couple of configuration directives to work:
+
+* username + password: The account you use to connect. Either a user account, or an API key+secret pair
+* apiurl: the base url of herald, (i.e. https://herald.dev) with postfix `/api/v2`
+* account + library: This is the library identifier you use to create your templates, layouts and transports
+
+You can pass this data in 3 ways:
+
+### Individual options:
+
+For example:
+
+    ./bin/herald-client --username=x --password=y --apiurl=https://herald.dev/api/v2 --account=test --library=test template:exists welcome
+
+### A single DSN
+
+For example:
+
+    ./bin/herald-client --dsn=https://x:y@herald.dev/test/test/mandrill
+
+### By environment variables
+
+You can define the environment variable `HERALD_DSN` with a valid URL, this way you don't
+need to pass any options to the CLI application
+
+### By .env
+
+The Herald CLI application loads `.env` before running any commands, allowing you to create a `.env` file 
+like this:
+
+```ini
+HERALD_DSN=https://x:y@herald.dev/test/test/mandrill
+```
+
+This way you also don't need to pass any options for each command
+
+### Example commands
 
-# get list of all contact lists
-bin/herald-client list:list ${common_param}
+    # get list of all contact lists
+    bin/herald-client list:list
 
-# get list of contacts in contact list #1
-bin/herald-client list:contacts ${common_param} --listId=1
+    # get list of contacts in contact list #1
+    bin/herald-client list:contacts 1
 
-# get list of segments for list #1
-bin/herald-client list:segments ${common_param} --listId=1
+    # get list of segments for list #1
+    bin/herald-client list:segments 1
 
-# get available list_fields for list #1
-bin/herald-client list:fields ${common_param} --listId=1
+    # get available list_fields for list #1
+    bin/herald-client list:fields 1
 
-# delete contact #42
-#bin/herald-client contact:delete ${common_param} --contactId=42
+    # delete contact #42
+    #bin/herald-client contact:delete 42
 
-# get properties of contact #6
-bin/herald-client contact:properties ${common_param} --contactId=6
+    # get properties of contact #6
+    bin/herald-client contact:properties 6
 
-# add new contact with address 'new.contact@example.com' to list #1
-bin/herald-client contact:add ${common_param} --listId=1 --address=new.contact@example.com
+    # add new contact with address 'new.contact@example.com' to list #1
+    bin/herald-client contact:add 1 new.contact@example.com
 
-# add new property to contact #36
-bin/herald-client property:add ${common_param} --contactId=36 --listFieldId=4 --value="some value"
+    # add new property to contact #36 for list field id #4
+    bin/herald-client property:add 36 4 "some value"
 
-# send message based on tamplate #1 to all contacts in list #1
-bin/herald-client list:send ${common_param} --listId=1 --templateId=1
+    # send message based on template #7 to all contacts in list #1
+    bin/herald-client list:send 1 7
 
-# send message based on tamplate #1 to contacts in list #1 that meet the conditions for segment #6
-bin/herald-client list:send ${common_param} --listId=1 --templateId=1 --segmentId=6
+    # send message based on template #1 to contacts in list #1 that meet the conditions for segment #6
+    bin/herald-client list:send 1 7 6
 

bin/herald-client

@@ -2,6 +2,7 @@
 <?php
 
 use Symfony\Component\Console\Application;
+use Symfony\Component\Dotenv\Dotenv;
 
 $loader = __DIR__ . '/../vendor/autoload.php';
 
@@ -19,17 +20,20 @@ if (!file_exists($loader)) {
 
 require $loader;
 
+(new Dotenv())->load(__DIR__.'/../.env');
+
+
 $application = new Application('Herald client', '0.0.1');
 $application->setCatchExceptions(true);
 $application->add(new \Herald\Client\Command\SendCommand());
 $application->add(new \Herald\Client\Command\MessageListCommand());
 $application->add(new \Herald\Client\Command\MessageGetCommand());
-$application->add(new \Herald\Client\Command\CheckTemplateCommand());
+$application->add(new \Herald\Client\Command\TemplateExistsCommand());
 
 $application->add(new \Herald\Client\Command\ListListCommand());
 $application->add(new \Herald\Client\Command\ListFieldListCommand());
+$application->add(new \Herald\Client\Command\ListContactsCommand());
 $application->add(new \Herald\Client\Command\SegmentListCommand());
-$application->add(new \Herald\Client\Command\ContactListCommand());
 $application->add(new \Herald\Client\Command\ContactAddCommand());
 $application->add(new \Herald\Client\Command\ContactViewCommand());
 $application->add(new \Herald\Client\Command\ContactDeleteCommand());

composer.json

@@ -24,7 +24,8 @@
         "guzzlehttp/guzzle": "^4.0|^5.0|^6.0"
     },
     "require-dev": {
-        "symfony/console": "^2.4|^3.0"
+        "symfony/console": "^2.4|^3.0",
+        "symfony/dotenv": "^3.0"
     },
     "autoload": {
         "psr-4": {

composer.lock

@@ -17,17 +17,54 @@ class Client implements MessageSenderInterface
     private $account;
     private $library;
 
-    public function __construct($username, $password, $apiUrl, $account, $library, $transportAccount)
+    public function __construct(
+        $username,
+        $password,
+        $apiUrl,
+        $account,
+        $library,
+        $transportAccount = null
+    )
     {
         $this->username = $username;
         $this->password = $password;
         $this->apiUrl = $apiUrl;
         $this->account = $account;
         $this->library = $library;
+        if (!$transportAccount) {
+            $transportAccount = "-";
+        }
         $this->transportAccount = $transportAccount;
         $this->baseUrl = $apiUrl.'/'.$account.'/'.$library;
     }
 
+    public static function fromDsn($dsn)
+    {
+        if (!filter_var($dsn, FILTER_VALIDATE_URL)) {
+            throw new RuntimeException("DSN is an invalid URL: " . $dsn);
+        }
+
+        $part = parse_url($dsn);
+
+        $username = $part['user'];
+        $password = $part['pass'];
+        $apiUrl = $part['scheme'] . '://' . $part['host'] . '/api/v2';
+        $part['path'] = trim($part['path'], '/');
+        $pathPart = explode('/', $part['path']);
+        if ((count($pathPart)<2) || (count($pathPart)>3)) {
+            throw new RuntimeException("Expecting url path with exactly 2 or 3 parts: " . $part['path']);
+        }
+
+        $account = $pathPart[0];
+        $library = $pathPart[1];
+        $transportAccount = null;
+        if (count($pathPart)>2) {
+            $transportAccount = $pathPart[2];
+        }
+
+        return new self($username, $password, $apiUrl, $account, $library, $transportAccount);
+    }
+
     public function setTemplateNamePrefix($prefix)
     {
         $this->templateNamePrefix = $prefix;