[CalendarLink] Add component

splitsh.json

@@ -2,6 +2,7 @@
     "subtrees": {
         "stimulus-bundle": "src/StimulusBundle",
         "ux-autocomplete": "src/Autocomplete",
+        "ux-calendar-link": "src/CalendarLink",
         "ux-dropzone": "src/Dropzone",
         "ux-chartjs": "src/Chartjs",
         "ux-cropperjs": "src/Cropperjs",

src/CalendarLink/.gitattributes

@@ -0,0 +1,5 @@
+/.git* export-ignore
+/.symfony.bundle.yaml export-ignore
+/doc export-ignore
+/phpunit.xml.dist export-ignore
+/tests export-ignore

src/CalendarLink/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,7 @@
+## Please do not submit any Pull Requests here. They will be closed.
+
+Please submit your PR here instead:
+https://github.com/symfony/ux
+
+This repository is what we call a "subtree split": a read-only subset of that main repository.
+We're looking forward to your PR there!

src/CalendarLink/.github/workflows/close-pull-request.yml

@@ -0,0 +1,20 @@
+name: Close Pull Request
+
+on:
+    pull_request_target:
+        types: [opened]
+
+jobs:
+    run:
+        runs-on: ubuntu-latest
+        steps:
+            - uses: superbrothers/close-pull-request@v3
+              with:
+                  comment: |
+                      Thanks for your Pull Request! We love contributions.
+
+                      However, you should instead open your PR on the main repository:
+                      https://github.com/symfony/ux
+
+                      This repository is what we call a "subtree split": a read-only subset of that main repository.
+                      We're looking forward to your PR there!

src/CalendarLink/.gitignore

@@ -0,0 +1,6 @@
+/vendor/
+/composer.lock
+/phpunit.xml
+/.phpunit.result.cache
+
+/var

src/CalendarLink/.symfony.bundle.yaml

@@ -0,0 +1,3 @@
+branches: ['3.x']
+maintained_branches: ['3.x']
+doc_dir: 'doc'

src/CalendarLink/CHANGELOG.md

@@ -0,0 +1,5 @@
+# CHANGELOG
+
+## 3.1
+
+- Add component

src/CalendarLink/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026-present Fabien Potencier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

src/CalendarLink/README.md

@@ -0,0 +1,18 @@
+# Symfony UX Calendar Link
+
+**EXPERIMENTAL** This component is currently experimental and is
+likely to change, or even change drastically.
+
+Symfony UX Calendar Link generates "Add to calendar" links for Google
+Calendar, Outlook.com, Office 365 and iCalendar (`.ics`), the format
+consumed by Apple Calendar, Outlook desktop, Thunderbird and every native
+calendar client. It is part of [the Symfony UX initiative](https://symfony.com/ux).
+
+**This repository is a READ-ONLY sub-tree split**. See
+https://github.com/symfony/ux to create issues or submit pull requests.
+
+## Resources
+
+- [Documentation](doc/index.rst)
+- Report issues and send Pull Requests in the
+  [main Symfony UX repository](https://github.com/symfony/ux)

src/CalendarLink/composer.json

@@ -0,0 +1,54 @@
+{
+    "name": "symfony/ux-calendar-link",
+    "type": "symfony-bundle",
+    "description": "Generates 'Add to calendar' links for Google, Outlook, Office 365 and iCalendar (.ics) in Twig templates.",
+    "keywords": [
+        "symfony-ux",
+        "calendar",
+        "ics"
+    ],
+    "homepage": "https://symfony.com",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Imad ZAIRIG",
+            "email": "imadzairig@gmail.com"
+        },
+        {
+            "name": "Symfony Community",
+            "homepage": "https://symfony.com/contributors"
+        }
+    ],
+    "autoload": {
+        "psr-4": {
+            "Symfony\\UX\\CalendarLink\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "Symfony\\UX\\CalendarLink\\Tests\\": "tests/"
+        }
+    },
+    "require": {
+        "php": ">=8.4",
+        "symfony/framework-bundle": "^7.4|^8.0",
+        "symfony/twig-bundle": "^7.4|^8.0",
+        "symfony/uid": "^7.4|^8.0"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^11.1|^12.0"
+    },
+    "config": {
+        "sort-packages": true
+    },
+    "conflict": {
+        "symfony/flex": "<1.13"
+    },
+    "extra": {
+        "thanks": {
+            "name": "symfony/ux",
+            "url": "https://github.com/symfony/ux"
+        }
+    },
+    "minimum-stability": "dev"
+}

src/CalendarLink/config/services.php

@@ -0,0 +1,55 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+
+use function Symfony\Component\DependencyInjection\Loader\Configurator\service;
+use function Symfony\Component\DependencyInjection\Loader\Configurator\tagged_iterator;
+
+use Symfony\UX\CalendarLink\Ics\IcsBuilder;
+use Symfony\UX\CalendarLink\Provider\GoogleCalendarLinkProvider;
+use Symfony\UX\CalendarLink\Provider\IcsCalendarLinkProvider;
+use Symfony\UX\CalendarLink\Provider\Office365CalendarLinkProvider;
+use Symfony\UX\CalendarLink\Provider\OutlookCalendarLinkProvider;
+use Symfony\UX\CalendarLink\Registry\CalendarLinkProviderRegistry;
+use Symfony\UX\CalendarLink\Twig\UXCalendarLinkExtension;
+use Symfony\UX\CalendarLink\Twig\UXCalendarLinkRuntime;
+
+return static function (ContainerConfigurator $container): void {
+    $services = $container->services();
+
+    $services->set('ux_calendar_link.ics.builder', IcsBuilder::class);
+
+    $services->set('ux_calendar_link.provider.google', GoogleCalendarLinkProvider::class)
+        ->tag('ux_calendar_link.provider');
+
+    $services->set('ux_calendar_link.provider.outlook', OutlookCalendarLinkProvider::class)
+        ->tag('ux_calendar_link.provider');
+
+    $services->set('ux_calendar_link.provider.office365', Office365CalendarLinkProvider::class)
+        ->tag('ux_calendar_link.provider');
+
+    $services->set('ux_calendar_link.provider.ics', IcsCalendarLinkProvider::class)
+        ->args([service('ux_calendar_link.ics.builder')])
+        ->tag('ux_calendar_link.provider');
+
+    $services->set('ux_calendar_link.registry', CalendarLinkProviderRegistry::class)
+        ->args([tagged_iterator('ux_calendar_link.provider')]);
+
+    $services->alias(CalendarLinkProviderRegistry::class, 'ux_calendar_link.registry');
+
+    $services->set('ux_calendar_link.twig.runtime', UXCalendarLinkRuntime::class)
+        ->args([service('ux_calendar_link.registry')])
+        ->tag('twig.runtime');
+
+    $services->set('ux_calendar_link.twig.extension', UXCalendarLinkExtension::class)
+        ->tag('twig.extension');
+};

src/CalendarLink/doc/index.rst

@@ -0,0 +1,141 @@
+Symfony UX Calendar Link
+========================
+
+**EXPERIMENTAL** This component is currently experimental and is likely
+to change, or even change drastically.
+
+Symfony UX CalendarLink is a Symfony bundle that allows generation of "Add to calendar" links for Google
+Calendar, Outlook.com, Office 365 and iCalendar (``.ics``), the format
+consumed by Apple Calendar, Outlook desktop, Thunderbird and every native
+calendar client.
+
+Installation
+------------
+
+Install the bundle using Composer and Symfony Flex:
+
+.. code-block:: terminal
+
+    $ composer require symfony/ux-calendar-link
+
+Usage
+-----
+
+Start by creating a ``CalendarEvent`` object in your controller. Once populated with your event details, pass it to Twig to render the calendar links::
+
+    // src/Controller/EventController.php
+    namespace App\Controller;
+
+    use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
+    use Symfony\Component\HttpFoundation\Response;
+    use Symfony\Component\Routing\Attribute\Route;
+    use Symfony\UX\CalendarLink\CalendarEvent;
+
+    final class EventController extends AbstractController
+    {
+        #[Route('/event/{id}', name: 'app_event_show')]
+        public function show(): Response
+        {
+            // Build from your database, API, etc.
+            $event = new CalendarEvent(
+                title: 'Symfony Live Paris',
+                start: new \DateTimeImmutable('2026-05-14 09:00'),
+                end:   new \DateTimeImmutable('2026-05-15 18:00'),
+                location: 'Cité Universitaire Paris',
+                description: 'Annual Symfony conference in France',
+            );
+
+            return $this->render('event/show.html.twig', ['event' => $event]);
+        }
+    }
+
+Then use the two Twig functions to render links:
+
+* ``ux_calendar_link(event, provider)``: generates a link for one provider
+* ``ux_calendar_links(event)``: generates links for every registered provider
+
+.. code-block:: html+twig
+
+    {# templates/event/show.html.twig #}
+    <a href="{{ ux_calendar_link(event, 'google').url }}">Add to Google Calendar</a>
+
+    <ul class="add-to-calendar">
+        {% for link in ux_calendar_links(event) %}
+            <li><a href="{{ link.url }}">{{ link.label }}</a></li>
+        {% endfor %}
+    </ul>
+
+Supported providers
+-------------------
+
+========================= =========== ========== ============= =========
+Field                     Google      Outlook    Office 365    ICS
+========================= =========== ========== ============= =========
+title                     yes         yes        yes           yes
+start / end               yes         yes        yes           yes
+description               yes         yes        yes           yes
+location                  yes         yes        yes           yes
+all-day                   yes         yes        yes           yes
+reminders (VALARM)        —           —          —             yes
+recurrence (RRULE)        yes         —          —             yes
+========================= =========== ========== ============= =========
+
+Fields marked "—" are silently ignored when generating a link for that
+provider, because the provider's URL scheme does not support them. For example,
+reminders are honoured only in the ``.ics`` output since Google and Outlook
+deeplink URLs cannot carry VALARM data.
+
+Reminders and recurrence
+------------------------
+
+Both recurrence rules and reminders can be attached when constructing the event::
+
+    use Symfony\UX\CalendarLink\CalendarEvent;
+    use Symfony\UX\CalendarLink\CalendarRecurrence;
+    use Symfony\UX\CalendarLink\CalendarReminder;
+
+    $event = new CalendarEvent(
+        title: 'Weekly sync',
+        start: new \DateTimeImmutable('2026-05-14 10:00'),
+        end:   new \DateTimeImmutable('2026-05-14 10:30'),
+        recurrence: CalendarRecurrence::weekly(count: 10),
+        reminders: [new CalendarReminder(minutesBefore: 15)],
+    );
+
+``CalendarRecurrence`` exposes one static factory per RFC 5545 frequency:
+``minutely()``, ``daily()``, ``weekly()``, ``monthly()``, ``yearly()``, each
+accepting the usual ``interval``, ``count`` and ``until`` named arguments. For example::
+
+    // every other day
+    CalendarRecurrence::daily(interval: 2);
+
+    // six monthly occurrences
+    CalendarRecurrence::monthly(count: 6);
+
+    // yearly until 2030
+    CalendarRecurrence::yearly(until: new \DateTimeImmutable('2030-01-01'));
+
+.. note::
+
+    ``CalendarRecurrence::minutely()`` produces a valid RFC 5545 RRULE, but
+    Google Calendar and Outlook deeplink URLs do not support ``FREQ=MINUTELY``
+    and will silently ignore it. Use ``minutely()`` only when targeting the
+    ``ics`` provider.
+
+All-day events
+--------------
+
+Pass ``allDay: true`` to create an event with no specific start or end time::
+
+    $holiday = new CalendarEvent(
+        title: 'Bastille Day',
+        start: new \DateTimeImmutable('2026-07-14'),
+        end:   new \DateTimeImmutable('2026-07-14'),
+        allDay: true,
+    );
+
+Backward compatibility promise
+------------------------------
+
+This bundle follows the same backward-compatibility promise as
+`Symfony itself <https://symfony.com/doc/current/contributing/code/bc.html>`_.

src/CalendarLink/phpunit.xml.dist

@@ -0,0 +1,36 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!-- https://phpunit.de/manual/current/en/appendixes.configuration.html -->
+<phpunit
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:noNamespaceSchemaLocation="vendor/phpunit/phpunit/phpunit.xsd"
+        colors="true"
+        bootstrap="tests/bootstrap.php"
+        failOnDeprecation="true"
+        failOnRisky="true"
+        failOnWarning="true"
+        cacheDirectory=".phpunit.cache"
+>
+    <php>
+        <ini name="error_reporting" value="-1"/>
+        <env name="SHELL_VERBOSITY" value="-1"/>
+        <env name="KERNEL_CLASS" value="Symfony\UX\CalendarLink\Tests\Fixtures\TestKernel" />
+    </php>
+    <testsuites>
+        <testsuite name="Symfony UX CalendarLink Test Suite">
+            <directory>./tests</directory>
+        </testsuite>
+    </testsuites>
+    <source
+            ignoreSuppressionOfDeprecations="true"
+            ignoreIndirectDeprecations="true"
+            restrictNotices="true"
+            restrictWarnings="true"
+    >
+        <include>
+            <directory>src</directory>
+        </include>
+        <deprecationTrigger>
+            <function>trigger_deprecation</function>
+        </deprecationTrigger>
+    </source>
+</phpunit>