diff --git a/composer.json b/composer.json index b9465af..4416d04 100644 --- a/composer.json +++ b/composer.json @@ -17,8 +17,8 @@ ], "require": { "php": ">=7.4", - "fernleafsystems/apiwrappers-base": "^2.0", - "league/oauth2-client": "^2.0" + "fernleafsystems/apiwrappers-base": "^2.1", + "league/oauth2-client": "^2.6" }, "require-dev": { }, diff --git a/src/Api.php b/src/Api.php index 3b813e1..9f2787c 100644 --- a/src/Api.php +++ b/src/Api.php @@ -53,15 +53,11 @@ protected function getResponseDataPayloadKey() :string { return $this->getRequestDataPayloadKey(); } - /** - * @return array|null - */ - public function getCoreResponseData() { + public function getCoreResponseData() :?array { $data = null; if ( $this->isLastRequestSuccess() ) { $key = $this->getResponseDataPayloadKey(); - $decoded = $this->getDecodedResponseBody(); - $data = empty( $key ) ? $decoded : $decoded[ $key ]; + $data = empty( $key ) ? $this->getDecodedResponseBody() : $this->getDecodedResponseBody()[ $key ]; } return $data; } @@ -101,17 +97,9 @@ protected function preSendVerification() { } } - /** - * @return EntityVO|mixed|null - */ - public function sendRequestWithVoResponse() { + public function sendRequestWithVoResponse() :?EntityVO { $data = $this->req()->getCoreResponseData(); - - $VO = null; - if ( !empty( $data ) ) { - $VO = $this->getVO()->applyFromArray( $data ); - } - return $VO; + return empty( $data ) ? null : $this->getVO()->applyFromArray( $data ); } /** diff --git a/src/Entities/BankTransactionExplanation/Create.php b/src/Entities/BankTransactionExplanation/Create.php index cf772f2..4d09699 100644 --- a/src/Entities/BankTransactionExplanation/Create.php +++ b/src/Entities/BankTransactionExplanation/Create.php @@ -38,35 +38,35 @@ public function setAssociatedPaidTo( $sAssociatedTo, $sAssociatedId ) { */ public function setBankAccount( $oBankAccount ) { return $this->removeRequestDataItem( 'bank_transaction' ) - ->setRequestDataItem( 'bank_account', $oBankAccount->getUri() ); + ->setRequestDataItem( 'bank_account', $oBankAccount->url ); } /** - * @param BankTransactionVO $oBankTxn + * @param BankTransactionVO $txn * @return $this */ - public function setBankTxn( $oBankTxn ) { + public function setBankTxn( $txn ) { return $this->removeRequestDataItem( 'bank_account' ) - ->setRequestDataItem( 'bank_transaction', $oBankTxn->getUri() ) - ->setDatedOn( $oBankTxn->getDatedOn() ); + ->setRequestDataItem( 'bank_transaction', $txn->url ) + ->setDatedOn( $txn->dated_on ); } /** - * @param BillVO $oBill + * @param BillVO $bill * @return $this */ - public function setBillPaid( $oBill ) { + public function setBillPaid( $bill ) { return $this->removeRequestDataItem( 'paid_invoice' ) - ->setAssociatedPaidTo( 'bill', $oBill->getUri() ); + ->setAssociatedPaidTo( 'bill', $bill->url ); } /** - * @param InvoiceVO $oInvoice + * @param InvoiceVO $invoice * @return $this */ - public function setInvoicePaid( $oInvoice ) { + public function setInvoicePaid( $invoice ) { return $this->removeRequestDataItem( 'paid_bill' ) - ->setAssociatedPaidTo( 'invoice', $oInvoice->getUri() ); + ->setAssociatedPaidTo( 'invoice', $invoice->url ); } /** diff --git a/src/Entities/BankTransactionExplanation/CreateTransferToAnotherAccount.php b/src/Entities/BankTransactionExplanation/CreateTransferToAnotherAccount.php index c5e9c87..98b793c 100644 --- a/src/Entities/BankTransactionExplanation/CreateTransferToAnotherAccount.php +++ b/src/Entities/BankTransactionExplanation/CreateTransferToAnotherAccount.php @@ -7,10 +7,9 @@ class CreateTransferToAnotherAccount extends Create { /** - * @param BankAccountVO $oBankAccount * @return $this */ - public function setTargetBankAccount( $oBankAccount ) { - return $this->setRequestDataItem( 'transfer_bank_account', $oBankAccount->getUri() ); + public function setTargetBankAccount( BankAccountVO $bankAccount ) { + return $this->setRequestDataItem( 'transfer_bank_account', $bankAccount->url ); } } \ No newline at end of file diff --git a/src/Entities/BankTransactionExplanation/RetrieveBulk.php b/src/Entities/BankTransactionExplanation/RetrieveBulk.php index 16adf12..e0e171b 100644 --- a/src/Entities/BankTransactionExplanation/RetrieveBulk.php +++ b/src/Entities/BankTransactionExplanation/RetrieveBulk.php @@ -14,6 +14,6 @@ class RetrieveBulk extends RetrieveBulkBase { * @return $this */ public function setBankAccount( $oBankAccount ) { - return $this->setRequestDataItem( 'bank_account', $oBankAccount->getUri() ); + return $this->setRequestDataItem( 'bank_account', $oBankAccount->url ); } } \ No newline at end of file diff --git a/src/Entities/BankTransactions/BankTransactionsIterator.php b/src/Entities/BankTransactions/BankTransactionsIterator.php index 0138880..00a7cfa 100644 --- a/src/Entities/BankTransactions/BankTransactionsIterator.php +++ b/src/Entities/BankTransactions/BankTransactionsIterator.php @@ -6,13 +6,9 @@ class BankTransactionsIterator extends Entities\Common\CommonIterator { - /** - * @param Entities\BankAccounts\BankAccountVO $oBankAccount - * @return $this - */ - public function filterByBankAccount( $oBankAccount ) { + public function filterByBankAccount( Entities\BankAccounts\BankAccountVO $bankAccount ) :self { $this->getRetriever() - ->setRequestDataItem( 'bank_account', $oBankAccount->getUri() ); + ->setRequestDataItem( 'bank_account', $bankAccount->url ); return $this; } diff --git a/src/Entities/BankTransactions/Find.php b/src/Entities/BankTransactions/Find.php index b3539f5..69c414d 100644 --- a/src/Entities/BankTransactions/Find.php +++ b/src/Entities/BankTransactions/Find.php @@ -7,11 +7,11 @@ class Find extends RetrieveBulk { /** - * @param BankAccountVO $oBankAccount + * @param BankAccountVO $bankAccount * @return $this */ - public function setBankAccount( $oBankAccount ) { - return $this->setRequestDataItem( 'bank_account', $oBankAccount->getUri() ); + public function setBankAccount( $bankAccount ) { + return $this->setRequestDataItem( 'bank_account', $bankAccount->url ); } /** diff --git a/src/Entities/BankTransactions/UploadStatement.php b/src/Entities/BankTransactions/UploadStatement.php index d665384..5b66273 100644 --- a/src/Entities/BankTransactions/UploadStatement.php +++ b/src/Entities/BankTransactions/UploadStatement.php @@ -58,7 +58,7 @@ protected function getUrlEndpoint() :string { * @return $this */ public function setBankAccount( $oBankAccount ) { - return $this->setRequestQueryDataItem( 'bank_account', $oBankAccount->getUri() ); + return $this->setRequestQueryDataItem( 'bank_account', $oBankAccount->url ); } /** diff --git a/src/Entities/Bills/BillsIterator.php b/src/Entities/Bills/BillsIterator.php index 566d1cd..5a48dc8 100644 --- a/src/Entities/Bills/BillsIterator.php +++ b/src/Entities/Bills/BillsIterator.php @@ -12,7 +12,7 @@ class BillsIterator extends Entities\Common\CommonIterator { */ public function filterByContact( $contact ) { $this->getRetriever() - ->setRequestDataItem( 'contact', $contact->getUri() ); + ->setRequestDataItem( 'contact', $contact->url ); return $this; } diff --git a/src/Entities/Bills/Create.php b/src/Entities/Bills/Create.php index 0c6df41..66db27e 100644 --- a/src/Entities/Bills/Create.php +++ b/src/Entities/Bills/Create.php @@ -25,7 +25,7 @@ public function addBillItem( BillItemVO $item, bool $merge = true ) :self { } public function setCategory( CategoryVO $category ) :self { - return $this->setRequestDataItem( 'category', $category->getUri() ); + return $this->setRequestDataItem( 'category', $category->url ); } /** @@ -47,7 +47,7 @@ public function setComment( $comment ) :self { * @param ContactVO $contact */ public function setContact( $contact ) :self { - return $this->setRequestDataItem( 'contact', $contact->getUri() ); + return $this->setRequestDataItem( 'contact', $contact->url ); } /** diff --git a/src/Entities/Categories/Retrieve.php b/src/Entities/Categories/Retrieve.php index 62db655..b1dbcf9 100644 --- a/src/Entities/Categories/Retrieve.php +++ b/src/Entities/Categories/Retrieve.php @@ -4,37 +4,26 @@ class Retrieve extends Base { - /** - * @return bool - */ - public function exists() { - return !is_null( $this->retrieve() ); + public function exists() :bool { + return $this->retrieve() !== null; } - /** - * @return CategoryVO - */ - public function retrieve() { + public function retrieve() :?CategoryVO { return $this->sendRequestWithVoResponse(); } - /** - * @return CategoryVO|mixed|null - */ - public function sendRequestWithVoResponse() { + public function sendRequestWithVoResponse() :?CategoryVO { try { - $aData = $this->send() - ->getCoreResponseData(); + $data = $this->send()->getCoreResponseData(); } catch ( \Exception $e ) { } $VO = null; - if ( !empty( $aData ) && is_array( $aData ) ) { - foreach ( $aData as $sCatType => $aCategory ) { + if ( !empty( $data ) && is_array( $data ) ) { + foreach ( $data as $sCatType => $aCategory ) { if ( $aCategory[ 'nominal_code' ] == $this->entity_id ) { - $VO = $this->getVO() - ->applyFromArray( $aCategory ); + $VO = $this->getVO()->applyFromArray( $aCategory ); } } } @@ -50,9 +39,6 @@ public function setEntityId( $id ) :self { return $this; } - /** - * @throws \Exception - */ protected function preSendVerification() { parent::preSendVerification(); if ( !$this->hasEntityId() ) { diff --git a/src/Entities/Contacts/Base.php b/src/Entities/Contacts/Base.php index 0451085..d0ff5ad 100644 --- a/src/Entities/Contacts/Base.php +++ b/src/Entities/Contacts/Base.php @@ -1,4 +1,4 @@ -charge_sales_tax; - } - - /** - * @return string - * @deprecated - */ - public function getCountry() { - return $this->country; - } - - /** - * @return string - * @deprecated - */ - public function getEmail() { - return $this->email; - } - - /** - * @return string - * @deprecated - */ - public function getFirstName() { - return $this->first_name; - } - - /** - * @return string - * @deprecated - */ - public function getLastName() { - return $this->last_name; - } - - /** - * @return string - * @deprecated - */ - public function getOrganisationName() { - return $this->organisation_name; - } - - /** - * @return string - * @deprecated - */ - public function getSalesTaxRegistrationNumber() { - return $this->sales_tax_registration_number; - } - - /** - * @return string 'Active', 'Hidden' - * @deprecated - */ - public function getStatus() { - return $this->status; - } - - /** - * @return bool - * @deprecated - */ - public function hasSalesTaxRegistrationNumber() { - return !empty( $this->sales_tax_registration_number ); - } + public const CHARGE_SALES_TAX_AUTO = 'Auto'; + public const CHARGE_SALES_TAX_ALWAYS = 'Always'; + public const CHARGE_SALES_TAX_NEVER = 'Never'; + public const STATUS_ACTIVE = 'Active'; + public const STATUS_HIDDEN = 'Hidden'; } \ No newline at end of file diff --git a/src/Entities/Contacts/ContactsIterator.php b/src/Entities/Contacts/ContactsIterator.php index c3a7ace..111dfef 100644 --- a/src/Entities/Contacts/ContactsIterator.php +++ b/src/Entities/Contacts/ContactsIterator.php @@ -7,12 +7,12 @@ class ContactsIterator extends Entities\Common\CommonIterator { /** - * @param Entities\Contacts\ContactVO $oContact + * @param Entities\Contacts\ContactVO $contact * @return $this */ - public function filterByContact( $oContact ) { + public function filterByContact( $contact ) { $this->getRetriever() - ->setRequestDataItem( 'contact', $oContact->getUri() ); + ->setRequestDataItem( 'contact', $contact->url ); return $this; } diff --git a/src/Entities/Contacts/ContactsTrait.php b/src/Entities/Contacts/ContactsTrait.php index 8df1435..fe0141f 100644 --- a/src/Entities/Contacts/ContactsTrait.php +++ b/src/Entities/Contacts/ContactsTrait.php @@ -4,9 +4,6 @@ trait ContactsTrait { - /** - * @return string - */ protected function getApiEndpoint() :string { return 'contacts'; } diff --git a/src/Entities/Contacts/Create.php b/src/Entities/Contacts/Create.php index 4d3be00..01e8c98 100644 --- a/src/Entities/Contacts/Create.php +++ b/src/Entities/Contacts/Create.php @@ -3,24 +3,18 @@ namespace FernleafSystems\ApiWrappers\Freeagent\Entities\Contacts; use FernleafSystems\ApiWrappers\Freeagent\Entities\Common\Constants; -use FernleafSystems\ApiWrappers\Freeagent\Entities\Common\EntityVO; class Create extends Base { - const REQUEST_METHOD = 'post'; + public const REQUEST_METHOD = 'post'; - /** - * @param array $aData - * @return ContactVO|null - */ - public function create( $aData = [] ) { + public function create( array $data = [] ) :?ContactVO { /** @var ContactVO $contact */ - $contact = $this->setRequestData( $aData, true ) - ->sendRequestWithVoResponse(); + $contact = $this->setRequestData( $data )->sendRequestWithVoResponse(); { // Fix for FreeAgent API broken country names. Find which FA Country corresponds to the requested country. $requestedCountry = $this->getRequestDataItem( 'country' ); - if ( $contact instanceof EntityVO && $contact->country !== $requestedCountry ) { + if ( $contact instanceof ContactVO && $contact->country !== $requestedCountry ) { foreach ( Constants::FREEAGENT_EU_COUNTRIES as $faCountry => $alternatives ) { if ( in_array( strtolower( $requestedCountry ), array_map( 'strtolower', $alternatives ) ) ) { $contact = $this->setAddress_Country( $faCountry ) @@ -34,14 +28,18 @@ public function create( $aData = [] ) { return $contact; } + public function createFromVO( ContactVO $contact ) :?ContactVO { + return $this->create( $contact->getRawData() ); + } + /** * @throws \Exception */ protected function preSendVerification() { parent::preSendVerification(); - $sOrganisationName = $this->getRequestDataItem( 'organisation_name' ); - if ( empty( $sOrganisationName ) ) { + $orgName = $this->getRequestDataItem( 'organisation_name' ); + if ( empty( $orgName ) ) { $firstName = $this->getRequestDataItem( 'first_name' ); if ( empty( $firstName ) ) { throw new \Exception( sprintf( 'Field "%s" cannot be empty.', 'first_name' ) ); @@ -53,118 +51,71 @@ protected function preSendVerification() { } } - /** - * @param string $value - * @return $this - */ - public function setAddress_Country( $value ) { + public function setAddress_Country( string $value ) :self { return $this->setRequestDataItem( 'country', $value ); } - /** - * @param string $sValue - * @param int $nLine - * @return $this - */ - public function setAddress_Line( $sValue, $nLine = 1 ) { - return $this->setRequestDataItem( 'address'.$nLine, $sValue ); + public function setAddress_Line( string $value, int $line = 1 ) :self { + return $this->setRequestDataItem( 'address'.max( min( $line, 3 ), 1 ), $value ); } - /** - * @param string $sValue - * @return $this - */ - public function setAddress_PostalCode( $sValue ) { - return $this->setRequestDataItem( 'postcode', $sValue ); + public function setAddress_PostalCode( string $value ) :self { + return $this->setRequestDataItem( 'postcode', $value ); } - /** - * @param string $sValue - * @return $this - */ - public function setAddress_Region( $sValue ) { - return $this->setRequestDataItem( 'region', $sValue ); + public function setAddress_Region( string $value ) :self { + return $this->setRequestDataItem( 'region', $value ); } - /** - * @param string $sValue - * @return $this - */ - public function setAddress_Town( $sValue ) { - return $this->setRequestDataItem( 'town', $sValue ); + public function setAddress_Town( string $value ) :self { + return $this->setRequestDataItem( 'town', $value ); } - /** - * @param string $email - will set both account email and billing email - * @return $this - */ - public function setEmail( $email ) { + public function setEmail( string $email ) :self { return $this->setRequestDataItem( 'email', $email ) ->setEmailForBilling( $email ); } - /** - * @param string $email - * @return $this - */ - public function setEmailForBilling( $email ) { + public function setEmailForBilling( string $email ) :self { return $this->setRequestDataItem( 'billing_email', $email ); } - /** - * @param string $sName - * @return $this - */ - public function setFirstName( $sName ) { - return $this->setRequestDataItem( 'first_name', $sName ); + public function setFirstName( string $name ) :self { + return $this->setRequestDataItem( 'first_name', $name ); } - /** - * @param string $name - * @return $this - */ - public function setLastName( $name ) { + public function setLastName( string $name ) :self { return $this->setRequestDataItem( 'last_name', $name ); } - /** - * @param string $name - * @return $this - */ - public function setOrganisationName( $name ) { + public function setOrganisationName( string $name ) :self { return $this->setRequestDataItem( 'organisation_name', $name ); } - /** - * @param string $sAutoAlwaysNever - * @return $this - */ - public function setSalesTaxCharge( $sAutoAlwaysNever ) { - return $this->setRequestDataItem( 'charge_sales_tax', $sAutoAlwaysNever ); + public function setSalesTaxCharge( string $charge ) :self { + if ( in_array( $charge, [ + ContactVO::CHARGE_SALES_TAX_ALWAYS, + ContactVO::CHARGE_SALES_TAX_AUTO, + ContactVO::CHARGE_SALES_TAX_NEVER + ] ) ) { + $this->setRequestDataItem( 'charge_sales_tax', $charge ); + } + return $this; } - /** - * @param string $sRegistrationNumber - * @return $this - */ - public function setSalesTaxNumber( $sRegistrationNumber ) { - return $this->setRequestDataItem( 'sales_tax_registration_number', $sRegistrationNumber ); + public function setSalesTaxNumber( string $taxRegistrationNumber ) :self { + return $this->setRequestDataItem( 'sales_tax_registration_number', $taxRegistrationNumber ); } - /** - * @param string $sStatus - * @return $this - */ - public function setStatus( $sStatus ) { - return $this->setRequestDataItem( 'status', ucfirst( strtolower( $sStatus ) ) ); + public function setStatus( string $status ) :self { + if ( in_array( $status, [ ContactVO::STATUS_HIDDEN, ContactVO::STATUS_ACTIVE ] ) ) { + $this->setRequestDataItem( 'status', $status ); + } + return $this; } - /** - * @param bool $bContactLevel - * @return $this - */ - public function setUseContactLevelInvoiceSequence( $bContactLevel ) { - return $this->setRequestDataItem( 'uses_contact_invoice_sequence', $bContactLevel ); + public function setUseContactLevelInvoiceSequence( bool $contactLevel ) :self { + return $this->setRequestDataItem( 'uses_contact_invoice_sequence', $contactLevel ); } protected function getCriticalRequestItems() :array { diff --git a/src/Entities/Contacts/Delete.php b/src/Entities/Contacts/Delete.php index b2698e2..adf9166 100644 --- a/src/Entities/Contacts/Delete.php +++ b/src/Entities/Contacts/Delete.php @@ -4,15 +4,11 @@ class Delete extends Base { - const REQUEST_METHOD = 'delete'; + public const REQUEST_METHOD = 'delete'; - /** - * @param int $nContactId - * @return $this - */ - public function delete( $nContactId = 0 ) { - if ( is_int( $nContactId ) && $nContactId > 0 ) { - $this->setEntityId( $nContactId ); + public function delete( $contactId = 0 ) :self { + if ( is_int( $contactId ) && $contactId > 0 ) { + $this->setEntityId( $contactId ); } return $this->send(); } diff --git a/src/Entities/Contacts/Finder.php b/src/Entities/Contacts/Finder.php index d436d21..c62964c 100644 --- a/src/Entities/Contacts/Finder.php +++ b/src/Entities/Contacts/Finder.php @@ -5,17 +5,17 @@ class Finder extends ContactsIterator { /** - * @param string $sEmail + * @param string $email * @return ContactVO|null */ - public function findByEmail( $sEmail ) { - $oTheOne = null; - foreach ( $this as $oContact ) { - if ( strcasecmp( $oContact->email, $sEmail ) === 0 ) { - $oTheOne = $oContact; + public function findByEmail( $email ) { + $theOne = null; + foreach ( $this as $contact ) { + if ( strcasecmp( $contact->email, $email ) === 0 ) { + $theOne = $contact; break; } } - return $oTheOne; + return $theOne; } } \ No newline at end of file diff --git a/src/Entities/Contacts/Hide.php b/src/Entities/Contacts/Hide.php index 35e9566..f45ac73 100644 --- a/src/Entities/Contacts/Hide.php +++ b/src/Entities/Contacts/Hide.php @@ -1,14 +1,10 @@ -setStatus( 'Hidden' ) - ->update(); + public function hide() :?ContactVO { + return $this->setStatus( 'Hidden' )->update(); } } \ No newline at end of file diff --git a/src/Entities/Contacts/Retrieve.php b/src/Entities/Contacts/Retrieve.php index cff0002..ce3367b 100644 --- a/src/Entities/Contacts/Retrieve.php +++ b/src/Entities/Contacts/Retrieve.php @@ -4,17 +4,11 @@ class Retrieve extends Base { - /** - * @return bool - */ - public function exists() { - return !is_null( $this->retrieve() ); + public function exists() :bool { + return $this->retrieve() !== null; } - /** - * @return ContactVO - */ - public function retrieve() { + public function retrieve() :?ContactVO { return $this->sendRequestWithVoResponse(); } diff --git a/src/Entities/Contacts/Update.php b/src/Entities/Contacts/Update.php index 6300e89..7e1944b 100644 --- a/src/Entities/Contacts/Update.php +++ b/src/Entities/Contacts/Update.php @@ -16,12 +16,8 @@ protected function preSendVerification() { } } - /** - * @param array $aUpdateData - * @return ContactVO|null - */ - public function update( $aUpdateData = [] ) { - return $this->create( $aUpdateData ); + public function update( array $data = [] ) :?ContactVO { + return $this->create( $data ); } protected function getCriticalRequestItems() :array { diff --git a/src/Entities/Invoices/Create.php b/src/Entities/Invoices/Create.php index f9b4e86..b097957 100644 --- a/src/Entities/Invoices/Create.php +++ b/src/Entities/Invoices/Create.php @@ -49,7 +49,7 @@ public function setComments( $comments ) :self { } public function setContact( ContactVO $contact ) :self { - return $this->setRequestDataItem( 'contact', $contact->getUri() ); + return $this->setRequestDataItem( 'contact', $contact->url ); } /** diff --git a/src/Entities/Invoices/InvoicesIterator.php b/src/Entities/Invoices/InvoicesIterator.php index 0476ddd..d8b349d 100644 --- a/src/Entities/Invoices/InvoicesIterator.php +++ b/src/Entities/Invoices/InvoicesIterator.php @@ -12,7 +12,7 @@ class InvoicesIterator extends Entities\Common\CommonIterator { */ public function filterByContact( $contact ) { $this->getRetriever() - ->setRequestDataItem( 'contact', $contact->getUri() ); + ->setRequestDataItem( 'contact', $contact->url ); return $this; }