✨ Add expense attachment documentation

And invoice attachment model.

Closes #67

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 - Support for PHP 8.3
+- Handle file uploads and invoice, expense attachments
 - Handle new API version webhook event errors
 
 ## 0.7.0

README.md

@@ -2,7 +2,7 @@
 
 [![Packagist Version](https://badgen.net/packagist/v/amcintosh/freshbooks)](https://packagist.org/packages/amcintosh/freshbooks)
 ![Packagist PHP Version Support](https://img.shields.io/packagist/php-v/amcintosh/freshbooks)
-[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/amcintosh/freshbooks-php-sdk/Run%20Tests)](https://github.com/amcintosh/freshbooks-php-sdk/actions?query=workflow%3A%22Run+Tests%22)
+[![GitHub Workflow Status](https://img.shields.io/github/actions/workflow/status/amcintosh/freshbooks-php-sdk/run-tests.yml?branch=main)](https://github.com/amcintosh/freshbooks-php-sdk/actions?query=workflow%3A%22Run+Tests%22)
 
 A FreshBooks PHP SDK to allow you to more easily utilize the [FreshBooks API](https://www.freshbooks.com/api).
 This library is not directly maintained by FreshBooks and [community contributions](CONTRIBUTING.md) are welcome.

docs/source/file-uploads.rst

@@ -21,7 +21,7 @@ Invoice Images and Attachments
 See `FreshBooks' API Documentation <https://www.freshbooks.com/api/invoice_presentation_attachments>`_.
 
 The ``upload()`` function takes a `PHP resource <https://www.php.net/manual/en/language.types.resource.php>`_.
-Logo's and banners are added to the invoice presentation objec.t To include an uploaded attachment on
+Logo's and banners are added to the invoice presentation object. To include an uploaded attachment on
 an invoice, the invoice request must include an attachments object.
 
 .. code-block:: php
@@ -51,3 +51,23 @@ Expense Receipts
 ----------------
 
 See `FreshBooks' API Documentation <https://www.freshbooks.com/api/expense-attachments>`_.
+
+Expenses have have images or PDFs of the associated receipt attached. The expense request must include
+an attachments object.
+
+.. code-block:: php
+    $attachment = $freshBooksClient->attachments()->upload($accountId, fopen('./sample_receipt.pdf', 'r'));
+
+    $expense->amount = new Money("6.49", "CAD");
+    $expense->date = new DateTime();
+    $expense->staffId = 1;
+    $expense->categoryId = 3436009;
+
+    $expenseAttachment = new ExpenseAttachment();
+    $expenseAttachment->jwt = $attachment->jwt;
+    $expenseAttachment->mediaType = $attachment->mediaType;
+
+    $expense->attachment = $expenseAttachment;
+
+    $includes = (new IncludesBuilder())->include('attachment');
+    $expense = $freshBooksClient->expenses()->create($accountId, model: $expense, includes: $includes);

src/Model/ExpenseAttachment.php

@@ -4,16 +4,11 @@
 
 namespace amcintosh\FreshBooks\Model;
 
-use DateTime;
-use DateTimeImmutable;
-use Spatie\DataTransferObject\Attributes\CastWith;
 use Spatie\DataTransferObject\Attributes\MapFrom;
 use Spatie\DataTransferObject\Attributes\MapTo;
 use Spatie\DataTransferObject\Caster;
 use Spatie\DataTransferObject\DataTransferObject;
 use amcintosh\FreshBooks\Model\DataModel;
-use amcintosh\FreshBooks\Model\Caster\AccountingDateTimeImmutableCaster;
-use amcintosh\FreshBooks\Model\Caster\MoneyCaster;
 
 /**
  * Attached receipt image details for an expense.
@@ -22,7 +17,7 @@
  * present with the use of a corresponding "includes" filter.
  *
  * @package amcintosh\FreshBooks\Model
- * @link https://www.freshbooks.com/api/expenses
+ * @link https://www.freshbooks.com/api/expense-attachments
  */
 class ExpenseAttachment extends DataTransferObject implements DataModel
 {

src/Model/InvoiceAttachment.php

@@ -0,0 +1,74 @@
+<?php
+
+declare(strict_types=1);
+
+namespace amcintosh\FreshBooks\Model;
+
+use Spatie\DataTransferObject\Attributes\MapFrom;
+use Spatie\DataTransferObject\Attributes\MapTo;
+use Spatie\DataTransferObject\Caster;
+use Spatie\DataTransferObject\DataTransferObject;
+use amcintosh\FreshBooks\Model\DataModel;
+
+/**
+ * Attached files and images to include with an invoice.
+ *
+ * _Note:_ This data is not in the default response and will only be
+ * present with the use of a corresponding "includes" filter.
+ *
+ * @package amcintosh\FreshBooks\Model
+ * @link https://www.freshbooks.com/api/invoice_presentation_attachments
+ */
+class InvoiceAttachment extends DataTransferObject implements DataModel
+{
+    public const RESPONSE_FIELD = 'expense';
+
+    /**
+     * @var int The unique identifier of this expense attachment within this business.
+     */
+    public ?int $id;
+
+    /**
+     * @var int Duplicate of id
+     */
+    #[MapFrom('attachmentid')]
+    public ?int $attachmentId;
+
+    /**
+     * @var int Id of the expense this attachment is associated with, if applicable.
+     */
+    #[MapFrom('expenseid')]
+    #[MapTo('expenseid')]
+    public ?int $expenseId;
+
+    /**
+     * @var string JWT link to the attachment.
+     */
+    public ?string $jwt;
+
+    /**
+     * @var string Type of the attachment.
+     */
+    #[MapFrom('media_type')]
+    #[MapTo('media_type')]
+    public ?string $mediaType;
+
+    /**
+     * Get the data as an array to POST or PUT to FreshBooks, removing any read-only fields.
+     *
+     * @return array
+     */
+    public function getContent(): array
+    {
+        $data = $this
+            ->except('id')
+            ->except('attachmentId')
+            ->toArray();
+        foreach ($data as $key => $value) {
+            if (is_null($value)) {
+                unset($data[$key]);
+            }
+        }
+        return $data;
+    }
+}