feat: Add File References API support

EXAMPLES.md

@@ -7,6 +7,7 @@
 - [Export and download TM](#export-and-download-tm)
 - [Create and upload glossary](#create-and-upload-glossary)
 - [Export and download glossary](#export-and-download-glossary)
+
 
 ---
 
@@ -160,3 +161,5 @@ $tbxFile = $crowdin->glossary->download($glossaryId, $glossaryExport->getIdentif
 
 print_r($tbxFile->getData());
 ```
+
+

phpunit.xml

@@ -8,7 +8,7 @@
          convertErrorsToExceptions="true"
          convertNoticesToExceptions="true"
          convertWarningsToExceptions="true"
-         convertDeprecationsToExceptions="true"
+        convertDeprecationsToExceptions="false"
          processIsolation="false"
          stopOnFailure="false">
     <coverage processUncoveredFiles="true">

src/CrowdinApiClient/Api/FileApi.php

@@ -5,6 +5,7 @@
 use CrowdinApiClient\Model\DownloadFile;
 use CrowdinApiClient\Model\DownloadFilePreview;
 use CrowdinApiClient\Model\File;
+use CrowdinApiClient\Model\FileReference;
 use CrowdinApiClient\Model\FileRevision;
 use CrowdinApiClient\ModelCollection;
 
@@ -196,4 +197,73 @@ public function getRevision(int $projectId, int $fileId, int $revision): ?FileRe
         $path = sprintf('projects/%d/files/%d/revisions/%d', $projectId, $fileId, $revision);
         return $this->_get($path, FileRevision::class);
     }
+
+    /**
+     * List File References
+     * @link https://support.crowdin.com/developer/api/v2/#operation/api.projects.files.references.getMany API Documentation
+     * @link https://support.crowdin.com/developer/api/v2/#operation/api.projects.files.references.getMany API Documentation Enterprise
+     *
+     * @param int $projectId
+     * @param int $fileId
+     * @param array $params
+     * integer $params[limit]<br>
+     * integer $params[offset]
+     * @return ModelCollection
+     */
+    public function listReferences(int $projectId, int $fileId, array $params = []): ModelCollection
+    {
+        $path = sprintf('projects/%d/files/%d/references', $projectId, $fileId);
+        return $this->_list($path, FileReference::class, $params);
+    }
+
+    /**
+     * Get File Reference
+     * @link https://support.crowdin.com/developer/api/v2/#operation/api.projects.files.references.get API Documentation
+     * @link https://support.crowdin.com/developer/api/v2/#operation/api.projects.files.references.get API Documentation Enterprise
+     *
+     * @param int $projectId
+     * @param int $fileId
+     * @param int $referenceId
+     * @return FileReference|null
+     */
+    public function getReference(int $projectId, int $fileId, int $referenceId): ?FileReference
+    {
+        $path = sprintf('projects/%d/files/%d/references/%d', $projectId, $fileId, $referenceId);
+        return $this->_get($path, FileReference::class);
+    }
+
+    /**
+     * Add File Reference
+     * @link https://support.crowdin.com/developer/api/v2/#operation/api.projects.files.references.post API Documentation
+     * @link https://support.crowdin.com/developer/api/v2/#operation/api.projects.files.references.post API Documentation Enterprise
+     *
+     * @param int $projectId
+     * @param int $fileId
+     * @param array $data
+     * string $data[name] required<br>
+     * string $data[type] required<br>
+     * string $data[url] required
+     * @return FileReference
+     */
+    public function addReference(int $projectId, int $fileId, array $data): FileReference
+    {
+        $path = sprintf('projects/%d/files/%d/references', $projectId, $fileId);
+        return $this->_create($path, FileReference::class, $data);
+    }
+
+    /**
+     * Delete File Reference
+     * @link https://support.crowdin.com/developer/api/v2/#operation/api.projects.files.references.delete API Documentation
+     * @link https://support.crowdin.com/developer/api/v2/#operation/api.projects.files.references.delete API Documentation Enterprise
+     *
+     * @param int $projectId
+     * @param int $fileId
+     * @param int $referenceId
+     * @return mixed
+     */
+    public function deleteReference(int $projectId, int $fileId, int $referenceId)
+    {
+        $path = sprintf('projects/%d/files/%d/references/%d', $projectId, $fileId, $referenceId);
+        return $this->_delete($path);
+    }
 }

src/CrowdinApiClient/Model/FileReference.php

@@ -0,0 +1,170 @@
+<?php
+
+namespace CrowdinApiClient\Model;
+
+/**
+ * @package Crowdin\Model
+ */
+class FileReference extends BaseModel
+{
+    /**
+     * @var integer
+     */
+    protected $id;
+
+    /**
+     * @var integer
+     */
+    protected $projectId;
+
+    /**
+     * @var integer
+     */
+    protected $fileId;
+
+    /**
+     * @var string
+     */
+    protected $name;
+
+    /**
+     * @var string
+     */
+    protected $type;
+
+    /**
+     * @var string
+     */
+    protected $url;
+
+    /**
+     * @var string
+     */
+    protected $createdAt;
+
+    /**
+     * @var string
+     */
+    protected $updatedAt;
+
+    /**
+     * FileReference constructor.
+     * @param array $data
+     */
+    public function __construct(array $data = [])
+    {
+        parent::__construct($data);
+        $this->id = (integer)$this->getDataProperty('id');
+        $this->projectId = (integer)$this->getDataProperty('projectId');
+        $this->fileId = (integer)$this->getDataProperty('fileId');
+        $this->name = (string)$this->getDataProperty('name');
+        $this->type = (string)$this->getDataProperty('type');
+        $this->url = (string)$this->getDataProperty('url');
+        $this->createdAt = (string)$this->getDataProperty('createdAt');
+        $this->updatedAt = (string)$this->getDataProperty('updatedAt');
+    }
+
+    /**
+     * @return int
+     */
+    public function getId(): int
+    {
+        return $this->id;
+    }
+
+    /**
+     * @return int
+     */
+    public function getProjectId(): int
+    {
+        return $this->projectId;
+    }
+
+    /**
+     * @param int $projectId
+     */
+    public function setProjectId(int $projectId): void
+    {
+        $this->projectId = $projectId;
+    }
+
+    /**
+     * @return int
+     */
+    public function getFileId(): int
+    {
+        return $this->fileId;
+    }
+
+    /**
+     * @param int $fileId
+     */
+    public function setFileId(int $fileId): void
+    {
+        $this->fileId = $fileId;
+    }
+
+    /**
+     * @return string
+     */
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    /**
+     * @param string $name
+     */
+    public function setName(string $name): void
+    {
+        $this->name = $name;
+    }
+
+    /**
+     * @return string
+     */
+    public function getType(): string
+    {
+        return $this->type;
+    }
+
+    /**
+     * @param string $type
+     */
+    public function setType(string $type): void
+    {
+        $this->type = $type;
+    }
+
+    /**
+     * @return string
+     */
+    public function getUrl(): string
+    {
+        return $this->url;
+    }
+
+    /**
+     * @param string $url
+     */
+    public function setUrl(string $url): void
+    {
+        $this->url = $url;
+    }
+
+    /**
+     * @return string
+     */
+    public function getCreatedAt(): string
+    {
+        return $this->createdAt;
+    }
+
+    /**
+     * @return string
+     */
+    public function getUpdatedAt(): string
+    {
+        return $this->updatedAt;
+    }
+}

tests/CrowdinApiClient/Api/FileApiTest.php

@@ -5,6 +5,7 @@
 use CrowdinApiClient\Model\DownloadFile;
 use CrowdinApiClient\Model\DownloadFilePreview;
 use CrowdinApiClient\Model\File;
+use CrowdinApiClient\Model\FileReference;
 use CrowdinApiClient\Model\FileRevision;
 use CrowdinApiClient\ModelCollection;
 
@@ -488,4 +489,105 @@ public function testGetRevision()
         $this->assertInstanceOf(FileRevision::class, $fileRevision);
         $this->assertEquals(16, $fileRevision->getId());
     }
+
+    public function testListReferences()
+    {
+        $this->mockRequest([
+            'path' => '/projects/2/files/44/references',
+            'method' => 'get',
+            'response' => '{
+              "data": [
+                {
+                  "data": {
+                    "id": 1,
+                    "projectId": 2,
+                    "fileId": 44,
+                    "name": "Asset Reference",
+                    "type": "image",
+                    "url": "https://cdn.example.com/assets/image.png",
+                    "createdAt": "2019-09-19T15:10:43+00:00",
+                    "updatedAt": "2019-09-19T15:10:46+00:00"
+                  }
+                }
+              ],
+              "pagination": {
+                "offset": 0,
+                "limit": 25
+              }
+            }'
+        ]);
+
+        $references = $this->crowdin->file->listReferences(2, 44);
+
+        $this->assertInstanceOf(ModelCollection::class, $references);
+        $this->assertCount(1, $references);
+        $this->assertInstanceOf(FileReference::class, $references[0]);
+        $this->assertEquals(1, $references[0]->getId());
+        $this->assertEquals('Asset Reference', $references[0]->getName());
+        $this->assertEquals('image', $references[0]->getType());
+        $this->assertEquals('https://cdn.example.com/assets/image.png', $references[0]->getUrl());
+    }
+
+    public function testGetReference()
+    {
+        $this->mockRequestGet('/projects/2/files/44/references/1', '{
+          "data": {
+            "id": 1,
+            "projectId": 2,
+            "fileId": 44,
+            "name": "Asset Reference",
+            "type": "image",
+            "url": "https://cdn.example.com/assets/image.png",
+            "createdAt": "2019-09-19T15:10:43+00:00",
+            "updatedAt": "2019-09-19T15:10:46+00:00"
+          }
+        }');
+
+        $reference = $this->crowdin->file->getReference(2, 44, 1);
+
+        $this->assertInstanceOf(FileReference::class, $reference);
+        $this->assertEquals(1, $reference->getId());
+        $this->assertEquals(2, $reference->getProjectId());
+        $this->assertEquals(44, $reference->getFileId());
+        $this->assertEquals('Asset Reference', $reference->getName());
+        $this->assertEquals('image', $reference->getType());
+        $this->assertEquals('https://cdn.example.com/assets/image.png', $reference->getUrl());
+    }
+
+    public function testAddReference()
+    {
+        $this->mockRequestPost('/projects/2/files/44/references', '{
+          "data": {
+            "id": 1,
+            "projectId": 2,
+            "fileId": 44,
+            "name": "New Asset Reference",
+            "type": "document",
+            "url": "https://docs.example.com/assets/document.pdf",
+            "createdAt": "2019-09-19T15:10:43+00:00",
+            "updatedAt": "2019-09-19T15:10:46+00:00"
+          }
+        }');
+
+        $reference = $this->crowdin->file->addReference(2, 44, [
+            'name' => 'New Asset Reference',
+            'type' => 'document',
+            'url' => 'https://docs.example.com/assets/document.pdf'
+        ]);
+
+        $this->assertInstanceOf(FileReference::class, $reference);
+        $this->assertEquals(1, $reference->getId());
+        $this->assertEquals('New Asset Reference', $reference->getName());
+        $this->assertEquals('document', $reference->getType());
+        $this->assertEquals('https://docs.example.com/assets/document.pdf', $reference->getUrl());
+    }
+
+    public function testDeleteReference()
+    {
+        $this->mockRequestDelete('/projects/2/files/44/references/1');
+
+        $result = $this->crowdin->file->deleteReference(2, 44, 1);
+
+        $this->assertNull($result);
+    }
 }