Skip to content

Commit f9d9680

Browse files
simonrjonessimonrjones
authored
Reorg docs (#8)
Reorganising docs to remove legacy doc pages.
1 parent e2a7e23 commit f9d9680

File tree

7 files changed

+32
-406
lines changed

7 files changed

+32
-406
lines changed

‎README.md‎

Lines changed: 4 additions & 216 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,12 @@ Features:
1111
* Automated debug information (logging and time profiling)
1212
* Cache requests to increase performance
1313
* Tools to help detect whether data has changed since last request
14+
* Transform data (e.g. convert source category to match local category name)
1415

1516
Planned for the future:
1617

17-
* Filter data for security (e.g. strip tags)
1818
* Validate data items to see whether they contain required data properties
19-
* Efficient bulk API queries via concurrent requests
20-
* Transform data (e.g. convert source category to match local category name)
19+
* Efficient bulk API queries via concurrent requests
2120
* Download data via local, FTP, S3 filesystem (via Flysystem)
2221

2322
## Status
@@ -38,219 +37,8 @@ composer require strata/data:^0.8
3837

3938
## Documentation
4039

41-
See [docs](docs/README.md) or the docs site at: [https://docs.strata.dev/data/](https://docs.strata.dev/data/)
40+
See [docs](docs/README.md) - these are currently being cleaned up and we plan to publish better docs for v0.10.
4241

43-
* [0.8 branch docs](https://docs.strata.dev/data/v/release%2F0.8.0/)
44-
45-
## Expected usage
46-
47-
```php
48-
use Stratas\Data\Http\RestApi;
49-
50-
// Use concrete classes to access data
51-
$api = new RestApi('example.com');
52-
53-
// Add functionality via events
54-
$api->addSubscriber(new Logger('/path/to/log'));
55-
$api->addSubscriber(new SymfonyProfiler(new Stopwatch()));
56-
57-
// Use concrete class methods to return response data, this is a GET request
58-
$response = $api->get('uri', $parameters);
59-
60-
// E.g. for GraphQL this looks like:
61-
$response = $api->query($query, $variables);
62-
63-
// Use Data manager to validate and transform data
64-
$manager = new DataManager($api);
65-
66-
// Add validator
67-
$rules = new ValidationRules([
68-
'data.entries' => 'array',
69-
'data.entries.title' => 'required',
70-
];
71-
$manager->addValidator($rules);
72-
73-
/** @var array $data */
74-
$data = $api->decode($response);
75-
76-
if ($manager->validate($data)) {
77-
// do something
78-
}
79-
80-
// Transform data
81-
$manager->addTransformers([
82-
new StripTags(),
83-
new Trim(),
84-
new RenameFields([
85-
'[item_category]' => '[category]'
86-
]),
87-
new MapValues('[category]', [
88-
'origin_name' => 'local_name'
89-
]),
90-
]);
91-
$data = $manager->transform($data);
92-
93-
// Return an item
94-
$manager->setupItem('ItemName', 'rootField');
95-
$item = $manager->getItem('ItemName', $data);
96-
97-
// Return a collection
98-
$manager->setupCollection('CollectionName', new CollectionStrategy()); // ???
99-
$collection = $manager->getCollection('CollectionName', $data);
100-
101-
// Map to an object
102-
$manager->addMapper('ClassName', [
103-
'data_field_1' => 'object_property_1',
104-
'data_field_2' => 'object_property_2'
105-
]);
106-
$object = $manager->mapToObject('ClassName');
107-
108-
// Returns an object of type ClassName
109-
$newObject = new Mapper($response);
110-
```
111-
112-
113-
GraphQL
114-
115-
```php
116-
$graphQl = new GraphQL($endpoint);
117-
118-
// Single record
119-
$query = <<<'EOD'
120-
query {
121-
entry(slug: "my-first-news-item") {
122-
postDate
123-
status
124-
title
125-
}
126-
}
127-
EOD;
128-
129-
try {
130-
$response = $graphQl->query($query);
131-
$data = $response->getContent()->data[];
132-
133-
// @todo update to this:
134-
$item = $graphQl->query($query);
135-
$data = $item->getData();
136-
137-
} catch (\Strata\Data\Exception\HttpNotFoundException) {
138-
// @todo No results found for query
139-
140-
} catch (\Strata\Data\Exception\HttpException $e) {
141-
// HTTP request error
142-
$response = $response->getErrorMessage();
143-
$errorData = $response->getErrorData();
144-
}
145-
146-
// News items
147-
$query = <<<EOD
148-
query {
149-
totalResults: entryCount(section: "news")
150-
entries(section: "news", limit: 2, offset: 0) {
151-
postDate
152-
title
153-
}
154-
}
155-
EOD;
156-
157-
try {
158-
$response = $graphQl->query($query);
159-
$items = $response->getList('entries', ['total' => 'totalResults']);
160-
161-
} catch (FailedRequestException $e) {
162-
$response = $response->getErrorMessage();
163-
$errorData = $response->getErrorData();
164-
}
165-
166-
167-
```
168-
169-
```php
170-
171-
// Return post ID 123
172-
$data = new RestApi('https://domain.com/api/');
173-
174-
$item = $data->get('posts', 123)
175-
->transform(Json);
176-
177-
// Return list of posts
178-
$items = $data->list('posts', ['limit' => 5])
179-
->transform(Json);
180-
181-
// Map results to an object
182-
$mapper = new Mapper(MyObject::class);
183-
$mapper->map('classProperty', 'apiProperty');
184-
185-
// Filter data before it is mapped to the object
186-
$mapper->addFilter('classProperty', new Filter());
187-
188-
// or
189-
$mapper->map('classProperty', 'apiProperty', new Filter());
190-
191-
// Get one post as an object
192-
$data->setMapper('posts', $mapper);
193-
$object = $data->getOne('posts', 123);
194-
195-
// Get a list of posts
196-
197-
// hi you: Do I need to make some form of query object here?
198-
199-
// Loop
200-
while ($data->hasResults()) {
201-
$items = $data->list('posts');
202-
foreach ($items as $item) {
203-
$object = $mapper->map($item);
204-
}
205-
}
206-
207-
// Get multiple, concurrent requests
208-
$urls = ['url1','url2'];
209-
$api->addRequests($urls);
210-
211-
/* addRequests does this internally:
212-
foreach ($urls as $url) {
213-
$requests[] = $api->get($url);
214-
}
215-
*/
216-
217-
// Get data
218-
foreach ($api->getRequests as $request) {
219-
$data = $request->getContent();
220-
}
221-
222-
// Check if data is changed? (requires local cache of content hashes)
223-
$data->isNew();
224-
$data->isChanged();
225-
$data->isDeleted();
226-
227-
// Support different types of APIs
228-
229-
// PaginationBuilder http://stateless.co/hal_specification.html
230-
$api = new HalApi();
231-
232-
// JSON-LD https://json-ld.org/
233-
$api = new JsonLdApi();
234-
235-
// Support custom APIs
236-
$api = new WordPressApi();
237-
238-
// Markdown files
239-
$data = new MarkdownData('path/to/folder');
240-
$item = $data->getOne('./', 'filename.md');
241-
foreach ($data->list() as $item)) {
242-
243-
}
244-
245-
// CSV data
246-
$data = new CsvData('path/to/file.csv');
247-
$item = $data->getOne(1);
248-
foreach ($data->list() as $item) {
249-
250-
}
251-
252-
```
253-
254-
Thanks to
42+
## Thanks to
25543

25644
https://developer.happyr.com/http-client-and-caching

‎docs/README.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
# Introduction
22

3-
Read and write data from external data providers in a standardised format.
4-
53
_Please note: documentation is in progress._
64

5+
Read and write data from external data providers in a standardised format.

‎docs/principles.md‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -37,12 +37,3 @@ Data can be modified via **transformers** or **mappers**. Transformers change da
3737
Mappers can also build collections along with automated pagination.
3838

3939
See [changing data](changing-data/changing-data.md).
40-
41-
### Data manager \(TODO\)
42-
43-
You can use data providers, validators, transformers and mappers independently of each other.
44-
45-
You can also wrap all this functionality up in a **Data Manager** which supports an **event system** to allow you to subscribe to events and run custom functionality. There is support for logging and profiling out of the box.
46-
47-
See [data manager](https://github.com/strata/data/tree/19976c714b935c0075e883fa40c47c7fb5c8aa08/docs/data-manager.md) and [events](advanced-usage/events.md).
48-

‎docs/retrieving-data/bulk-query.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Bulk querying records from an API
2+
3+
A common use data to download data is to bulk download all records in paginated recordset.
4+
5+
Strategy
6+
7+
1. Get field from resultset, use this as a param in next query, until field is empty
8+
2. Get resultset, pass page param, when no results end of resultset
9+
3. Get total results from meta data, query until reach end (concurrent)
10+
11+
```php
12+
$api = new BulkStrategy();
13+
14+
bulk()->total('[result]['totalResults']')->setPage('page')
15+
16+
```
17+
18+
19+
Default param 'page'

‎docs/retrieving-data/graphql.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,3 @@
11
# GraphQL
22

3+
TODO

‎docs/usage/installation.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,12 @@
11
# Installation
22

3+
## Requirements
4+
5+
* PHP 7.4+
6+
* [Composer](https://getcomposer.org/)
7+
8+
## Standalone
9+
310
Install via Composer:
411

512
```

0 commit comments

Comments
 (0)