#1: Docs & examples.

CHANGELOG.md

@@ -0,0 +1,7 @@
+# Change Log
+
+## 0.3.4 - 2016-09-01
+
+### Changed
+
+- Change MaxDataServiceVersion to 3.0 in requests.

README.md

@@ -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) (на русском)

composer.json

@@ -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"
     }

docs/create.ru.md

@@ -0,0 +1,3 @@
+# Создание объектов
+
+TODO

docs/delete.ru.md

@@ -0,0 +1,3 @@
+# Удаление объектов
+
+TODO

docs/documents.ru.md

@@ -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;
+```

docs/index.en.md

@@ -0,0 +1,7 @@
+# OData client-side library
+
+TODO
+
+---
+
+[[русский](index.ru.md)]

docs/index.ru.md

@@ -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)]

docs/install.ru.md

@@ -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

docs/intro.ru.md

@@ -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']);
+```
+
+Здесь мы получаем из документа запись и выводим некоторые её свойства. 

docs/read.ru.md

@@ -0,0 +1,3 @@
+# Получение объектов
+
+TODO

docs/requests.ru.md

@@ -0,0 +1,4 @@
+# Запросы и ответы
+
+TODO
+