Merge pull request #191 from spatie/web-service-link-customization

Allow URL customisations for Google, Outlook and Yahoo

src/Generators/BaseOutlook.php

@@ -8,6 +8,7 @@
 
 /**
  * @see https://github.com/InteractionDesignFoundation/add-event-to-calendar-docs/blob/master/services/outlook-web.md
+ * @psalm-type OutlookUrlParameters = array<string, scalar|null>
  */
 abstract class BaseOutlook implements Generator
 {
@@ -17,6 +18,15 @@ abstract class BaseOutlook implements Generator
     /** @var string {@see https://www.php.net/manual/en/function.date.php} */
     protected $dateTimeFormat = 'Y-m-d\TH:i:s\Z';
 
+    /** @psalm-var OutlookUrlParameters */
+    protected array $urlParameters = [];
+
+    /** @psalm-param OutlookUrlParameters $urlParameters */
+    public function __construct(array $urlParameters = [])
+    {
+        $this->urlParameters = $urlParameters;
+    }
+
     /** Get base URL for links. */
     abstract public function baseUrl(): string;
 
@@ -47,6 +57,10 @@ public function generate(Link $link): string
             $url .= '&location='.$this->sanitizeString($link->address);
         }
 
+        foreach ($this->urlParameters as $key => $value) {
+            $url .= '&'.urlencode($key).(in_array($value, [null, ''], true) ? '' : '='.$this->sanitizeString((string) $value));
+        }
+
         return $url;
     }
 

src/Generators/Google.php

@@ -8,6 +8,7 @@
 
 /**
  * @see https://github.com/InteractionDesignFoundation/add-event-to-calendar-docs/blob/master/services/google.md
+ * @psalm-type GoogleUrlParameters = array<string, scalar|null>
  */
 class Google implements Generator
 {
@@ -16,6 +17,15 @@ class Google implements Generator
     /** @var string */
     protected $dateTimeFormat = 'Ymd\THis\Z';
 
+    /** @psalm-var GoogleUrlParameters */
+    protected array $urlParameters = [];
+
+    /** @psalm-param GoogleUrlParameters $urlParameters */
+    public function __construct(array $urlParameters = [])
+    {
+        $this->urlParameters = $urlParameters;
+    }
+
     /** {@inheritDoc} */
     public function generate(Link $link): string
     {
@@ -44,6 +54,10 @@ public function generate(Link $link): string
             $url .= '&location='.urlencode($link->address);
         }
 
+        foreach ($this->urlParameters as $key => $value) {
+            $url .= '&'.urlencode($key).(in_array($value, [null, ''], true) ? '' : '='.urlencode((string) $value));
+        }
+
         return $url;
     }
 }

src/Generators/Ics.php

@@ -20,7 +20,7 @@ class Ics implements Generator
     /** @var string */
     protected $dateTimeFormat = 'Ymd\THis\Z';
 
-    /** @var IcsOptions */
+    /** @psalm-var IcsOptions */
     protected $options = [];
 
     /** @var array{format?: self::FORMAT_*} */

src/Generators/Yahoo.php

@@ -8,14 +8,25 @@
 
 /**
  * @see https://github.com/InteractionDesignFoundation/add-event-to-calendar-docs/blob/master/services/yahoo.md
+ * @psalm-type YahooUrlParameters = array<string, scalar|null>
  */
 class Yahoo implements Generator
 {
     /** @var string {@see https://www.php.net/manual/en/function.date.php} */
     protected $dateFormat = 'Ymd';
+
     /** @var string */
     protected $dateTimeFormat = 'Ymd\THis\Z';
 
+    /** @psalm-var YahooUrlParameters */
+    protected array $urlParameters = [];
+
+    /** @psalm-param YahooUrlParameters $urlParameters */
+    public function __construct(array $urlParameters = [])
+    {
+        $this->urlParameters = $urlParameters;
+    }
+
     /** {@inheritDoc} */
     public function generate(Link $link): string
     {
@@ -44,6 +55,10 @@ public function generate(Link $link): string
             $url .= '&in_loc='.$this->sanitizeText($link->address);
         }
 
+        foreach ($this->urlParameters as $key => $value) {
+            $url .= '&'.urlencode($key).(in_array($value, [null, ''], true) ? '' : '='.$this->sanitizeText((string) $value));
+        }
+
         return $url;
     }
 

src/Link.php

@@ -17,6 +17,9 @@
  * @property-read string $address
  * @property-read bool $allDay
  * @psalm-import-type IcsOptions from \Spatie\CalendarLinks\Generators\Ics
+ * @psalm-import-type GoogleUrlParameters from \Spatie\CalendarLinks\Generators\Google
+ * @psalm-import-type YahooUrlParameters from \Spatie\CalendarLinks\Generators\Yahoo
+ * @psalm-import-type OutlookUrlParameters from \Spatie\CalendarLinks\Generators\BaseOutlook
  */
 class Link
 {
@@ -123,9 +126,10 @@ public function formatWith(Generator $generator): string
         return $generator->generate($this);
     }
 
