Merge pull request #1 from bcrowe/develop

2.0.0-alpha1

README.md

@@ -60,21 +60,25 @@ $ composer require bcrowe/growl
 
 ## Usage
 
-Create a new instance of the `Growl` class and supply a `Builder` class in its
-construction:
+Create a new instance of the `Growl` class. You can optionally supply a
+`Builder` class and its path if you don't wish for the package to choose
+a notification program based on your system:
 
 ```php
 <?php
 use BryanCrowe\Growl\Growl;
-use BryanCrowe\Growl\Builder\GrowlNotifyBuilder;
-
 // ...
+$Growl = new Growl;
+?>
+```
 
-$Growl = new Growl(new GrowlNotifyBuilder());
-
-// You can optionally set the path for a command by passing in a string to the
-// Builder's constructor. For example:
+Or...
 
+```php
+<?php
+use BryanCrowe\Growl\Growl;
+use BryanCrowe\Growl\Builder\GrowlNotifyBuilder;
+// ...
 $Growl = new Growl(new GrowlNotifyBuilder('/usr/local/bin/growlnotify'));
 ?>
 ```
@@ -86,20 +90,23 @@ After setting options, the last thing to do is build the command with
 
 ```php
 <?php
-$Growl->setOption('title', 'Hello World')
-	->setOption('message', 'How are you doing?')
-	->setOption('sticky', true)
-	->execute();
+(new Growl)
+    ->setOption('title', 'Hello World')
+    ->setOption('message', 'How are you doing?')
+    ->setOption('sticky', true)
+    ->execute();
 
-// or...
+// Or...
 
-$cmd = $Growl->setOptions([
-		'title' => 'Hello World',
-		'message' => 'How are you doing?',
-		'sticky' => true
-	])->buildCommand();
+$Growl = new Growl;
+$Growl->setOptions([
+        'title' => 'Hello World',
+        'message' => 'How are you doing?',
+        'sticky' => true
+    ])
+    ->buildCommand();
 
-exec($cmd);
+exec($Growl);
 ?>
 ```
 
