Introduce typed DTOs and sub-namespaces for Micropub handlers

Each handler now declares the data class it needs via dataClass(). The
controller builds the appropriate typed DTO from the raw request array
before calling handle(), giving handlers typed property access instead
of raw array lookups.

Handlers moved to App\Services\Micropub\Handlers, data objects to
App\Services\Micropub\Data. MicropubHandlerRegistry and the interface
are documented with flow diagrams and guidance for adding new types.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app/Services/Micropub/Handlers/CardHandler.php

@@ -0,0 +1,42 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Micropub\Handlers;
+
+use App\Exceptions\InvalidTokenScopeException;
+use App\Services\Micropub\Data\CardData;
+use App\Services\Micropub\Data\MicropubData;
+use App\Services\PlaceService;
+
+class CardHandler implements MicropubHandlerInterface
+{
+    public function dataClass(): string
+    {
+        return CardData::class;
+    }
+
+    /**
+     * @throws InvalidTokenScopeException
+     */
+    public function handle(MicropubData $data): array
+    {
+        assert($data instanceof CardData);
+
+        $scopes = $data->tokenData['scope'];
+        if (is_string($scopes)) {
+            $scopes = explode(' ', $scopes);
+        }
+
+        if (! in_array('create', $scopes, true)) {
+            throw new InvalidTokenScopeException;
+        }
+
+        $location = resolve(PlaceService::class)->createPlace($data->toArray())->uri;
+
+        return [
+            'response' => 'created',
+            'url' => $location,
+        ];
+    }
+}

app/Services/Micropub/Handlers/EntryHandler.php

@@ -0,0 +1,51 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Micropub\Handlers;
+
+use App\Exceptions\InvalidTokenScopeException;
+use App\Services\ArticleService;
+use App\Services\BookmarkService;
+use App\Services\LikeService;
+use App\Services\Micropub\Data\EntryData;
+use App\Services\Micropub\Data\MicropubData;
+use App\Services\NoteService;
+
+class EntryHandler implements MicropubHandlerInterface
+{
+    public function dataClass(): string
+    {
+        return EntryData::class;
+    }
+
+    /**
+     * @throws InvalidTokenScopeException
+     */
+    public function handle(MicropubData $data): array
+    {
+        assert($data instanceof EntryData);
+
+        $scopes = $data->tokenData['scope'];
+        if (is_string($scopes)) {
+            $scopes = explode(' ', $scopes);
+        }
+
+        if (! in_array('create', $scopes, true)) {
+            throw new InvalidTokenScopeException;
+        }
+
+        $dataArray = $data->toArray();
+        $location = match (true) {
+            isset($dataArray['like-of']) => resolve(LikeService::class)->create($dataArray)->url,
+            isset($dataArray['bookmark-of']) => resolve(BookmarkService::class)->create($dataArray)->uri,
+            isset($dataArray['name']) => resolve(ArticleService::class)->create($dataArray)->link,
+            default => resolve(NoteService::class)->create($dataArray)->uri,
+        };
+
+        return [
+            'response' => 'created',
+            'url' => $location,
+        ];
+    }
+}

app/Services/Micropub/Handlers/MicropubHandlerInterface.php

@@ -0,0 +1,44 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Micropub\Handlers;
+
+use App\Services\Micropub\Data\MicropubData;
+
+/**
+ * Contract for all Micropub request handlers.
+ *
+ * The Micropub endpoint receives different types of request — creating an
+ * h-entry (note, article, bookmark, like), creating an h-card (place), or
+ * updating an existing post. Each type is handled by its own class that
+ * implements this interface.
+ *
+ * Each handler declares the typed data object it needs via dataClass(). The
+ * controller calls dataClass()::fromArray() to build the right object before
+ * passing it to handle(), so the handler always receives a concrete typed
+ * object rather than a raw array.
+ *
+ * Handlers live in App\Services\Micropub\Handlers.
+ * Their corresponding data objects live in App\Services\Micropub\Data.
+ * Handlers are registered in MicropubServiceProvider and looked up by type
+ * string (e.g. "entry", "card", "update") via MicropubHandlerRegistry.
+ */
+interface MicropubHandlerInterface
+{
+    /**
+     * Return the fully-qualified class name of the data object this handler
+     * expects. The controller will call fromArray() on this class to build the
+     * object from the normalised request data before calling handle().
+     *
+     * @return class-string<MicropubData>
+     */
+    public function dataClass(): string;
+
+    /**
+     * Process the request and return a result array with at minimum a
+     * 'response' key ('created' or 'updated') and a 'url' key pointing to
+     * the affected resource.
+     */
+    public function handle(MicropubData $data): array;
+}

