feat: add support for plex new nfo agent

arabcoders · arabcoders · commit 18f3bafcb993 · 2026-04-27T22:17:17.000+03:00
diff --git a/FAQ.md b/FAQ.md
@@ -258,21 +258,23 @@ If there are no errors, the database has been repaired successfully. And you can
 
 # Which Providers id `GUIDs` supported by for PlexClient?
 
-* tvdb://(id) `New plex agent`
-* imdb://(id) `New plex agent`
-* tmdb://(id) `New plex agent`
-* com.plexapp.agents.imdb://(id)?lang=en `(Legacy plex agent)`
-* com.plexapp.agents.tmdb://(id)?lang=en `(Legacy plex agent)`
-* com.plexapp.agents.themoviedb://(id)?lang=en `(Legacy plex agent)`
-* com.plexapp.agents.thetvdb://(seriesId)?lang=en `(Legacy plex agent)`
-* com.plexapp.agents.xbmcnfo://(id)?lang=en `(XBMC NFO Movies agent)`
-* com.plexapp.agents.xbmcnfotv://(id)?lang=en `(XBMC NFO TV agent)`
+* tvdb://(id)
+* imdb://(id)
+* tmdb://(id)
+* tv.plex.agents.nfo.movie://movie/(provider)_(id) `Where the provider one of supported providers`
+* tv.plex.agents.nfo.series://(show|episode)/(provider)_(id) `Where the provider one of supported providers`
+  
+## Legacy Plex Agents
+
+* com.plexapp.agents.imdb://(id)?lang=en
+* com.plexapp.agents.tmdb://(id)?lang=en
+* com.plexapp.agents.themoviedb://(id)?lang=en
+* com.plexapp.agents.thetvdb://(seriesId)?lang=en
+* com.plexapp.agents.xbmcnfo://(id)?lang=en `(XBMC NFO Movies agent) -> imdb|tmdb://(movieId)?lang=en`
+* com.plexapp.agents.xbmcnfotv://(id)?lang=en `(XBMC NFO TV agent) -> tvdb://(serisId)?lang=en`
 * com.plexapp.agents.hama://(db)\d?-(id)?lang=en `(HAMA multi source db agent mainly for anime)`