@@ -112,23 +119,23 @@ while escaping is enabled.
 <?php
 // Completely disable escaping...
 $Growl->setOptions([
-		'title' => 'Hello World',
-		'subtitle' => 'Earth',
-		'message' => 'How are you doing?',
-		'open' => 'http://www.google.com'
-	])
-	->setEscape(false)
-	->execute();
+        'title' => 'Hello World',
+        'subtitle' => 'Earth',
+        'message' => 'How are you doing?',
+        'url' => 'http://www.google.com'
+    ])
+    ->setEscape(false)
+    ->execute();
 
 // Set a safe list of option keys. Can be an array of option keys, or a string.
 $Growl->setOptions([
-		'title' => 'Hello World',
-		'subtitle' => $safeSubtitle,
-		'message' => 'How are you doing?',
-		'open' => $safeURL
-	])
-	->setSafe(['subtitle', 'open'])
-	->execute();
+        'title' => 'Hello World',
+        'subtitle' => $safeSubtitle,
+        'message' => 'How are you doing?',
+        'url' => $safeURL
+    ])
+    ->setSafe(['subtitle', 'open'])
+    ->execute();
 ?>
 ```
 
@@ -145,7 +152,9 @@ Available option keys:
 * **title** *string* The title of the growl.
 * **message** *string* The growl's body.
 * **sticky** *boolean* Whether or not make the growl stick until closed.
-* **appIcon** *string* An application icon to use.
+* **image** *string* A name of an application's icon to use, e.g., "Mail"
+(Darwin), the path to a file on the system (Darwin & Windows), or a URL to an
+image (Windows).
 * **url** *string* A URL to open if the growl is clicked.
 
 #### TerminalNotifierBuilder
@@ -157,9 +166,9 @@ Available option keys:
 * **title** *string* The title of the notification.
 * **subtitle** *string* The notification's subtitle.
 * **message** *string* The notification's body.
-* **appIcon** *string* A URL to an image to be used as the icon. *(Mavericks+ only)*
+* **image** *string* A URL to an image to be used as the icon. *(Mavericks+ only)*
 * **contentImage** *string* A URL to an image to be in the notification body. *(Mavericks+ only)*
-* **open** *string* A URL to go to when the notification is clicked.
+* **url** *string* A URL to go to when the notification is clicked.
 
 #### NotifySendBuilder
 

src/Builder/BuilderAbstract.php

@@ -2,7 +2,7 @@
 
 namespace BryanCrowe\Growl\Builder;
 
-use \InvalidARgumentException;
+use InvalidArgumentException;
 
 abstract class BuilderAbstract implements BuilderInterface
 {
@@ -23,18 +23,21 @@ public function __construct($path = null)
         if ($path === null) {
             return;
         }
-
         if (is_string($path)) {
             $this->path = $path;
-        } else {
-            throw new InvalidArgumentException('This constructor expects a string argument.');
+            return;
         }
+
+        throw new InvalidArgumentException(
+            'This constructor expects a string argument.'
+        );
     }
 
     /**
      * Build the command string to be executed.
      *
-     * @param array $options An array of options to use for building the command.
+     * @param array $options An array of options to use for building the
+     * command.
      * @return string
      */
     abstract public function build($options);

src/Builder/GrowlNotifyBuilder.php

@@ -25,16 +25,21 @@ public function build($options)
         $command = $this->path;
 
         if (isset($options['title'])) {
-            $command .= ' -t ' . $options['title'];
+            $command .= " -t {$options['title']}";
         }
         if (isset($options['message'])) {
-            $command .= ' -m ' . $options['message'];
+            $command .= " -m {$options['message']}";
         }
-        if (isset($options['appIcon'])) {
-            $command .= ' -a ' . $options['appIcon'];
+        if (isset($options['image'])) {
+            $pathInfo = pathinfo($options['image']);
+            if (isset($pathInfo['extension'])) {
+                $command .= " --image {$options['image']}";
+            } else {
+                $command .= " -a {$options['image']}";
+            }
         }
         if (isset($options['url'])) {
-            $command .= ' --url ' . $options['url'];
+            $command .= " --url {$options['url']}";
         }
         if (isset($options['sticky']) && $options['sticky'] === true) {
             $command .= ' -s';

src/Builder/GrowlNotifyWindowsBuilder.php

@@ -25,19 +25,19 @@ public function build($options)
         $command = $this->path;
 
         if (isset($options['title'])) {
-            $command .= ' /t:' . $options['title'];
+            $command .= " /t:{$options['title']}";
         }
-        if (isset($options['appIcon'])) {
-            $command .= ' /ai:' . $options['appIcon'];
+        if (isset($options['image'])) {
+            $command .= " /i:{$options['image']}";
         }
         if (isset($options['url'])) {
-            $command .= ' /cu:' . $options['url'];
+            $command .= " /cu:{$options['url']}";
         }
         if (isset($options['sticky']) && $options['sticky'] === true) {
             $command .= ' /s:true';
         }
         if (isset($options['message'])) {
-            $command .= ' ' . $options['message'];
+            $command .= " {$options['message']}";
         }
 
         return $command;

src/Builder/NotifySendBuilder.php

@@ -25,10 +25,10 @@ public function build($options)
         $command = $this->path;
 
         if (isset($options['title'])) {
-            $command .= ' ' . $options['title'];
+            $command .= " {$options['title']}";
         }
         if (isset($options['message'])) {
-            $command .= ' ' . $options['message'];
+            $command .= " {$options['message']}";
         }
         if (isset($options['sticky']) && $options['sticky'] === true) {
             $command .= ' -t 0';

src/Builder/TerminalNotifierBuilder.php

@@ -25,22 +25,22 @@ public function build($options)
         $command = $this->path;
 
         if (isset($options['title'])) {
-            $command .= ' -title ' . $options['title'];
+            $command .= " -title {$options['title']}";
         }
         if (isset($options['subtitle'])) {
-            $command .= ' -subtitle ' . $options['subtitle'];
+            $command .= " -subtitle {$options['subtitle']}";
         }
         if (isset($options['message'])) {
-            $command .= ' -message ' . $options['message'];
+            $command .= " -message {$options['message']}";
         }
-        if (isset($options['appIcon'])) {
-            $command .= ' -appIcon ' . $options['appIcon'];
+        if (isset($options['image'])) {
+            $command .= " -appIcon {$options['image']}";
         }
         if (isset($options['contentImage'])) {
-            $command .= ' -contentImage ' . $options['contentImage'];
+            $command .= " -contentImage {$options['contentImage']}";
         }
-        if (isset($options['open'])) {
-            $command .= ' -open ' . $options['open'];
+        if (isset($options['url'])) {
+            $command .= " -open {$options['url']}";
         }
 
         return $command;

src/Growl.php

@@ -3,7 +3,11 @@
 namespace BryanCrowe\Growl;
 
 use BryanCrowe\Growl\Builder\BuilderAbstract;
-use \InvalidArgumentException;
+use BryanCrowe\Growl\Builder\GrowlNotifyBuilder;
+use BryanCrowe\Growl\Builder\GrowlNotifyWindowsBuilder;
+use BryanCrowe\Growl\Builder\NotifySendBuilder;
+use BryanCrowe\Growl\Builder\TerminalNotifierBuilder;
+use InvalidArgumentException;
 
 /**
  * This class accepts a Builder in its constructor to be used for building the
@@ -18,7 +22,14 @@ class Growl
      *
      * @var BuilderAbstract
      */
-    protected $builder;
+    protected $builder = null;
+
+    /**
+     * Stores the built command when treating this object like a string.
+     *
+     * @var string
+     */
+    protected $command = '';
 
     /**
      * An array of options to use for building commands.
@@ -47,12 +58,36 @@ class Growl
      *
      * Accepts a Builder object to be used in building the command.
      *
-     * @param BuilderAbstract $builder
+     * @param $builder
      * @return void
+     * @throws InvalidArgumentException If not null or a BuilderAbstract
+     * instance.
+     */
+    public function __construct($builder = null)
+    {
+        if ($builder === null) {
+            $this->builder = $this->selectBuilder();
+            return;
+        }
+        if ($builder instanceof BuilderAbstract) {
+            $this->builder = $builder;
+            return;
+        }
+
+        throw new InvalidArgumentException(
+            'This constructor expects null or a BuilderAbstract instance.'
+        );
+    }
+
+    /**
+     * Allow this object to be treated as a string in the case of using the
+     * buildCommand() method instead of executing the command.
+     *
+     * @return string
      */
-    public function __construct(BuilderAbstract $builder)
+    public function __toString()
     {
-        $this->builder = $builder;
+        return $this->command;
     }
 
     /**
@@ -66,9 +101,10 @@ public function execute()
         if ($this->escape !== false) {
             $this->options = $this->escape($this->options);
         }
-        $command = $this->builder->build($this->options);
-
-        exec($command);
+        if ($this->builder !== null) {
+            $command = $this->builder->build($this->options);
+            exec($command);
+        }
     }
 
     /**
@@ -81,9 +117,11 @@ public function buildCommand()
         if ($this->escape !== false) {
             $this->options = $this->escape($this->options);
         }
-        $command = $this->builder->build($this->options);
+        if ($this->builder !== null) {
+            $this->command = $this->builder->build($this->options);
+        }
 
-        return $command;
+        return $this;
     }
 
     /**
@@ -174,6 +212,37 @@ protected function escape(array $options)
                 $results[$key] = $value;
             }
         }
+
         return $results;
     }
+
+    /**
+     * Chooses a Builder to use depending on the operating system and which
+     * program is installed.
+     *
+     * @codeCoverageIgnore
+     * @return BuilderAbstract A suitable Builder for a notification program
+     * that was found on the system.
+     */
+    protected function selectBuilder()
+    {
+        if (PHP_OS === 'Darwin') {
+            if (exec('which growlnotify')) {
+                return new GrowlNotifyBuilder;
+            }
+            if (exec('which terminal-notifier')) {
+                return new TerminalNotifierBuilder;
+            }
+        }
+        if (PHP_OS === 'Linux') {
+            if (exec('which notify-send')) {
+                return new NotifySendBuilder;
+            }
+        }
+        if (PHP_OS === 'WINNT') {
+            if (exec('where growlnotify')) {
+                return new GrowlNotifyWindowsBuilder;
+            }
+        }
+    }
 }