Dev

.github/workflows/ci.yml

@@ -26,7 +26,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        php-versions: ['8.1']
+        php-versions: ['8.2']
         dependencies: ['latest', 'oldest']
     steps:
       - name: Checkout
@@ -63,7 +63,7 @@ jobs:
         run: composer validate --no-check-all --no-check-lock --strict;
       - name: Linting all php files
         run: find src/ tests/ public/ -name ''*.php'' -print0 | xargs -0 -n 1 -P 4 php -l; php -l;
-      - name: Running  unit tests
+      - name: Running unit tests
         run: vendor/bin/phpunit tests/Unit/;
         continue-on-error: ${{matrix.php-versions == '8.0' }} # [temp-php8]
       - name: Running the integration tests

.github/workflows/client-docs.yml

@@ -31,7 +31,7 @@ jobs:
       - name: Setup PHP with Composer and Extensions
         uses: shivammathur/setup-php@v2
         with:
-          php-version: 8.1
+          php-version: 8.2
           extensions: mbstring, dom, fileinfo, mysql
 
       - name: Cache Composer Dependencies

.github/workflows/front-docs.yml

@@ -38,7 +38,7 @@ jobs:
       - name: Setup PHP with Composer and Extensions
         uses: shivammathur/setup-php@v2
         with:
-          php-version: 8.1
+          php-version: 8.2
           extensions: mbstring, dom, fileinfo, mysql
 
       - name: Cache Composer Dependencies

.github/workflows/restapi-docs.yml

@@ -16,7 +16,7 @@ jobs:
       - name: Setup PHP with Composer and Extensions
         uses: shivammathur/setup-php@v2
         with:
-          php-version: 8.1
+          php-version: 8.2
           extensions: mbstring, dom, fileinfo, mysql
 
       - name: Cache Composer Dependencies

composer.json