-    public function google(): string
+    /** @psalm-param GoogleUrlParameters $urlParameters */
+    public function google(array $urlParameters = []): string
     {
-        return $this->formatWith(new Google());
+        return $this->formatWith(new Google($urlParameters));
     }
 
     /**
@@ -139,19 +143,22 @@ public function ics(array $options = [], array $presentationOptions = []): strin
         return $this->formatWith(new Ics($options, $presentationOptions));
     }
 
-    public function yahoo(): string
+    /** @psalm-param YahooUrlParameters $urlParameters */
+    public function yahoo(array $urlParameters = []): string
     {
-        return $this->formatWith(new Yahoo());
+        return $this->formatWith(new Yahoo($urlParameters));
     }
 
-    public function webOutlook(): string
+    /** @psalm-param OutlookUrlParameters $urlParameters */
+    public function webOutlook(array $urlParameters = []): string
     {
-        return $this->formatWith(new WebOutlook());
+        return $this->formatWith(new WebOutlook($urlParameters));
     }
 
-    public function webOffice(): string
+    /** @psalm-param OutlookUrlParameters $urlParameters */
+    public function webOffice(array $urlParameters = []): string
     {
-        return $this->formatWith(new WebOffice());
+        return $this->formatWith(new WebOffice($urlParameters));
     }
 
     public function __get($property)

tests/Generators/GoogleGeneratorTest.php

@@ -35,4 +35,12 @@ public function it_correctly_generates_all_day_events_by_dates(): void
             $this->generator()->generate($this->createEventMultipleDaysViaStartEndWithTimezoneLink())
         );
     }
+
+    /** @test */
+    public function it_can_generate_an_url_with_custom_parameters(): void
+    {
+        $link = $this->createShortEventLink();
+
+        $this->assertMatchesSnapshot($link->google(['recur' => 'RRULE:FREQ=DAILY']));
+    }
 }

tests/Generators/WebOfficeGeneratorTest.php

@@ -19,4 +19,12 @@ protected function linkMethodName(): string
     {
         return 'webOffice';
     }
+
+    /** @test */
+    public function it_can_generate_an_url_with_custom_parameters(): void
+    {
+        $link = $this->createShortEventLink();
+
+        $this->assertMatchesSnapshot($link->webOffice(['online' => 1]));
+    }
 }

tests/Generators/WebOutlookGeneratorTest.php

@@ -19,4 +19,12 @@ protected function linkMethodName(): string
     {
         return 'webOutlook';
     }
+
+    /** @test */
+    public function it_can_generate_an_url_with_custom_parameters(): void
+    {
+        $link = $this->createShortEventLink();
+
+        $this->assertMatchesSnapshot($link->webOutlook(['online' => 1]));
+    }
 }

tests/Generators/YahooGeneratorTest.php

@@ -34,4 +34,12 @@ public function it_can_generate_a_yahoo_link_for_long_multiple_days_event(): voi
 
         $this->assertMatchesSnapshot($link->yahoo());
     }
+
+    /** @test */
+    public function it_can_generate_an_url_with_custom_parameters(): void
+    {
+        $link = $this->createShortEventLink();
+
+        $this->assertMatchesSnapshot($link->yahoo(['uid' => '750e0c92aa33a7382460a280c2dfb8e6', 'msngr' => null]));
+    }
 }

tests/Generators/__snapshots__/GoogleGeneratorTest__it_can_generate_an_url_with_custom_parameters__1.txt

@@ -0,0 +1 @@
+https://calendar.google.com/calendar/render?action=TEMPLATE&dates=20180201T090000Z/20180201T180000Z&ctz=UTC&text=Birthday&details=With+balloons%2C+clowns+and+stuff%0ABring+a+dog%2C+bring+a+frog&location=Party+Lane+1A%2C+1337+Funtown&recur=RRULE%3AFREQ%3DDAILY

tests/Generators/__snapshots__/WebOfficeGeneratorTest__it_can_generate_an_url_with_custom_parameters__1.txt

@@ -0,0 +1 @@
+https://outlook.office.com/calendar/deeplink/compose?path=/calendar/action/compose&rru=addevent&startdt=2018-02-01T09:00:00Z&enddt=2018-02-01T18:00:00Z&subject=Birthday&body=With%20balloons%2C%20clowns%20and%20stuff%0ABring%20a%20dog%2C%20bring%20a%20frog&location=Party%20Lane%201A%2C%201337%20Funtown&online=1

tests/Generators/__snapshots__/WebOutlookGeneratorTest__it_can_generate_an_url_with_custom_parameters__1.txt

@@ -0,0 +1 @@
+https://outlook.live.com/calendar/action/compose?path=/calendar/action/compose&rru=addevent&startdt=2018-02-01T09:00:00Z&enddt=2018-02-01T18:00:00Z&subject=Birthday&body=With%20balloons%2C%20clowns%20and%20stuff%0ABring%20a%20dog%2C%20bring%20a%20frog&location=Party%20Lane%201A%2C%201337%20Funtown&online=1

tests/Generators/__snapshots__/YahooGeneratorTest__it_can_generate_an_url_with_custom_parameters__1.txt

@@ -0,0 +1 @@
+https://calendar.yahoo.com/?v=60&view=d&type=20&ST=20180201T090000Z&ET=20180201T180000Z&TITLE=Birthday&DESC=With%20balloons%2C%20clowns%20and%20stuff%0ABring%20a%20dog%2C%20bring%20a%20frog&in_loc=Party%20Lane%201A%2C%201337%20Funtown&uid=750e0c92aa33a7382460a280c2dfb8e6&msngr