Issue #47 : Glossary implementation

README.md

@@ -187,6 +187,10 @@ try {
 
 See `example/retrieve_supported_languages.php`
 
+#### Working with glossaries
+
+See [use_glossaries.php](example/use_glossaries.php)
+
 ## Testing
 
 ``` bash

example/use_glossaries.php

@@ -0,0 +1,98 @@
+<?php
+
+declare(strict_types=1);
+
+require_once __DIR__ . '/../vendor/autoload.php';
+
+use Scn\DeeplApiConnector\DeeplClientFactory;
+use Scn\DeeplApiConnector\Enum\GlossarySubmissionEntryFormatEnum;
+use Scn\DeeplApiConnector\Model\GlossariesInterface;
+use Scn\DeeplApiConnector\Model\GlossaryEntries;
+use Scn\DeeplApiConnector\Model\GlossaryIdSubmission;
+use Scn\DeeplApiConnector\Model\GlossaryInterface;
+use Scn\DeeplApiConnector\Model\GlossarySubmission;
+use Scn\DeeplApiConnector\Model\GlossariesSupportedLanguagesPairsInterface;
+use Scn\DeeplApiConnector\Model\TranslationConfig;
+
+$apiKey = 'your-api-key';
+
+$deepl = DeeplClientFactory::create($apiKey);
+
+/** @var GlossariesSupportedLanguagesPairsInterface $result */
+$result = $deepl->getGlossariesSupportedLanguagesPairs();
+/**
+ * List all available pairs
+ */
+var_dump($result->getList());
+
+/** @var GlossariesInterface $result */
+$result = $deepl->getGlossariesList();
+/**
+ * List all glossaries
+ */
+var_dump($result->getList());
+
+$input = (new GlossarySubmission())
+    ->setName('en => nl')
+    ->setSourceLang('en')
+    ->setTargetLang('nl')
+    ->setEntries("Hello\tDag\nDog\tHond");
+
+// NB.: Note that entries can be a tsv or csv. Related to the documentation : https://www.deepl.com/fr/docs-api/glossaries/formats
+// To use CSV, this is the example :
+
+$input->setEntriesFormat(GlossarySubmissionEntryFormatEnum::FORMAT_CSV)
+    ->setEntries("Hello,Dag\nDog,Hond");
+/** @var GlossaryInterface $glossary */
+$glossary = $deepl->createGlossary($input);
+/**
+ * Get created glossary
+ */
+var_dump($glossary->getDetails());
+
+$input = (new GlossaryIdSubmission())
+    ->setId($glossary->getDetails()['glossary_id']);
+/** @var GlossaryInterface $result */
+$result = $deepl->retrieveGlossary($input);
+/**
+ * Get glossary details
+ */
+var_dump($result->getDetails());
+
+/** @var GlossaryEntries $result */
+$result = $deepl->retrieveGlossaryEntries($input);
+/**
+ * Get glossary entries array
+ */
+var_dump($result->getList());
+/**
+ * Get glossary entries real result
+ */
+var_dump($result->getResult());
+
+$result = $deepl->deleteGlossary($input);
+/**
+ * True if glossary successfully deleted
+ */
+var_dump($result);
+
+/**
+ * Now, whe can get the glossary from the source and target lang and use it in the TranslationConfig
+ */
+$source = 'en';
+$target = 'nl';
+/** @var GlossariesInterface $glossaries */
+$glossaries = $deepl->getGlossariesList();
+$glossary = current(array_filter(
+    $glossaries->getList(),
+    fn (array $e) => $e['source_lang'] === $source && $e['target_lang'] === $target
+));
+
+$translationConfig = new TranslationConfig(
+    'Hello World',
+    $target,
+    $source,
+    glossaryId: $glossary !== false ? $glossary['glossary_id'] : ''
+);
+$translationObj = $deepl->getTranslation($translationConfig);
+var_dump($translationObj);

src/DeeplClient.php

@@ -12,11 +12,17 @@
 use Scn\DeeplApiConnector\Handler\DeeplRequestHandlerInterface;
 use Scn\DeeplApiConnector\Model\BatchTranslation;
 use Scn\DeeplApiConnector\Model\BatchTranslationConfig;
+use Scn\DeeplApiConnector\Model\GlossaryEntries;
+use Scn\DeeplApiConnector\Model\GlossaryIdSubmission;
+use Scn\DeeplApiConnector\Model\GlossarySubmissionInterface;
 use Scn\DeeplApiConnector\Model\FileSubmission;
 use Scn\DeeplApiConnector\Model\FileSubmissionInterface;
 use Scn\DeeplApiConnector\Model\FileTranslation;
 use Scn\DeeplApiConnector\Model\FileTranslationConfigInterface;
 use Scn\DeeplApiConnector\Model\FileTranslationStatus;
+use Scn\DeeplApiConnector\Model\Glossaries;
+use Scn\DeeplApiConnector\Model\GlossariesSupportedLanguagesPairs;
+use Scn\DeeplApiConnector\Model\Glossary;
 use Scn\DeeplApiConnector\Model\ResponseModelInterface;
 use Scn\DeeplApiConnector\Model\SupportedLanguages;
 use Scn\DeeplApiConnector\Model\Translation;
@@ -128,6 +134,54 @@ public function getSupportedLanguages(): ResponseModelInterface
         );
     }
 
+    public function getGlossariesSupportedLanguagesPairs(): ResponseModelInterface
+    {
+        return (new GlossariesSupportedLanguagesPairs())->hydrate(
+            $this->executeRequest(
+                $this->deeplRequestFactory->createDeeplGlossariesSupportedLanguagesPairsRetrievalRequestHandler()
+            )
+        );
+    }
+
+    public function getGlossariesList(): ResponseModelInterface
+    {
+        return (new Glossaries())->hydrate(
+            $this->executeRequest(
+                $this->deeplRequestFactory->createDeeplGlossariesListRetrievalRequestHandler()
+            )
+        );
+    }
+
+    public function createGlossary(GlossarySubmissionInterface $submission): ResponseModelInterface
+    {
+        return (new Glossary())->hydrate($this->executeRequest(
+            $this->deeplRequestFactory->createDeeplGlossaryCreateRequestHandler($submission)
+        ));
+    }
+
+    public function retrieveGlossary(GlossaryIdSubmission $submission): ResponseModelInterface
+    {
+        return (new Glossary())->hydrate($this->executeRequest(
+            $this->deeplRequestFactory->createDeeplGlossaryRetrieveRequestHandler($submission)
+        ));
+    }
+
+    public function deleteGlossary(GlossaryIdSubmission $submission): bool
+    {
+        $this->executeRequest(
+            $this->deeplRequestFactory->createDeeplGlossaryDeleteRequestHandler($submission)
+        );
+
+        return true;
+    }
+
+    public function retrieveGlossaryEntries(GlossaryIdSubmission $submission): ResponseModelInterface
+    {
+        return (new GlossaryEntries())->hydrate($this->executeRequest(
+            $this->deeplRequestFactory->createDeeplGlossaryEntriesRetrieveRequestHandler($submission)
+        ));
+    }
+
     /**
      * Execute given RequestHandler Request and returns decoded Json Object or throws Exception with Error Code
      * and maybe given Error Message.
@@ -148,6 +202,14 @@ private function executeRequest(DeeplRequestHandlerInterface $requestHandler): s
             )
             ->withBody($requestHandler->getBody());
 
+        if ($requestHandler->getAuthHeader() !== null) {
+            $request = $request->withHeader('Authorization', $requestHandler->getAuthHeader());
+        }
+
+        if ($requestHandler->getAcceptHeader() !== null) {
+            $request = $request->withHeader('Accept', $requestHandler->getAcceptHeader());
+        }
+
         try {
             $response = $this->httpClient->sendRequest($request);
         } catch (ClientExceptionInterface $exception) {

src/DeeplClientInterface.php

@@ -5,6 +5,8 @@
 use Scn\DeeplApiConnector\Enum\LanguageEnum;
 use Scn\DeeplApiConnector\Model\FileSubmissionInterface;
 use Scn\DeeplApiConnector\Model\FileTranslationConfigInterface;
+use Scn\DeeplApiConnector\Model\GlossaryIdSubmission;
+use Scn\DeeplApiConnector\Model\GlossarySubmissionInterface;
 use Scn\DeeplApiConnector\Model\ResponseModelInterface;
 use Scn\DeeplApiConnector\Model\TranslationConfigInterface;
 
@@ -59,4 +61,34 @@ public function getFileTranslation(FileSubmissionInterface $fileSubmission): Res
      * Returns list of supported languages
      */
     public function getSupportedLanguages(): ResponseModelInterface;
+
+    /**
+     * Returns list of supported languages pairs for glossaries
+     */
+    public function getGlossariesSupportedLanguagesPairs(): ResponseModelInterface;
+
+    /**
+     * Returns list of glossaries
+     */
+    public function getGlossariesList(): ResponseModelInterface;
+
+    /**
+     * Create a glossary and return glossary object
+     */
+    public function createGlossary(GlossarySubmissionInterface $submission): ResponseModelInterface;
+
+    /**
+     * Returns a glossary using id
+     */
+    public function retrieveGlossary(GlossaryIdSubmission $submission): ResponseModelInterface;
+
+    /**
+     * Delete a glossary using id
+     */
+    public function deleteGlossary(GlossaryIdSubmission $submission): bool;
+
+    /**
+     * Returns list of entries
+     */
+    public function retrieveGlossaryEntries(GlossaryIdSubmission $submission): ResponseModelInterface;
 }

src/Enum/GlossarySubmissionEntryFormatEnum.php

@@ -0,0 +1,11 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scn\DeeplApiConnector\Enum;
+
+final class GlossarySubmissionEntryFormatEnum
+{
+    public const FORMAT_TSV = 'tsv';
+    public const FORMAT_CSV = 'csv';
+}

src/Handler/AbstractDeeplHandler.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scn\DeeplApiConnector\Handler;
+
+abstract class AbstractDeeplHandler implements DeeplRequestHandlerInterface
+{
+    public function getAuthHeader(): ?string
+    {
+        return null;
+    }
+
+    public function getAcceptHeader(): ?string
+    {
+        return null;
+    }
+}

src/Handler/DeeplBatchTranslationRequestHandler.php

@@ -11,7 +11,7 @@
 /**
  * Builds the request body for batch translations
  */
-final class DeeplBatchTranslationRequestHandler implements DeeplRequestHandlerInterface
+final class DeeplBatchTranslationRequestHandler extends AbstractDeeplHandler
 {
     private const SEPARATOR = ',';
     public const API_ENDPOINT = '/v2/translate';
@@ -59,6 +59,7 @@ public function getBody(): StreamInterface
                     'ignore_tags' => implode(static::SEPARATOR, $this->translation->getIgnoreTags()),
                     'split_sentences' => $this->translation->getSplitSentences(),
                     'preserve_formatting' => $this->translation->getPreserveFormatting(),
+                    'glossary_id' => $this->translation->getGlossaryId(),
                     'auth_key' => $this->authKey,
                 ]
             )

src/Handler/DeeplFileRequestHandler.php

@@ -1,12 +1,14 @@
 <?php
 
+declare(strict_types=1);
+
 namespace Scn\DeeplApiConnector\Handler;
 
 use Psr\Http\Message\StreamFactoryInterface;
 use Psr\Http\Message\StreamInterface;
 use Scn\DeeplApiConnector\Model\FileSubmissionInterface;
 
-final class DeeplFileRequestHandler implements DeeplRequestHandlerInterface
+final class DeeplFileRequestHandler extends AbstractDeeplHandler
 {
     public const API_ENDPOINT = '/v2/document/%s/result';
 

src/Handler/DeeplFileSubmissionRequestHandler.php

@@ -8,7 +8,7 @@
 use Psr\Http\Message\StreamInterface;
 use Scn\DeeplApiConnector\Model\FileTranslationConfigInterface;
 
-final class DeeplFileSubmissionRequestHandler implements DeeplRequestHandlerInterface
+final class DeeplFileSubmissionRequestHandler extends AbstractDeeplHandler
 {
     public const API_ENDPOINT = '/v2/document';
 

src/Handler/DeeplFileTranslationStatusRequestHandler.php

@@ -8,7 +8,7 @@
 use Psr\Http\Message\StreamInterface;
 use Scn\DeeplApiConnector\Model\FileSubmissionInterface;
 
-final class DeeplFileTranslationStatusRequestHandler implements DeeplRequestHandlerInterface
+final class DeeplFileTranslationStatusRequestHandler extends AbstractDeeplHandler
 {
     public const API_ENDPOINT = '/v2/document/%s';
 

src/Handler/DeeplGlossariesListRetrievalRequestHandler.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Scn\DeeplApiConnector\Handler;
+
+use Psr\Http\Message\StreamFactoryInterface;
+use Psr\Http\Message\StreamInterface;
+
+final class DeeplGlossariesListRetrievalRequestHandler extends AbstractDeeplHandler
+{
+    public const API_ENDPOINT = '/v2/glossaries';
+
+    private string $authKey;
+
+    private StreamFactoryInterface $streamFactory;
+
+    public function __construct(
+        string $authKey,
+        StreamFactoryInterface $streamFactory
+    ) {
+        $this->authKey = $authKey;
+        $this->streamFactory = $streamFactory;
+    }
+
+    public function getMethod(): string
+    {
+        return DeeplRequestHandlerInterface::METHOD_GET;
+    }
+
+    public function getPath(): string
+    {
+        return static::API_ENDPOINT;
+    }
+
+    public function getBody(): StreamInterface
+    {
+        return $this->streamFactory->createStream();
+    }
+
+    public function getAuthHeader(): ?string
+    {
+        return sprintf('DeepL-Auth-Key %s', $this->authKey);
+    }
+
+    public function getContentType(): string
+    {
+        return 'application/x-www-form-urlencoded';
+    }
+}