-* com.plexapp.agents.ytinforeader://(id)
-  ?lang=en [ytinforeader.bundle](https://github.com/arabcoders/plex-ytdlp-info-reader-agent)
-  With [jp_scanner.py](https://github.com/arabcoders/plex-daily-scanner) as scanner.
-* com.plexapp.agents.cmdb://(id)
-  ?lang=en [cmdb.bundle](https://github.com/arabcoders/cmdb.bundle) `(User custom metadata database)`.
+* com.plexapp.agents.ytinforeader://(id)?lang=en [ytinforeader.bundle](https://github.com/arabcoders/plex-ytdlp-info-reader-agent) With [jp_scanner.py](https://github.com/arabcoders/plex-daily-scanner) as scanner.
+* com.plexapp.agents.cmdb://(id)?lang=en [cmdb.bundle](https://github.com/arabcoders/cmdb.bundle) `(User custom metadata database)`.
 
 ---
 
diff --git a/src/Backends/Plex/PlexClient.php b/src/Backends/Plex/PlexClient.php
@@ -105,6 +105,8 @@ class PlexClient implements iClient
         'com.plexapp.agents.cmdb',
         'tv.plex.agents.movie',
         'tv.plex.agents.series',
+        'tv.plex.agents.nfo.movie',
+        'tv.plex.agents.nfo.series',
     ];
 
     /**
diff --git a/src/Backends/Plex/PlexGuid.php b/src/Backends/Plex/PlexGuid.php
@@ -45,6 +45,14 @@ final class PlexGuid implements iGuid
         'com.plexapp.agents.cmdb',
     ];
 
+    /**
+     * @var array<array-key,string> List of native plex NFO agents.
+     */
+    private array $guidNfo = [
+        'tv.plex.agents.nfo.movie',
+        'tv.plex.agents.nfo.series',
+    ];
+
     /**
      * @var array<array-key,string> List of local plex agents.
      */
@@ -359,6 +367,10 @@ private function ListExternalIds(array $guids, array $context = [], bool $log =
                     $val = $this->parseLegacyAgent(guid: $val, context: $context, log: $log);
                 }
 
+                if (true === str_starts_with($val, 'tv.plex.agents.nfo.')) {
+                    $val = $this->parseNfoAgent(guid: $val, context: $context, log: $log);
+                }
+
                 if (false === str_contains($val, '://')) {
                     if (true === $log) {
                         $this->logger->info("PlexGuid: Unable to parse '{backend}: {agent}' identifier.", [
@@ -398,6 +410,10 @@ private function ListExternalIds(array $guids, array $context = [], bool $log =
 
                 // -- Plex in their infinite wisdom, sometimes report two keys for same data source.
                 if (null !== ($guid[$this->guidMapper[$key]] ?? null)) {
+                    if ($guid[$this->guidMapper[$key]] === $value) {
+                        continue;
+                    }
+
                     if (true === $log) {
                         $this->logger->warning(
                             "PlexGuid: '{client}: {backend}' reported multiple ids for same data source '{key}: {ids}' for {item.type} '{item.id}: {item.title}'.",
@@ -514,6 +530,74 @@ private function parseLegacyAgent(string $guid, array $context = [], bool $log =
         }
     }
 
+    /**
+     * Parse native Plex NFO agents.
+     *
+     * Typed NFO GUIDs include the source in the last path segment, such as
+     * `tv.plex.agents.nfo.movie://movie/tmdb_383498`. We normalize those to the
+     * same `<source>://<id>` format the rest of the parser already understands.
+     * Fallback NFO ids like `...://movie/858024` do not identify the source and
+     * are intentionally left untouched.
+     *
+     * @param string $guid Guid to parse.
+     * @param array $context Context data.
+     * @param bool $log Log errors. default true.
+     *
+     * @return string The parsed GUID.
+     */
+    private function parseNfoAgent(string $guid, array $context = [], bool $log = true): string
+    {
+        if (false === in_array(before($guid, '://'), $this->guidNfo, true)) {
+            return $guid;
+        }
+
+        try {
+            $payload = after($guid, '://');
+            $token = trim((string) basename($payload));
+
+            if ('' === $token || false === str_contains($token, '_')) {
+                return $guid;
+            }
+
+            [$source, $sourceId] = explode('_', $token, 2);
+            $source = strtolower(trim($source));
+            $sourceId = trim($sourceId);
+
+            if ('' === $source || '' === $sourceId || null === ($this->guidMapper[$source] ?? null)) {
+                return $guid;
+            }
+
+            return $source . '://' . before($sourceId, '?');
+        } catch (Throwable $e) {
+            if (true === $log) {
+                $this->logger->error(
+                    message: "PlexGuid: Exception '{error.kind}' was thrown unhandled during '{client}: {backend}' parsing NFO agent '{agent}' identifier. Error '{error.message}' at '{error.file}:{error.line}.",
+                    context: [
+                        'backend' => $this->context->backendName,
+                        'client' => $this->context->clientName,
+                        'error' => [
+                            'kind' => $e::class,
+                            'line' => $e->getLine(),
+                            'message' => $e->getMessage(),
+                            'file' => after($e->getFile(), ROOT_PATH),
+                        ],
+                        'agent' => $guid,
+                        'exception' => [
+                            'file' => $e->getFile(),
+                            'line' => $e->getLine(),
+                            'kind' => get_class($e),
+                            'message' => $e->getMessage(),
+                            'trace' => $e->getTrace(),
+                        ],
+                        ...$context,
+                    ],
+                );
+            }
+
+            return $guid;
+        }
+    }
+
     /**
      * Get the Plex Guid configuration.
      *
@@ -524,6 +608,7 @@ public function getConfig(): array
         return [
             'guidMapper' => $this->guidMapper,
             'guidLegacy' => $this->guidLegacy,
+            'guidNfo' => $this->guidNfo,
             'guidLocal' => $this->guidLocal,
             'guidReplacer' => $this->guidReplacer,
         ];
diff --git a/tests/Backends/Plex/GetLibrariesListTest.php b/tests/Backends/Plex/GetLibrariesListTest.php
@@ -152,4 +152,37 @@ public function test_401_response_with_invalid_token(): void
         $this->assertNull($response->response);
         $this->assertTrue($response->error->hasException());
     }
+
+    public function test_nfo_agents_are_supported(): void
+    {
+        $payload = [
+            'MediaContainer' => [
+                'Directory' => [
+                    [
+                        'key' => '1',
+                        'title' => 'NFO Movies',
+                        'type' => 'movie',
+                        'agent' => 'tv.plex.agents.nfo.movie',
+                        'scanner' => 'Plex Movie Scanner',
+                    ],
+                    [
+                        'key' => '2',
+                        'title' => 'NFO Shows',
+                        'type' => 'show',
+                        'agent' => 'tv.plex.agents.nfo.series',
+                        'scanner' => 'Plex TV Series',
+                    ],
+                ],
+            ],
+        ];
+
+        $resp = new MockResponse(json_encode($payload), ['http_code' => 200]);
+        $client = new MockHttpClient($resp);
+        $response = new GetLibrariesList($client, $this->logger)($this->context);
+
+        $this->assertTrue($response->status);
+        $this->assertCount(2, $response->response);
+        $this->assertTrue((bool) $response->response[0]['supported']);
+        $this->assertTrue((bool) $response->response[1]['supported']);
+    }
 }
diff --git a/tests/Backends/Plex/ImportTest.php b/tests/Backends/Plex/ImportTest.php
@@ -98,4 +98,43 @@ public function test_import_empty_libraries(): void
         $this->assertTrue($result->isSuccessful());
         $this->assertSame([], $result->response);
     }
+
+    public function test_import_nfo_library_select_includes_selected(): void
+    {
+        $sections = [
+            'MediaContainer' => [
+                'Directory' => [
+                    [
+                        'key' => '5',
+                        'title' => 'NFO Movies',
+                        'type' => 'movie',
+                        'agent' => 'tv.plex.agents.nfo.movie',
+                    ],
+                ],
+            ],
+        ];
+
+        $http = $this->makeHttpClient(
+            $this->makeResponse($sections),
+            new MockResponse('', [
+                'http_code' => 200,
+                'response_headers' => ['X-Plex-Container-Total-Size' => '1'],
+            ]),
+        );
+        $context = $this->makeContext([Options::LIBRARY_SELECT => ['5']]);
+        $action = new Import($http, $this->logger);
+
+        $result = $action(
+            $context,
+            new PlexGuid($this->logger),
+            $context->userContext->mapper,
+            null,
+            [],
+        );
+
+        $this->assertTrue($result->isSuccessful());
+        $this->assertCount(1, $result->response);
+        $logContext = $result->response[0]->extras['logContext'] ?? [];
+        $this->assertSame(5, (int) ag($logContext, 'library.id'));
+    }
 }
diff --git a/tests/Backends/Plex/PlexGuidTest.php b/tests/Backends/Plex/PlexGuidTest.php
@@ -351,6 +351,11 @@ public function test_isLocal()
             $this->getClass()->isLocal('com.plexapp.agents.imdb://123456/1/1'),
             'Assert that the GUID is not local.'
         );
+
+        $this->assertFalse(
+            $this->getClass()->isLocal('tv.plex.agents.nfo.movie://movie/tmdb_383498'),
+            'Assert that typed NFO GUIDs are treated as non-local external ids.'
+        );
     }
 
     public function test_has()
@@ -392,10 +397,23 @@ public function test_parse()
             ], $context),
             'Assert that the GUID exists.');
 
+        $this->assertEquals([
+            Guid::GUID_IMDB => 'tt1234567',
+            Guid::GUID_TMDB => '383498',
+            Guid::GUID_TVDB => '121361',
+        ],
+            $this->getClass()->parse([
+                ['id' => 'tv.plex.agents.nfo.movie://movie/tmdb_383498'],
+                ['id' => 'tv.plex.agents.nfo.movie://movie/imdb_tt1234567'],
+                ['id' => 'tv.plex.agents.nfo.series://show/tvdb_121361'],
+            ], $context),
+            'Assert that typed NFO GUIDs are normalized into supported external ids.');
+
         $this->assertEquals([], $this->getClass()->parse([
             ['id' => ''],
             ['id' => 'com.plexapp.agents.none://123456'],
             ['id' => 'com.plexapp.agents.imdb'],
+            ['id' => 'tv.plex.agents.nfo.movie://movie/858024'],
         ], $context), 'Assert that the GUID does not exist. for invalid GUIDs.');
     }
 
@@ -434,6 +452,16 @@ public function test_get()
             ['id' => 'com.plexapp.agents.imdb://2'],
         ], $context), 'Assert only the the oldest ID is returned for numeric GUIDs.');
 
+        $this->assertEquals([Guid::GUID_TVDB => '84871'], $this->getClass()->get([
+            ['id' => 'tvdb://84871'],
+            ['id' => 'tv.plex.agents.nfo.series://episode/tvdb_84871'],
+        ], $context), 'Assert typed NFO GUIDs do not conflict with identical canonical GUIDs.');
+
+        $this->assertFalse(
+            $this->logged(Level::Warning, 'reported multiple ids', true),
+            'Assert identical canonical and NFO GUIDs do not raise duplicate warnings.'
+        );
+
         // -- as we cache the ignore list for each user now,
         // -- and no longer rely on config.ignore key, we needed a workaround to update the ignore list
         is_ignored_id(
diff --git a/tests/Backends/Plex/ToEntityTest.php b/tests/Backends/Plex/ToEntityTest.php
@@ -77,4 +77,72 @@ public function __invoke(\App\Backends\Common\Context $context, string|int $id,
         $this->assertInstanceOf(StateInterface::class, $result->response);
         $this->assertNotEmpty($result->response->parent);
     }
+
+    public function test_to_entity_uses_top_level_typed_nfo_guid(): void
+    {
+        $context = $this->makeContext();
+        $item = [
+            'ratingKey' => '42',
+            'type' => 'movie',
+            'title' => 'NFO Movie',
+            'addedAt' => 1000,
+            'guid' => 'tv.plex.agents.nfo.movie://movie/tmdb_383498',
+        ];
+
+        $action = new ToEntity(new PlexGuid($this->logger));
+        $result = $action($context, $item);
+
+        $this->assertTrue($result->isSuccessful());
+        $this->assertInstanceOf(StateInterface::class, $result->response);
+        $this->assertSame('383498', $result->response->guids['guid_tmdb'] ?? null);
+    }
+
+    public function test_to_entity_episode_uses_show_level_typed_nfo_guid_when_parent_has_no_guid_list(): void
+    {
+        $context = $this->makeContext();
+        $item = [
+            'ratingKey' => '11',
+            'type' => 'episode',
+            'title' => 'Pilot',
+            'grandparentTitle' => 'Test Show',
+            'parentIndex' => 1,
+            'index' => 1,
+            'addedAt' => 1000,
+            'Guid' => [
+                ['id' => 'tvdb://84871'],
+            ],
+            'grandparentRatingKey' => 'show-1',
+        ];
+
+        $showPayload = [
+            'MediaContainer' => [
+                'Metadata' => [
+                    [
+                        'ratingKey' => 'show-1',
+                        'type' => 'show',
+                        'title' => 'Test Show',
+                        'guid' => 'tv.plex.agents.nfo.series://show/tvdb_72408',
+                    ],
+                ],
+            ],
+        ];
+
+        Container::add(GetMetaData::class, fn() => new class($showPayload) {
+            public function __construct(private array $payload)
+            {
+            }
+
+            public function __invoke(\App\Backends\Common\Context $context, string|int $id, array $opts = []): Response
+            {
+                return new Response(status: true, response: $this->payload);
+            }
+        });
+
+        $action = new ToEntity(new PlexGuid($this->logger));
+        $result = $action($context, $item);
+
+        $this->assertTrue($result->isSuccessful());
+        $this->assertInstanceOf(StateInterface::class, $result->response);
+        $this->assertSame('72408', $result->response->parent['guid_tvdb'] ?? null);
+    }
 }
