Poweroffice API client, used it to talk to the PowerOffice API: https://api.poweroffice.net/Web/docs/index.html
You can install the package via composer:
composer require guilty/poweroffice
You can use the package as a standalone PHP Package, here is a simple example:
<?php
use Guilty\Poweroffice\Services\PowerofficeService;
use Guilty\Poweroffice\Sessions\ValueStoreSession;
use GuzzleHttp\Client;
use Spatie\Valuestore\Valuestore;
$client = new Client();
$store = Valuestore::make(config("poweroffice.store_path"));
$session = new ValueStoreSession($store);
$service = new PowerOfficeService(
$client,
$session,
"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", // Application Key
"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", // Client Key
true // Test Mode
);
You can publish the config file like so
php artisan vendor:publish --provider="Guilty\Poweroffice\PowerofficeServiceProvider" --tag="config"
This is the contents of the published config file:
<?php
return [
'application_key' => env("POWEROFFICE_APPLICATION_KEY"),
'client_key' => env("POWEROFFICE_CLIENT_KEY"),
'test_mode' => env("POWEROFFICE_TEST_MODE"),
'store_path' => storage_path("poweroffice.json"), // Used with the ValueStoreSession
];
To get started, add the following environment variable to your .env file:
POWEROFFICE_APPLICATION_KEY=aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa
POWEROFFICE_CLIENT_KEY=bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb
POWEROFFICE_TEST_MODE=true
The PowerOffice API uses the "client_credentials" grant type for authentication, to keep track of the "session" (access token, refresh token and expire date) we use a Session class that stores these values for us, out of the box the following session implementations are provided:
- ArraySession - Used for testing
- ValueStoreSession - Can be used in production, saves all data in a json file defined in the "poweroffice.store_path" config option, uses Spatie's ValueStore package
- RedisSession - Can be used in production, saves all data in a redis cache, keys are prefixed with
POWEROFFICE_SESSION_{KEYNAME}
, expects a Predis Client.
Create a new class that implements
the SessionInterface
interface and add the required methods, the actual implementation is up to you, you can put the data in a database, a file, in redis, or whatever you need.
OR...
extend the AbstractSession
which implements some of the methods for you.
Here is the interface you need to implement.
<?php
namespace Guilty\Poweroffice\Interfaces;
interface SessionInterface
{
public function setAccessToken($accessToken);
public function getAccessToken();
public function setRefreshToken($refreshToken);
public function getRefreshToken();
public function canRefresh();
public function disconnect();
public function setExpireDate(\DateTime $expireDate);
/** @return \DateTimeImmutable */
public function getExpireDate();
public function hasExpired();
public function isValid();
public function setFromResponse($response);
}
Here is an example extending the AbstractSession.
<?php
use Guilty\Poweroffice\Sessions\AbstractSession;
// Or whatever else you want to store your session
class ExcelSpreadsheetSession extends AbstractSession
{
public function setAccessToken($accessToken) { /* TODO: Implement */ }
public function getAccessToken() { /* TODO: Implement */ }
public function setRefreshToken($refreshToken) { /* TODO: Implement */ }
public function getRefreshToken() { /* TODO: Implement */ }
public function disconnect() { /* TODO: Implement */ }
public function setExpireDate(\DateTime $expireDate) { /* TODO: Implement */ }
public function getExpireDate() { /* TODO: Implement */ }
}
You can use the performRequest()
method directly if you just want to use this package as a thin wrapper for Guzzle that handles the oAuth session storage and maintenance, here is an example:
<?php
require "./vendor/autoload.php";
use Guilty\Poweroffice\Services\PowerofficeService;
use GuzzleHttp\Client;
use Guilty\Poweroffice\Sessions\ArraySession;
$service = new PowerOfficeService(
new Client(),
new ArraySession(),
"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", // Application Key
"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", // Client Key
true // Test Mode
);
$customer = $service->performRequest("post", "/Customer", [
"json" => [
"firstName" => "John",
"lastName" => "Smith",
"emailAddress" => "johnsmith@example.com",
"invoiceEmailAddress" => "johnsmith@example.com",
"isArchived" => false,
"isPerson" => true,
"invoiceDeliveryType" => 1, // PDF By Email
"since" => (new DateTimeImmutable())->format("Y-m-d"),
"mailAddress" => $address = [
"address1" => "123 Fakestreet",
"city" => "Lazytown",
"zipCode" => "1234",
"countryCode" => "NO", // ISO Country Code (norway)
"isPrimary" => true,
],
"streetAddresses" => [$address], // Must be an array
]
]);
// All responses will include a success key, that can be used for error handling
if ($response["success"] === false) {
throw new Exception("Customer could not be created");
}
Or you can use the methods provided, that will prefill the method and path for you, as well as make it easier to provide certain data (like start and end dates).
<?php
require "./vendor/autoload.php";
use Guilty\Poweroffice\Services\PowerofficeService;
use GuzzleHttp\Client;
use Guilty\Poweroffice\Sessions\ArraySession;
$service = new PowerOfficeService(
new Client(),
new ArraySession(),
"aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa", // Application Key
"bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb", // Client Key
true // Test Mode
);
$customer = $service->createCustomer([
"json" => [
"firstName" => "John",
"lastName" => "Smith",
"emailAddress" => "johnsmith@example.com",
"invoiceEmailAddress" => "johnsmith@example.com",
"isArchived" => false,
"isPerson" => true,
"invoiceDeliveryType" => 1, // PDF By Email
"since" => (new DateTimeImmutable())->format("Y-m-d"),
"mailAddress" => $address = [
"address1" => "123 Fakestreet",
"city" => "Lazytown",
"zipCode" => "1234",
"countryCode" => "NO", // ISO Country Code (norway)
"isPrimary" => true,
],
"streetAddresses" => [$address], // Must be an array
]
]);
// All responses will include a success key, that can be used for error handling
if ($response["success"] === false) {
throw new Exception("Customer could not be created");
}
It seems that PowerOffice's API is case sensitive when it comes to the field names in oData filtering.
The following services are implemented in the API client wrapper:
- ArraySession (testing)
- ValueStoreSession (production)
- RedisSession (production)
- oData filter builder
- Bank/BankTransfer
- Bank/ClientBankAccount
- Blob
- BrandingTheme
- Client
- ClientAuth
- ContactGroup
- Customer
- DebtCollection
- Department
- Employee
- ExternallyDeliverableInvoice
- GeneralLedgerAccount
- Import
- InvoiceAttachment
- JournalEntryVoucher
- Location
- OutgoingInvoice
- PartyBankAccount
- PartyContactPerson
- Payroll/PayItem
- Payroll/SalaryLine
- Product
- ProductGroup
- Project
- ProjectActivity
- ProjectTeamMember
- RecurringInvoice
- Reporting/AccountTransactions
- Reporting/CustomerLedger
- Reporting/InvoiceJournal
- Reporting/SupplierLedger
- Reporting/TrialBalance
- Reporting/Usage
- SubledgerNumberSeries
- Supplier
- TimeTracking/Activity
- TimeTracking/HourType
- TimeTracking/TimeTrackingEntry
- VatCode
The MIT License (MIT). Please see License File for more information.
Brought to you by Guilty AS
The Poweroffice logo and Trademark is the property of Poweroffice AS