Skip to content

Commit

Permalink
#1: Docs & examples.
Browse files Browse the repository at this point in the history
  • Loading branch information
mekras committed Sep 1, 2016
1 parent a6bfbb7 commit fe0ee9e
Show file tree
Hide file tree
Showing 40 changed files with 469 additions and 237 deletions.
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# Change Log

## 0.3.4 - 2016-09-01

### Changed

- Change MaxDataServiceVersion to 3.0 in requests.
142 changes: 9 additions & 133 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,139 +7,15 @@

OData client-side library.

## Service
Supported OData versions:

First you need to create a Service — representation of the certain OData Service specified by URI:
| Version | Support
|---------|--------
| [4.0](http://docs.oasis-open.org/odata/odata/v4.0/) | unknown
| [3.0](http://www.odata.org/documentation/odata-version-3-0) | partial
| [2.0](http://www.odata.org/documentation/odata-version-2-0/) | partial
| 1.0 | partial

```php
use Mekras\OData\Client\Service;

$service = new Service(
'http://example.com/odata/',
$httpClient, // Http\Client\HttpClient
$messageFactory // Http\Message\MessageFactory
);
```

With this service you can perform requests:

```php
$object = $service->sendRequest('GET', '/Categories(1)');
```

## URIs

Special helper `URI` can be used to construct URIs.

Get 5 Category entries skipping first 10 entries, reverse sorted by Name:

```php
use Mekras\OData\Client\URI\Uri;
use Mekras\OData\Client\URI\Options;
// ...

$uri = new Uri();
$uri
->collection('Categories');
$uri
->options()
->top(5)
->skip(10)
->orderBy('Name', Options::DESC);

$document = $service->sendRequest('GET', $uri);
```

Get Category with ID 123:

```php
use Mekras\OData\Client\URI\Uri;
// ...

$uri = new Uri();
$uri
->collection('Categories')
->item('123');

$document = $service->sendRequest('GET', $uri);
```

## Response

Method `Service::sendRequest()` returns an instance one of documents:

* [AtomPub\ServiceDocument](https://github.com/mekras/atompub/blob/master/src/Document/ServiceDocument.php)
* [MetadataDocument](src/Document/MetadataDocument.php)
* [FeedDocument](src/Document/FeedDocument.php)
* [EntryDocument](src/Document/EntryDocument.php)

## Service Documents

[Service Document](http://www.odata.org/documentation/odata-version-2-0/atom-format/#ServiceDocuments)
lists available collections (which are grouped to *workspaces*).

```php
/** @var ServiceDocument $document */
foreach ($document->getWorkspaces() as $workspace) {
echo 'Title: ' . $workspace->getTitle() . PHP_EOL;
foreach ($workspace->getCollections() as $collection) {
echo ' Title: ' . $collection->getTitle() . PHP_EOL;
echo ' Href: ' . $collection->getHref() . PHP_EOL;
}
}
```

## Metadata Documents

[Metadata Document](http://www.odata.org/documentation/odata-version-2-0/overview/#ServiceMetadataDocument)

TODO

## Collections of Entries

Collections represent a set of Entries. In OData, Collections are represented as Atom feeds, with
one Atom entry for each Entry within the Collection.

## Entries

In OData, Entries are represented as Atom entries.

```php
//...

$uri = new Uri();
$uri
->collection('Categories')
->item('123');

$document = $service->sendRequest('GET', $uri);
if (!$document instanceof EntryDocument) {
throw new \RuntimeException;
}
$entry = $document->getEntry(); // Instance of Mekras\OData\Client\Element\Entry
```

Entry meta data can be accessed via normal `Mekras\Atom\Element\Entry` methods:

```php
echo 'Title: ' . $entry->getTitle() . PHP_EOL;
echo 'ID: ' . $entry->getId() . PHP_EOL;
echo 'Updated: ' . $entry->getUpdated()->format('d.m.y H:i:s') . PHP_EOL;
```

Entry properties can be accessed via `getContent` method:

```php
$properties = $entry->getContent();
echo ' Id: ' . $properties['Id'] . PHP_EOL;
echo ' Hostname: ' . $properties['HostName'] . PHP_EOL;
echo ' Operations: ' . $properties['Operations'] . PHP_EOL;
```

Or directly as array elements:

```php
echo ' Id: ' . $entry['Id'] . PHP_EOL;
echo ' Hostname: ' . $entry['HostName'] . PHP_EOL;
echo ' Operations: ' . $entry['Operations'] . PHP_EOL;
```
- [Documentation](docs/index.en.md) (English)
- [Документация](docs/index.ru.md) (на русском)
4 changes: 1 addition & 3 deletions composer.json
Original file line number Diff line number Diff line change
Expand Up @@ -26,9 +26,7 @@
"php-http/client-implementation": "^1.0"
},
"require-dev": {
"guzzlehttp/psr7": "^1.3.1",
"php-http/curl-client": "^1.4.2",
"php-http/message": "^1.2",
"php-http/curl-client": "^1.5.1",
"phpunit/phpunit": "^5.0.9",
"satooshi/php-coveralls": "dev-master"
}
Expand Down
3 changes: 3 additions & 0 deletions docs/create.ru.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Создание объектов

TODO
3 changes: 3 additions & 0 deletions docs/delete.ru.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Удаление объектов

TODO
74 changes: 74 additions & 0 deletions docs/documents.ru.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,74 @@
# Документы

TODO

## Service Documents

[Service Document](http://www.odata.org/documentation/odata-version-2-0/atom-format/#ServiceDocuments)
lists available collections (which are grouped to *workspaces*).

```php
/** @var ServiceDocument $document */
foreach ($document->getWorkspaces() as $workspace) {
echo 'Title: ' . $workspace->getTitle() . PHP_EOL;
foreach ($workspace->getCollections() as $collection) {
echo ' Title: ' . $collection->getTitle() . PHP_EOL;
echo ' Href: ' . $collection->getHref() . PHP_EOL;
}
}
```

## Metadata Documents

[Metadata Document](http://www.odata.org/documentation/odata-version-2-0/overview/#ServiceMetadataDocument)

TODO

## Collections of Entries

Collections represent a set of Entries. In OData, Collections are represented as Atom feeds, with
one Atom entry for each Entry within the Collection.

## Entries

In OData, Entries are represented as Atom entries.

```php
//...

$uri = new Uri();
$uri
->collection('Categories')
->item('123');

$document = $service->sendRequest('GET', $uri);
if (!$document instanceof EntryDocument) {
throw new \RuntimeException;
}
$entry = $document->getEntry(); // Instance of Mekras\OData\Client\Element\Entry
```

Entry meta data can be accessed via normal `Mekras\Atom\Element\Entry` methods:

```php
echo 'Title: ' . $entry->getTitle() . PHP_EOL;
echo 'ID: ' . $entry->getId() . PHP_EOL;
echo 'Updated: ' . $entry->getUpdated()->format('d.m.y H:i:s') . PHP_EOL;
```

Entry properties can be accessed via `getContent` method:

```php
$properties = $entry->getContent();
echo ' Id: ' . $properties['Id'] . PHP_EOL;
echo ' Hostname: ' . $properties['HostName'] . PHP_EOL;
echo ' Operations: ' . $properties['Operations'] . PHP_EOL;
```

Or directly as array elements:

```php
echo ' Id: ' . $entry['Id'] . PHP_EOL;
echo ' Hostname: ' . $entry['HostName'] . PHP_EOL;
echo ' Operations: ' . $entry['Operations'] . PHP_EOL;
```
7 changes: 7 additions & 0 deletions docs/index.en.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
# OData client-side library

TODO

---

[[русский](index.ru.md)]
19 changes: 19 additions & 0 deletions docs/index.ru.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Клиентская библиотека OData

1. [Установка](install.ru.md)
2. [Начало работы](intro.ru.md)
3. [Составление адресов](uri.ru.md)
4. [Запросы и ответы](requests.ru.md)
5. [Документы](documents.ru.md)
6. [Получение объектов](read.ru.md)
7. [Создание объектов](create.ru.md)
8. [Изменение объектов](update.ru.md)
9. [Удаление объектов](delete.ru.md)

**Приложения**

- [Класс Service](service.ru.md)

---

[[English](index.en.md)]
19 changes: 19 additions & 0 deletions docs/install.ru.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
# Установка

Установка производится с помощью [Composer](https://getcomposer.org/). Однако перед установкой надо
добавить в проект некоторые зависимости.

Для работы с HTTP используются библиотеки [PHP-HTTP](http://php-http.org/). Поэтому надо
подключить пакет, предоставляющий
[php-http/client-implementation](https://packagist.org/providers/php-http/client-implementation),
например [php-http/curl-client](https://packagist.org/packages/php-http/curl-client). Для этого
в папке проекта выполните:

composer require php-http/curl-client

Подробнее о доступных клиентах можно прочитать на сайте
[PHP-HTTP](http://php-http.org/en/latest/clients.html).

Теперь можно установить `odata-client`:

composer require mekras/odata-client
71 changes: 71 additions & 0 deletions docs/intro.ru.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# Введение

Первым делом вам надо создать экземпляр `Service` — представляющий службу OData, заданную
определённым URI.

```php
use Mekras\OData\Client\Service;

$service = new Service(
'http://example.com/odata/',
$httpClient, // Http\Client\HttpClient
$messageFactory // Http\Message\MessageFactory
);
```

Теперь можно выполнить первый запрос к службе:

```php
use Mekras\OData\Client\Document\EntryDocument;
use Mekras\OData\Client\OData;
use Mekras\OData\Client\URI\Uri;

$uri = new Uri();
$uri
->collection('Products')
->item(1);

$document = $service->sendRequest(OData::GET, $uri);

if (!$document instanceof EntryDocument) {
die("Not an entry!\n");
}

$entry = $document->getEntry();
printf("Id: %s\nRelease: %s\n", $entry['ID'], $entry['Price']);
```

Полный пример: [example/get_entry.php](example/get_entry.php).

Разберём пример подробно.

```php
$uri = new Uri();
$uri
->collection('Products')
->item(1);
```

Здесь мы составляем адрес запрашиваемого документа. Результат будет соответствовать «/Products(1)».

Подробнее класс `Uri` рассматривается в разделе [Составление адресов](uri.ru.md).

```php
$document = $service->sendRequest(OData::GET, $uri);

if (!$document instanceof EntryDocument) {
die("Not an entry!\n");
}
```

Запрашиваем у службы OData документ (`OData::GET`) расположенный по составленному нами ранее адресу.
Получив ответ, проверяем, что это документ, содержащий одну запись (`EntryDocument`).

Подробнее метод `sendRequest` рассматривается в разделе [Класс Service](service.ru.md).

```php
$entry = $document->getEntry();
printf("Id: %s\nRelease: %s\n", $entry['ID'], $entry['Price']);
```

Здесь мы получаем из документа запись и выводим некоторые её свойства.
3 changes: 3 additions & 0 deletions docs/read.ru.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
# Получение объектов

TODO
4 changes: 4 additions & 0 deletions docs/requests.ru.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
# Запросы и ответы

TODO

0 comments on commit fe0ee9e

Please sign in to comment.