@@ -41,8 +41,8 @@
         "source": "https://github.com/phpList/rest-api"
     },
     "require": {
-        "php": "^8.1",
-        "phplist/core": "dev-main",
+        "php": "^8.2",
+        "phplist/core": "dev-dev",
         "elasticsearch/elasticsearch": "^8.9",
         "friendsofsymfony/rest-bundle": "*",
         "symfony/test-pack": "^1.0",

src/Messaging/Controller/AttachmentController.php

@@ -75,7 +75,7 @@ public function download(
         }
 
         return new StreamedResponse(
-            callback: function () use ($downloadable) {
+            function () use ($downloadable) {
                 $stream = $downloadable->content;
 
                 if ($stream->isSeekable()) {

src/Messaging/Controller/CampaignMessageDataController.php

@@ -0,0 +1,128 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpList\RestBundle\Messaging\Controller;
+
+use Doctrine\ORM\EntityManagerInterface;
+use OpenApi\Attributes as OA;
+use PhpList\Core\Domain\Identity\Service\Authentication;
+use PhpList\Core\Domain\Identity\Service\PermissionChecker;
+use PhpList\Core\Domain\Messaging\Model\Message;
+use PhpList\Core\Domain\Messaging\Service\Manager\MessageDataManager;
+use PhpList\Core\Domain\Messaging\Service\MessageDataLoader;
+use PhpList\RestBundle\Common\Controller\BaseController;
+use PhpList\RestBundle\Common\Validator\RequestValidator;
+use PhpList\RestBundle\Messaging\Dto\CampaignMessageData;
+use PhpList\RestBundle\Messaging\Request\UpdateMessageDataRequest;
+use PhpList\RestBundle\Messaging\Serializer\MessageDataNormalizer;
+use Symfony\Bridge\Doctrine\Attribute\MapEntity;
+use Symfony\Component\HttpFoundation\JsonResponse;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\Response;
+use Symfony\Component\Routing\Attribute\Route;
+
+/**
+ * This controller provides REST API to set the campaign settings that are kept in the message data.
+ */
+#[Route('/campaigns', name: 'campaign_message_data_')]
+class CampaignMessageDataController extends BaseController
+{
+    public function __construct(
+        Authentication $authentication,
+        RequestValidator $validator,
+        private readonly MessageDataManager $messageDataManager,
+        private readonly MessageDataLoader $messageDataLoader,
+        private readonly PermissionChecker $permissionChecker,
+        private readonly EntityManagerInterface $entityManager,
+        private readonly MessageDataNormalizer $messageDataNormalizer,
+    ) {
+        parent::__construct($authentication, $validator);
+    }
+
+    #[Route(
+        '/{messageId}/message-data',
+        name: 'update',
+        requirements: ['messageId' => '\d+'],
+        methods: ['PATCH']
+    )]
+    #[OA\Patch(
+        path: '/api/v2/campaigns/{messageId}/message-data',
+        description: '🚧 **Status: Beta** – This method is under development. Avoid using in production. ' .
+        'Sets campaign settings that are not part of the campaign itself: analytics tracking, notification ' .
+        'addresses and excluded lists. Only the fields that are sent are changed.',
+        summary: 'Set campaign message data.',
+        requestBody: new OA\RequestBody(
+            description: 'The settings to change.',
+            required: true,
+            content: new OA\JsonContent(ref: '#/components/schemas/UpdateMessageDataRequest')
+        ),
+        tags: ['campaigns'],
+        parameters: [
+            new OA\Parameter(
+                name: 'php-auth-pw',
+                description: 'Session key obtained from login',
+                in: 'header',
+                required: true,
+                schema: new OA\Schema(type: 'string')
+            ),
+            new OA\Parameter(
+                name: 'messageId',
+                description: 'message ID',
+                in: 'path',
+                required: true,
+                schema: new OA\Schema(type: 'string')
+            )
+        ],
+        responses: [
+            new OA\Response(
+                response: 200,
+                description: 'Success, returns all the settings of the campaign',
+                content: new OA\JsonContent(ref: '#/components/schemas/MessageData')
+            ),
+            new OA\Response(
+                response: 401,
+                description: 'Not authenticated',
+                content: new OA\JsonContent(ref: '#/components/schemas/UnauthorizedResponse')
+            ),
+            new OA\Response(
+                response: 403,
+                description: 'Failure',
+                content: new OA\JsonContent(ref: '#/components/schemas/UnauthorizedResponse')
+            ),
+            new OA\Response(
+                response: 404,
+                description: 'Failure',
+                content: new OA\JsonContent(ref: '#/components/schemas/NotFoundErrorResponse')
+            ),
+            new OA\Response(
+                response: 422,
+                description: 'Failure',
+                content: new OA\JsonContent(ref: '#/components/schemas/ValidationErrorResponse')
+            ),
+        ]
+    )]
+    public function updateMessageData(
+        Request $request,
+        #[MapEntity(mapping: ['messageId' => 'id'])] ?Message $message = null,
+    ): JsonResponse {
+        $authUser = $this->requireAuthentication($request);
+        if ($message === null) {
+            throw $this->createNotFoundException('Campaign not found.');
+        }
+
+        if (!$this->permissionChecker->canEdit($authUser, $message)) {
+            throw $this->createAccessDeniedException('You are not allowed to update campaigns.');
+        }
+
+        /** @var UpdateMessageDataRequest $messageDataRequest */
+        $messageDataRequest = $this->validator->validate($request, UpdateMessageDataRequest::class);
+
+        $this->messageDataManager->storeMessageData($message, $messageDataRequest->getDto());
+        $this->entityManager->flush();
+
+        $messageData = new CampaignMessageData(($this->messageDataLoader)($message));
+
+        return $this->json($this->messageDataNormalizer->normalize($messageData), Response::HTTP_OK);
+    }
+}

src/Messaging/Dto/CampaignMessageData.php

@@ -0,0 +1,16 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpList\RestBundle\Messaging\Dto;
+
+/**
+ * The message data of a campaign, as loaded by core's MessageDataLoader.
+ */
+class CampaignMessageData
+{
+    /** @param array<string, mixed> $values */
+    public function __construct(public readonly array $values)
+    {
+    }
+}

src/Messaging/Request/UpdateMessageDataRequest.php

@@ -0,0 +1,133 @@
+<?php
+
+declare(strict_types=1);
+
+namespace PhpList\RestBundle\Messaging\Request;
+
+use OpenApi\Attributes as OA;
+use PhpList\RestBundle\Common\Request\RequestInterface;
+use PhpList\RestBundle\Subscription\Validator\Constraint\ListExists;
+use Symfony\Component\Validator\Constraints as Assert;
+use Symfony\Component\Validator\Context\ExecutionContextInterface;
+
+/**
+ * Campaign settings that are kept in the message data, apart from the campaign itself. Only the fields that are
+ * sent are changed; an empty string clears a text setting.
+ */
+#[OA\Schema(
+    schema: 'UpdateMessageDataRequest',
+    properties: [
+        new OA\Property(
+            property: 'google_track',
+            description: 'Add analytics tracking parameters to the links of the campaign.',
+            type: 'boolean',
+            example: true
+        ),
+        new OA\Property(property: 'utm_source', description: 'Google Analytics source.', type: 'string'),
+        new OA\Property(property: 'utm_medium', description: 'Google Analytics medium.', type: 'string'),
+        new OA\Property(property: 'utm_campaign', description: 'Google Analytics campaign.', type: 'string'),
+        new OA\Property(property: 'pk_source', description: 'Matomo source.', type: 'string'),
+        new OA\Property(property: 'pk_medium', description: 'Matomo medium.', type: 'string'),
+        new OA\Property(property: 'pk_campaign', description: 'Matomo campaign.', type: 'string'),
+        new OA\Property(
+            property: 'notify_start',
+            description: 'Email addresses, separated by a comma, to alert when sending starts.',
+            type: 'string',
+            example: 'admin@example.com'
+        ),
+        new OA\Property(
+            property: 'notify_end',
+            description: 'Email addresses, separated by a comma, to alert when sending finishes.',
+            type: 'string',
+            example: 'admin@example.com'
+        ),
+        new OA\Property(
+            property: 'exclude_lists',
+            description: 'IDs of the lists whose subscribers are left out of the campaign.',
+            type: 'array',
+            items: new OA\Items(type: 'integer', minimum: 1),
+            example: [4, 5]
+        ),
+    ],
+    type: 'object'
+)]
+class UpdateMessageDataRequest implements RequestInterface
+{
+    #[Assert\Type('bool')]
+    public ?bool $googleTrack = null;
+
+    #[Assert\Length(max: 255)]
+    public ?string $utmSource = null;
+
+    #[Assert\Length(max: 255)]
+    public ?string $utmMedium = null;
+
+    #[Assert\Length(max: 255)]
+    public ?string $utmCampaign = null;
+
+    #[Assert\Length(max: 255)]
+    public ?string $pkSource = null;
+
+    #[Assert\Length(max: 255)]
+    public ?string $pkMedium = null;
+
+    #[Assert\Length(max: 255)]
+    public ?string $pkCampaign = null;
+
+    #[Assert\Length(max: 255)]
+    public ?string $notifyStart = null;
+
+    #[Assert\Length(max: 255)]
+    public ?string $notifyEnd = null;
+
+    #[Assert\Type('array')]
+    #[Assert\All([
+        new Assert\Sequentially([
+            new Assert\Type('integer'),
+            new Assert\Positive(),
+            new ListExists(),
+        ]),
+    ])]
+    public ?array $excludeLists = null;
+
+    #[Assert\Callback]
+    public function validateNotifyAddresses(ExecutionContextInterface $context): void
+    {
+        foreach (['notifyStart' => $this->notifyStart, 'notifyEnd' => $this->notifyEnd] as $property => $value) {
+            if ($value === null || $value === '') {
+                continue;
+            }
+
+            foreach (array_map('trim', explode(',', $value)) as $address) {
+                $context->getValidator()
+                    ->inContext($context)
+                    ->atPath($property)
+                    ->validate($address, [new Assert\NotBlank(), new Assert\Email()]);
+            }
+        }
+    }
+
+    /**
+     * The settings that were sent, by their message data name.
+     *
+     * @return array<string, bool|string|array<int, int>>
+     */
+    public function getDto(): array
+    {
+        return array_filter([
+            'google_track' => $this->googleTrack,
+            'utm_source' => $this->utmSource,
+            'utm_medium' => $this->utmMedium,
+            'utm_campaign' => $this->utmCampaign,
+            'pk_source' => $this->pkSource,
+            'pk_medium' => $this->pkMedium,
+            'pk_campaign' => $this->pkCampaign,
+            'notify_start' => $this->notifyStart,
+            'notify_end' => $this->notifyEnd,
+            // like phplist3, keyed by list id
+            'excludelist' => $this->excludeLists === null
+                ? null
+                : array_combine($this->excludeLists, $this->excludeLists),
+        ], static fn (mixed $value): bool => $value !== null);
+    }
+}