app/Services/Micropub/Handlers/UpdateHandler.php

@@ -0,0 +1,106 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Services\Micropub\Handlers;
+
+use App\Exceptions\InvalidTokenScopeException;
+use App\Exceptions\MicropubHandlerException;
+use App\Exceptions\MicropubUnsupportedModelException;
+use App\Models\Media;
+use App\Models\Note;
+use App\Services\Micropub\Data\MicropubData;
+use App\Services\Micropub\Data\UpdateData;
+use Illuminate\Support\Str;
+
+class UpdateHandler implements MicropubHandlerInterface
+{
+    public function dataClass(): string
+    {
+        return UpdateData::class;
+    }
+
+    /**
+     * @throws InvalidTokenScopeException
+     * @throws MicropubUnsupportedModelException
+     * @throws MicropubHandlerException
+     */
+    public function handle(MicropubData $data): array
+    {
+        assert($data instanceof UpdateData);
+
+        $scopes = $data->tokenData['scope'];
+        if (is_string($scopes)) {
+            $scopes = explode(' ', $scopes);
+        }
+
+        if (! in_array('update', $scopes, true)) {
+            throw new InvalidTokenScopeException;
+        }
+
+        $urlPath = parse_url($data->updateUrl, PHP_URL_PATH);
+
+        if (mb_substr($urlPath, 1, 5) !== 'notes') {
+            throw new MicropubUnsupportedModelException('This implementation currently only supports the updating of notes');
+        }
+
+        $note = Note::nb60(basename($urlPath))->firstOrFail();
+
+        if ($data->updateReplace !== null) {
+            foreach ($data->updateReplace as $property => $value) {
+                if ($property === 'content') {
+                    $note->note = $value[0];
+                }
+                if ($property === 'syndication') {
+                    $this->applySyndication($note, $value);
+                }
+            }
+            $note->save();
+
+            return [
+                'response' => 'updated',
+                'url' => $note->uri,
+            ];
+        }
+
+        if ($data->updateAdd !== null) {
+            foreach ($data->updateAdd as $property => $value) {
+                if ($property === 'syndication') {
+                    $this->applySyndication($note, $value);
+                }
+                if ($property === 'photo') {
+                    foreach ($value as $photoURL) {
+                        if (Str::startsWith($photoURL, 'https://')) {
+                            $media = new Media;
+                            $media->path = $photoURL;
+                            $media->type = 'image';
+                            $media->save();
+                            $note->media()->save($media);
+                        }
+                    }
+                }
+            }
+            $note->save();
+
+            return [
+                'response' => 'updated',
+                'url' => $note->uri,
+            ];
+        }
+
+        throw new MicropubHandlerException('Unsupported update operation');
+    }
+
+    private function applySyndication(Note $note, array $urls): void
+    {
+        foreach ($urls as $url) {
+            if (Str::startsWith($url, 'https://www.facebook.com')) {
+                $note->facebook_url = $url;
+            } elseif (Str::startsWith($url, 'https://www.swarmapp.com')) {
+                $note->swarm_url = $url;
+            } elseif (Str::startsWith($url, 'https://twitter.com')) {
+                $note->tweet_id = basename(parse_url($url, PHP_URL_PATH));
+            }
+        }
+    }
+}