Skip to content

Commit bc65761

Browse files
author
Willem Stuursma-Ruwen
authored
Merge pull request #117 from archin-software/master
Support browse data
2 parents 8d99e3e + 935afc8 commit bc65761

26 files changed

+2272
-1
lines changed

‎readme.md

Lines changed: 88 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,93 @@ $customer_factory->send($customer);
9494

9595
You can also send multiple objects in one batch, chunking is handled automatically.
9696

97+
### Browse data
98+
In order to get financial data out of Twinfield like general ledger transactions, sales invoices, and so on, you can use the the browse data functionality.
99+
More information about the browse data functionality in Twinfield can be found in the [documentation](https://c3.twinfield.com/webservices/documentation/#/ApiReference/Request/BrowseData).
100+
101+
#### Browse definition
102+
103+
You can retrieve the browse definition of a browse code as follows.
104+
You don't need to retrieve the browse definition for getting the browse data. It's only for viewing the browse definition of a browse code to know exactly which columns are available.
105+
106+
```php
107+
$connector = new BrowseDataApiConnector($connection);
108+
$browseDefinition = $connector->getBrowseDefinition('000');
109+
```
110+
111+
#### Browse fields
112+
113+
You can retrieve the browse fields as follows.
114+
You don't need to retrieve the browse fields for getting the browse data. It's only for viewing the definitions of all browse fields so you now what you can expect when retrieving browse data.
115+
116+
```php
117+
$connector = new BrowseDataApiConnector($connection);
118+
$browseFields = $connector->getBrowseFields();
119+
```
120+
121+
#### Browse data
122+
123+
You can retrieve browse data of a browse code as follows.
124+
125+
```php
126+
$connector = new BrowseDataApiConnector($connection);
127+
128+
// First, create the columns that you want to retrieve (see the browse definition for which columns are available)
129+
$columns[] = (new BrowseColumn())
130+
->setField('fin.trs.head.yearperiod')
131+
->setLabel('Period')
132+
->setVisible(true)
133+
->setAsk(true)
134+
->setOperator('between')
135+
->setFrom('2013/01')
136+
->setTo('2013/12');
137+
138+
$columns[] = (new BrowseColumn())
139+
->setField('fin.trs.head.code')
140+
->setLabel('Transaction type')
141+
->setVisible(true);
142+
143+
$columns[] = (new BrowseColumn())
144+
->setField('fin.trs.head.shortname')
145+
->setLabel('Name')
146+
->setVisible(true);
147+
148+
$columns[] = (new BrowseColumn())
149+
->setField('fin.trs.head.number')
150+
->setLabel('Trans. no.')
151+
->setVisible(true);
152+
153+
$columns[] = (new BrowseColumn())
154+
->setField('fin.trs.line.dim1')
155+
->setLabel('General ledger')
156+
->setVisible(true)
157+
->setAsk(true)
158+
->setOperator('between')
159+
->setFrom('1300')
160+
->setTo('1300');
161+
162+
$columns[] = (new BrowseColumn())
163+
->setField('fin.trs.head.curcode')
164+
->setLabel('Currency')
165+
->setVisible(true);
166+
167+
$columns[] = (new BrowseColumn())
168+
->setField('fin.trs.line.valuesigned')
169+
->setLabel('Value')
170+
->setVisible(true);
171+
172+
$columns[] = (new BrowseColumn())
173+
->setField('fin.trs.line.description')
174+
->setLabel('Description')
175+
->setVisible(true);
176+
177+
// Second, create sort fields
178+
$sortFields[] = new BrowseSortField('fin.trs.head.code');
179+
180+
// Get the browse data
181+
$browseData = $connector->getBrowseData('000', $columns, $sortFields);
182+
```
183+
97184
### Supported resources
98185
Not all resources from the Twinfield API are currently implemented. Feel free to create a pull request when you need
99186
support for another resource.
@@ -111,7 +198,7 @@ support for another resource.
111198
| Transactions:<br> [Purchase](https://c3.twinfield.com/webservices/documentation/#/ApiReference/PurchaseTransactions), [Sale](https://c3.twinfield.com/webservices/documentation/#/ApiReference/SalesTransactions), [Journal](https://c3.twinfield.com/webservices/documentation/#/ApiReference/Transactions/JournalTransactions), [Cash](https://c3.twinfield.com/webservices/documentation/#/ApiReference/Transactions/CashTransactions) | :white_check_mark: | | :white_check_mark: | :white_check_mark: | :white_check_mark: |
112199
| [Users](https://c3.twinfield.com/webservices/documentation/#/ApiReference/Masters/Users) | | :white_check_mark: | | | |
113200
| [Vat types](https://c3.twinfield.com/webservices/documentation/#/ApiReference/Masters/VAT) | | :white_check_mark: | | | |
114-
201+
| [Browse Data](https://c3.twinfield.com/webservices/documentation/#/ApiReference/Request/BrowseData) | :white_check_mark: | | | | :white_check_mark: |
115202

116203
## Links
117204

‎src/ApiConnectors/BrowseDataApiConnector.php

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
<?php
2+
3+
namespace PhpTwinfield\ApiConnectors;
4+
5+
use PhpTwinfield\Exception;
6+
use PhpTwinfield\BrowseColumn;
7+
use PhpTwinfield\BrowseSortField;
8+
use PhpTwinfield\Mappers\BrowseDataMapper;
9+
use PhpTwinfield\Mappers\BrowseDefinitionMapper;
10+
use PhpTwinfield\Request\BrowseData;
11+
use PhpTwinfield\Mappers\BrowseFieldMapper;
12+
use PhpTwinfield\Request\Catalog\BrowseField;
13+
use PhpTwinfield\Request\Read\BrowseDefinition;
14+
use Webmozart\Assert\Assert;
15+
16+
class BrowseDataApiConnector extends BaseApiConnector
17+
{
18+
/**
19+
* Requests the browse definition of the given browse code.
20+
*
21+
* See the Twinfield documentation for the available browse codes:
22+
* https://c3.twinfield.com/webservices/documentation/#/ApiReference/Request/BrowseData#Determine-which-browse-definition-to-use
23+
*
24+
* @param string $code
25+
* @return \PhpTwinfield\BrowseDefinition
26+
* @throws Exception
27+
*/
28+
public function getBrowseDefinition(string $code)
29+
{
30+
// Make a request to read the browse definition of the given browse code.
31+
$requestBrowseDefinition = new BrowseDefinition($code);
32+
33+
// Send the Request document and set the response to this instance.
34+
$response = $this->sendXmlDocument($requestBrowseDefinition);
35+
return BrowseDefinitionMapper::map($response);
36+
}
37+
38+
/**
39+
* Requests the definition of the browse fields. Browse definitions exists of browse fields.
40+
* Each browse fields has its own definition and can be determined by using this function.
41+
*
42+
* Note that which browse fields can be used for getting browse data depends on the browse code which is used.
43+
*
44+
* @return \PhpTwinfield\BrowseField[]
45+
* @throws Exception
46+
*/
47+
public function getBrowseFields()
48+
{
49+
// Make a request to retrieve the list of browse fields.
50+
$requestBrowseField = new BrowseField();
51+
52+
// Send the Request document and set the response to this instance.
53+
$response = $this->sendXmlDocument($requestBrowseField);
54+
return BrowseFieldMapper::map($response);
55+
}
56+
57+
/**
58+
* Requests financial data from Twinfield. This function is based on so called browse codes. These codes are
59+
* predefined definitions of financial data. For more information see the Twinfield documentation:
60+
* https://c3.twinfield.com/webservices/documentation/#/ApiReference/Request/BrowseData
61+
*
62+
* @param string $code
63+
* @param BrowseColumn[] $columns
64+
* @param BrowseSortField[] $sortFields
65+
* @return \PhpTwinfield\BrowseData
66+
* @throws Exception
67+
*/
68+
public function getBrowseData(string $code, array $columns, array $sortFields = [])
69+
{
70+
Assert::minCount($columns, 1);
71+
Assert::allIsInstanceOf($columns, BrowseColumn::class);
72+
Assert::allIsInstanceOf($sortFields, BrowseSortField::class);
73+
74+
$requestBrowseData = new BrowseData($code, $columns, $sortFields);
75+
76+
$response = $this->sendXmlDocument($requestBrowseData);
77+
return BrowseDataMapper::map($response);
78+
}
79+
}

‎src/BrowseColumn.php

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
<?php
2+
3+
namespace PhpTwinfield;
4+
5+
use PhpTwinfield\Enums\BrowseColumnOperator;
6+
7+
class BrowseColumn
8+
{
9+
/** @var int */
10+
private $id;
11+
12+
/** @var string */
13+
private $field;
14+
15+
/** @var string|null */
16+
private $label;
17+
18+
/** @var bool */
19+
private $visible;
20+
21+
/** @var bool */
22+
private $ask;
23+
24+
/** @var BrowseColumnOperator */
25+
private $operator;
26+
27+
/** @var string|null */
28+
private $from;
29+
30+
/** @var string|null */
31+
private $to;
32+
33+
/**
34+
* BrowseColumn constructor.
35+
*/
36+
public function __construct()
37+
{
38+
$this->visible = false;
39+
$this->ask = false;
40+
$this->operator = BrowseColumnOperator::NONE();
41+
}
42+
43+
/**
44+
* @return int
45+
*/
46+
public function getId(): int
47+
{
48+
return $this->id;
49+
}
50+
51+
/**
52+
* @param int $id
53+
* @return BrowseColumn
54+
*/
55+
public function setId(int $id): BrowseColumn
56+
{
57+
$this->id = $id;
58+
return $this;
59+
}
60+
61+
/**
62+
* @return string
63+
*/
64+
public function getField(): string
65+
{
66+
return $this->field;
67+
}
68+
69+
/**
70+
* @param string $field
71+
* @return BrowseColumn
72+
*/
73+
public function setField(string $field): BrowseColumn
74+
{
75+
$this->field = $field;
76+
return $this;
77+
}
78+
79+
/**
80+
* @return string|null
81+
*/
82+
public function getLabel(): ?string
83+
{
84+
return $this->label;
85+
}
86+
87+
/**
88+
* @param string $label
89+
* @return BrowseColumn
90+
*/
91+
public function setLabel(string $label): BrowseColumn
92+
{
93+
$this->label = $label;
94+
return $this;
95+
}
96+
97+
/**
98+
* @return bool
99+
*/
100+
public function isVisible(): bool
101+
{
102+
return $this->visible;
103+
}
104+
105+
/**
106+
* @param bool $visible
107+
* @return BrowseColumn
108+
*/
109+
public function setVisible(bool $visible): BrowseColumn
110+
{
111+
$this->visible = $visible;
112+
return $this;
113+
}
114+
115+
/**
116+
* @return bool
117+
*/
118+
public function isAsk(): bool
119+
{
120+
return $this->ask;
121+
}
122+
123+
/**
124+
* @param bool $ask
125+
* @return BrowseColumn
126+
*/
127+
public function setAsk(bool $ask): BrowseColumn
128+
{
129+
$this->ask = $ask;
130+
return $this;
131+
}
132+
133+
/**
134+
* @return BrowseColumnOperator
135+
*/
136+
public function getOperator(): BrowseColumnOperator
137+
{
138+
return $this->operator;
139+
}
140+
141+
/**
142+
* @param BrowseColumnOperator $operator
143+
* @return BrowseColumn
144+
*/
145+
public function setOperator(BrowseColumnOperator $operator): BrowseColumn
146+
{
147+
$this->operator = $operator;
148+
return $this;
149+
}
150+
151+
/**
152+
* @return string|null
153+
*/
154+
public function getFrom(): ?string
155+
{
156+
return $this->from;
157+
}
158+
159+
/**
160+
* @param string $from
161+
* @return BrowseColumn
162+
*/
163+
public function setFrom(string $from): BrowseColumn
164+
{
165+
$this->from = $from;
166+
return $this;
167+
}
168+
169+
/**
170+
* @return string|null
171+
*/
172+
public function getTo(): ?string
173+
{
174+
return $this->to;
175+
}
176+
177+
/**
178+
* @param string $to
179+
* @return BrowseColumn
180+
*/
181+
public function setTo(string $to): BrowseColumn
182+
{
183+
$this->to = $to;
184+
return $this;
185+
}
186+
}

0 commit comments

Comments
 (0)