Created matter

Author: rimi-itk

src/Client/ApiClient.php

@@ -142,6 +142,55 @@ public function matterByMatterNumber(string $matterNumber): Matter
         return $this->createItemResult($response, Matter::class);
     }
 
+    public function matterCreate(array $matterData, ?CaseFile $case = null): Matter
+    {
+        $linkName = 'http://cbrain.com/casefile/rel/create-matter';
+        $url = null !== $case ? $case->links->getLinkUrl($linkName) : $this->getRequestUrl($linkName);
+
+        // The documentation is unclear on this POE stuff. Does it return 303 or 201?
+        // resources/f2-rest-docs/f2-rest-docs-v13s.html#11
+        $response = $this->request(Request::METHOD_POST, $url);
+        if (Response::HTTP_CREATED !== $response->getStatusCode()) {
+            $message = null !== $case
+                ? sprintf('Cannot get matter create POE URL for case %s', $case)
+                : 'Cannot get matter create POE URLs';
+            throw new RuntimeException($message);
+        }
+        try {
+            $location = $this->getHeader('location', $response);
+        } catch (\Exception $e) {
+            $message = null !== $case
+                ? sprintf('Cannot get matter create POE URL for case %s', $case)
+                : 'Cannot get matter create POE URLs';
+            throw new RuntimeException($message, previous: $e);
+        }
+
+        $response = $this->request(Request::METHOD_POST, $location, [
+            'json' => $matterData,
+        ]);
+
+        if (Response::HTTP_CREATED !== $response->getStatusCode()) {
+            $message = null !== $case ? sprintf('Cannot create matter for case %s', $case) : 'Cannot create matter';
+            throw new RuntimeException($message);
+        }
+
+        return $this->createItemResult($response, Matter::class);
+    }
+
+    /**
+     * Get header value.
+     */
+    private function getHeader(string $name, ResponseInterface $response): string
+    {
+        $headers = $response->getHeaders();
+        $name = strtolower($name);
+        if (!array_key_exists($name, $headers)) {
+            throw new RuntimeException(sprintf('Header "%s" not found.', $name));
+        }
+
+        return reset($headers[$name]);
+    }
+
     public function documentById(int $id): Document
     {
         $url = $this->getRequestUrl('http://cbrain.com/casefile/rel/document-by-id', [

src/Model/F2Item/Links.php

@@ -4,6 +4,8 @@
 
 namespace ItkDev\F2ApiClient\Model\F2Item;
 
+use ItkDev\F2ApiClient\Exception\RuntimeException;
+
 /**
  * @phpstan-type Link array{rel: string, href: string, title:string}
  */
@@ -16,7 +18,7 @@ public function __construct(
     {
     }
 
-    static function fromSimpleXMLElement(\SimpleXMLElement $sxe): self
+    public static function fromSimpleXMLElement(\SimpleXMLElement $sxe): self
     {
         $links = [];
         foreach ($sxe->Link as $link) {
@@ -30,12 +32,25 @@ static function fromSimpleXMLElement(\SimpleXMLElement $sxe): self
     }
 
     /**
-     * @param string $rel
      * @return Link
      */
-    public function getLink(string $rel): ?array
+    public function getLink(string $rel): array
+    {
+        if (!array_key_exists($rel, $this->links)) {
+            throw new RuntimeException(sprintf('Cannot get link "%s"', $rel));
+        }
+
+        return $this->links[$rel];
+    }
+
+    public function getLinkUrl(string $rel): string
     {
-        return $this->links[$rel] ?? null;
+        $link = $this->getLink($rel);
+        if (!array_key_exists('href', $link) || !is_string($link['href'])) {
+            throw new RuntimeException(sprintf('Cannot get URL for link "%s"', $rel));
+        }
+
+        return $link['href'];
     }
 
     #[\Override]

src/Model/Matter.php

@@ -6,12 +6,18 @@
 
 final class Matter extends F2Item
 {
+    // resources/f2-rest-docs/f2-rest-docs-v13s.html#65
+    public const string TYPE_INTERNAL = 'Internal';
+    public const string TYPE_INBOUND = 'Inbound';
+    public const string TYPE_OUTBOUND= 'Outbound';
+
     public string $matterNumber;
     public string $title;
     public \DateTimeImmutable $createdDate;
     public \DateTimeImmutable $modifiedDate;
+    public PartyItem $createdBy;
     public PartyItem $modifiedBy;
-    public PartyItem $responsible;
+    public ?PartyItem $responsible;
 
     #[\Override]
     public function setFromSimpleXMLElement(\SimpleXMLElement $sxe): static
@@ -23,8 +29,9 @@ public function setFromSimpleXMLElement(\SimpleXMLElement $sxe): static
         $this->title = (string) $sxe->Title;
         $this->createdDate = new \DateTimeImmutable((string) $sxe->CreatedDate);
         $this->modifiedDate = new \DateTimeImmutable((string) $sxe->ModifiedDate);
+        $this->createdBy = PartyItem::fromSimpleXMLElement($sxe->CreatedBy);
         $this->modifiedBy = PartyItem::fromSimpleXMLElement($sxe->ModifiedBy);
-        $this->responsible = PartyItem::fromSimpleXMLElement($sxe->Responsible);
+        $this->responsible = $sxe->Responsible ? PartyItem::fromSimpleXMLElement($sxe->Responsible) : null;
 
         return $this;
     }
@@ -43,8 +50,9 @@ public function jsonSerialize(): array
             'title' => $this->title,
             'createdDate' => $this->createdDate,
             'modifiedDate' => $this->modifiedDate,
+            'createdBy' => $this->createdBy->jsonSerialize(),
             'modifiedBy' => $this->modifiedBy->jsonSerialize(),
-            'responsible' => $this->responsible->jsonSerialize(),
+            'responsible' => $this->responsible?->jsonSerialize(),
         ] + parent::jsonSerialize();
     }
 }