From fe0ee9ed5274012d615a853907b28aca16982dc0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D0=9C=D0=B8=D1=85=D0=B0=D0=B8=D0=BB=20=D0=9A=D1=80=D0=B0?= =?UTF-8?q?=D1=81=D0=B8=D0=BB=D1=8C=D0=BD=D0=B8=D0=BA=D0=BE=D0=B2?= Date: Thu, 1 Sep 2016 15:00:31 +0300 Subject: [PATCH] #1: Docs & examples. --- CHANGELOG.md | 7 ++ README.md | 142 ++----------------------- composer.json | 4 +- docs/create.ru.md | 3 + docs/delete.ru.md | 3 + docs/documents.ru.md | 74 +++++++++++++ docs/index.en.md | 7 ++ docs/index.ru.md | 19 ++++ docs/install.ru.md | 19 ++++ docs/intro.ru.md | 71 +++++++++++++ docs/read.ru.md | 3 + docs/requests.ru.md | 4 + docs/service.ru.md | 89 ++++++++++++++++ docs/update.ru.md | 3 + docs/uri.ru.md | 38 +++++++ src/Document/Document.php | 6 +- src/Document/EntryDocument.php | 6 +- src/Document/ErrorDocument.php | 10 +- src/Document/MetadataDocument.php | 8 +- src/DocumentFactory.php | 6 +- src/EDM/Primitive.php | 2 +- src/Element/Element.php | 4 +- src/Element/Entry.php | 14 +-- src/Element/Properties.php | 14 +-- src/Exception/ClientErrorException.php | 2 +- src/Exception/ErrorException.php | 4 +- src/Exception/LogicException.php | 2 + src/Exception/ODataException.php | 2 + src/Exception/RuntimeException.php | 2 + src/Exception/ServerErrorException.php | 2 +- src/OData.php | 12 ++- src/ODataExtension.php | 12 ++- src/Service.php | 28 ++--- src/URI/Collection.php | 12 +-- src/URI/Filter.php | 4 +- src/URI/KeyPredicate.php | 10 +- src/URI/Options.php | 22 ++-- src/URI/Property.php | 12 +-- src/URI/Uri.php | 14 +-- src/URI/UriComponent.php | 10 +- 40 files changed, 469 insertions(+), 237 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 docs/create.ru.md create mode 100644 docs/delete.ru.md create mode 100644 docs/documents.ru.md create mode 100644 docs/index.en.md create mode 100644 docs/index.ru.md create mode 100644 docs/install.ru.md create mode 100644 docs/intro.ru.md create mode 100644 docs/read.ru.md create mode 100644 docs/requests.ru.md create mode 100644 docs/service.ru.md create mode 100644 docs/update.ru.md create mode 100644 docs/uri.ru.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..90745d0 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,7 @@ +# Change Log + +## 0.3.4 - 2016-09-01 + +### Changed + +- Change MaxDataServiceVersion to 3.0 in requests. diff --git a/README.md b/README.md index b916c8b..6a19d29 100644 --- a/README.md +++ b/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) (на русском) diff --git a/composer.json b/composer.json index 1ad1f56..6504f6e 100644 --- a/composer.json +++ b/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" } diff --git a/docs/create.ru.md b/docs/create.ru.md new file mode 100644 index 0000000..6574022 --- /dev/null +++ b/docs/create.ru.md @@ -0,0 +1,3 @@ +# Создание объектов + +TODO diff --git a/docs/delete.ru.md b/docs/delete.ru.md new file mode 100644 index 0000000..041dd89 --- /dev/null +++ b/docs/delete.ru.md @@ -0,0 +1,3 @@ +# Удаление объектов + +TODO diff --git a/docs/documents.ru.md b/docs/documents.ru.md new file mode 100644 index 0000000..64a0bbc --- /dev/null +++ b/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; +``` diff --git a/docs/index.en.md b/docs/index.en.md new file mode 100644 index 0000000..8bf6eb8 --- /dev/null +++ b/docs/index.en.md @@ -0,0 +1,7 @@ +# OData client-side library + +TODO + +--- + +[[русский](index.ru.md)] diff --git a/docs/index.ru.md b/docs/index.ru.md new file mode 100644 index 0000000..e2fcb6f --- /dev/null +++ b/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)] diff --git a/docs/install.ru.md b/docs/install.ru.md new file mode 100644 index 0000000..341279e --- /dev/null +++ b/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 diff --git a/docs/intro.ru.md b/docs/intro.ru.md new file mode 100644 index 0000000..43d1f92 --- /dev/null +++ b/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']); +``` + +Здесь мы получаем из документа запись и выводим некоторые её свойства. diff --git a/docs/read.ru.md b/docs/read.ru.md new file mode 100644 index 0000000..bda87fa --- /dev/null +++ b/docs/read.ru.md @@ -0,0 +1,3 @@ +# Получение объектов + +TODO \ No newline at end of file diff --git a/docs/requests.ru.md b/docs/requests.ru.md new file mode 100644 index 0000000..f4948ff --- /dev/null +++ b/docs/requests.ru.md @@ -0,0 +1,4 @@ +# Запросы и ответы + +TODO + diff --git a/docs/service.ru.md b/docs/service.ru.md new file mode 100644 index 0000000..fefcc9c --- /dev/null +++ b/docs/service.ru.md @@ -0,0 +1,89 @@ +# Класс Service + +Класс `Mekras\OData\Client\Service` предоставляет интерфейс для взаимодействия со службой OData. + +## Service::__construct + +Создаёт экземпляр службы OData. + +```php +public function __construct(string $serviceRootUri, Http\Client\HttpClient $httpClient, + Http\Message\RequestFactory $requestFactory) +``` + +### Аргументы + +- **$serviceRootUri** — Корневой адрес службы OData. +- **$httpClient** — Клиент HTTP (см. [Установка](install.ru.md)). +- **$requestFactory** — Фабрика запросов HTTP (см. [Установка](install.ru.md)). + + +## Service::sendRequest + +Выполняет запрос к службе OData. + +```php +public function sendRequest(string $method, string $uri, + Mekras\Atom\Document\Document Document $document = null): Mekras\Atom\Document\Document +``` + +### Аргументы + +- **$method** — Метод запроса. Можно использовать обычные имена методов HTTP («GET», «POST») или + константы класса `Mekras\OData\Client\OData`: `OData::GET`, `OData::CREATE`, `OData::UPDATE` и + `OData::DELETE`. +- **$uri** — Запрашиваемый URI относительно корневого адреса, указанного в конструкторе. +- **$document** — Документ, который надо отправить на сервер. + +### Возвращаемые значения + +Возвращает экземпляр одного из дочерних классов `Mekras\Atom\Document\Document`: + +- `Mekras\Atom\Document\FeedDocument` — коллекция объектов; +- `Mekras\AtomPub\Document\CategoryDocument` — список категорий; +- `Mekras\AtomPub\Document\ServiceDocument` — сервисный документ; +- `Mekras\OData\Client\Document\EntryDocument` — объект OData; +- `Mekras\OData\Client\Document\MetadataDocument` — мета-данные службы. + +Подробнее об этих типах документов читайте в разделе [Документы](documents.ru.md). + +### Ошибки / исключения + +Метод вбрасывает следующие исключения. + +- `\InvalidArgumentException` если тип документа $document не поддерживается. +- `\Mekras\Atom\Exception\RuntimeException` в случае ошибок в XML, полученном от сервера. +- `\Mekras\OData\Client\Exception\ClientErrorException` если сервер сообщает об ошибке клиента. +- `\Mekras\OData\Client\Exception\ServerErrorException` в случае ошибки на стороне сервера. +- `\Mekras\OData\Client\Exception\RuntimeException` в остальных случаях. + +### См. также + +- [Запросы и ответы](requests.ru.md) + + +## Service::getServiceRootUri + +Возвращает корневой адрес службы OData. + +```php +public function getServiceRootUri(): string +``` + +### Возвращаемые значения + +Адрес, переданный в конструкторе `Service`. + + +## getDocumentFactory + +Возвращает фабрику документов. + +```php +public function getDocumentFactory(): Mekras\OData\Client\DocumentFactory +``` + +### См. также + +- [Создание объектов](create.ru.md) + diff --git a/docs/update.ru.md b/docs/update.ru.md new file mode 100644 index 0000000..534a29d --- /dev/null +++ b/docs/update.ru.md @@ -0,0 +1,3 @@ +# Изменение объектов + +TODO diff --git a/docs/uri.ru.md b/docs/uri.ru.md new file mode 100644 index 0000000..725fc43 --- /dev/null +++ b/docs/uri.ru.md @@ -0,0 +1,38 @@ +# Составление адресов + +TODO + +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); +``` diff --git a/src/Document/Document.php b/src/Document/Document.php index 61eb753..a0257c5 100644 --- a/src/Document/Document.php +++ b/src/Document/Document.php @@ -15,7 +15,7 @@ /** * OData document. * - * @since 1.0 + * @since 0.3 */ abstract class Document extends AtomPubDocument { @@ -27,7 +27,7 @@ abstract class Document extends AtomPubDocument * * @throws \InvalidArgumentException If $document root node has invalid name. * - * @since 1.0 + * @since 0.3 */ public function __construct(Extensions $extensions, \DOMDocument $document = null) { @@ -45,7 +45,7 @@ public function __construct(Extensions $extensions, \DOMDocument $document = nul * * @return \DOMXPath * - * @since 1.0 + * @since 0.3 */ protected function getXPath() { diff --git a/src/Document/EntryDocument.php b/src/Document/EntryDocument.php index 6762cc4..47f87cb 100644 --- a/src/Document/EntryDocument.php +++ b/src/Document/EntryDocument.php @@ -13,7 +13,7 @@ /** * OData Service entry response. * - * @since 1.0 + * @since 0.3.2 */ class EntryDocument extends BaseEntryDocument { @@ -25,7 +25,7 @@ class EntryDocument extends BaseEntryDocument * * @throws \InvalidArgumentException If $document root node has invalid name. * - * @since 1.0 + * @since 0.3.2 */ public function __construct(Extensions $extensions, $document = null) { @@ -44,7 +44,7 @@ public function __construct(Extensions $extensions, $document = null) * * @return \Mekras\OData\Client\Element\Entry * - * @since 1.0 + * @since 0.3.2 */ public function getEntry() { diff --git a/src/Document/ErrorDocument.php b/src/Document/ErrorDocument.php index 7671459..1c9d65e 100644 --- a/src/Document/ErrorDocument.php +++ b/src/Document/ErrorDocument.php @@ -12,7 +12,7 @@ /** * OData Service error response. * - * @since 1.0 + * @since 0.3 */ class ErrorDocument extends Document { @@ -21,7 +21,7 @@ class ErrorDocument extends Document * * @return int * - * @since 1.0 + * @since 0.3 */ public function getCode() { @@ -35,7 +35,7 @@ public function getCode() * * @return string * - * @since 1.0 + * @since 0.3 */ public function getMessage() { @@ -49,7 +49,7 @@ public function getMessage() * * @return string * - * @since 1.0 + * @since 0.3 */ public function ns() { @@ -61,7 +61,7 @@ public function ns() * * @return string * - * @since 1.0 + * @since 0.3 */ protected function getRootNodeName() { diff --git a/src/Document/MetadataDocument.php b/src/Document/MetadataDocument.php index 79faf6a..1813b26 100644 --- a/src/Document/MetadataDocument.php +++ b/src/Document/MetadataDocument.php @@ -10,9 +10,9 @@ /** * OData Metadata document. * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/overview/#ServiceMetadataDocument + * @see http://www.odata.org/documentation/odata-version-2-0/overview/#ServiceMetadataDocument */ class MetadataDocument extends Document { @@ -21,7 +21,7 @@ class MetadataDocument extends Document * * @return string * - * @since 1.0 + * @since 0.3.2 */ public function ns() { @@ -33,7 +33,7 @@ public function ns() * * @return string * - * @since 1.0 + * @since 0.3.2 */ protected function getRootNodeName() { diff --git a/src/DocumentFactory.php b/src/DocumentFactory.php index 2234b7c..7bbc05f 100644 --- a/src/DocumentFactory.php +++ b/src/DocumentFactory.php @@ -15,14 +15,14 @@ /** * OData document factory. * - * @since 1.0 + * @since 0.3 */ class DocumentFactory extends BaseDocumentFactory { /** * Create new factory. * - * @since 1.0 + * @since 0.3 */ public function __construct() { @@ -39,7 +39,7 @@ public function __construct() * * @throws \Mekras\OData\Client\Exception\LogicException * - * @since 1.0 + * @since 0.3.2 */ public function createEntityDocument($type) { diff --git a/src/EDM/Primitive.php b/src/EDM/Primitive.php index 1408705..ab477a6 100644 --- a/src/EDM/Primitive.php +++ b/src/EDM/Primitive.php @@ -16,7 +16,7 @@ * * @since 1.0 * - * @link http://www.odata.org/documentation/odata-version-2-0/overview/#EntityDataModel + * @see http://www.odata.org/documentation/odata-version-2-0/overview/#EntityDataModel */ class Primitive extends Element { diff --git a/src/Element/Element.php b/src/Element/Element.php index d0057f5..1a66dbb 100644 --- a/src/Element/Element.php +++ b/src/Element/Element.php @@ -13,7 +13,7 @@ /** * Abstract OData element. * - * @since 1.0 + * @since 0.3 */ abstract class Element extends BaseElement { @@ -22,7 +22,7 @@ abstract class Element extends BaseElement * * @return \DOMXPath * - * @since 1.0 + * @since 0.3 */ protected function getXPath() { diff --git a/src/Element/Entry.php b/src/Element/Entry.php index 44b0695..ba67f76 100644 --- a/src/Element/Entry.php +++ b/src/Element/Entry.php @@ -16,9 +16,9 @@ /** * OData Entry. * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/overview/#EntityDataModel + * @see http://www.odata.org/documentation/odata-version-2-0/overview/#EntityDataModel */ class Entry extends BaseEntry implements \ArrayAccess { @@ -29,7 +29,7 @@ class Entry extends BaseEntry implements \ArrayAccess * * @throws \Mekras\Atom\Exception\MalformedNodeException * - * @since 1.0 + * @since 0.3 */ public function getEntityType() { @@ -55,7 +55,7 @@ function () { * * @throws \Mekras\OData\Client\Exception\LogicException * - * @since 1.0 + * @since 0.3 */ public function setEntityType($type) { @@ -81,7 +81,7 @@ public function setEntityType($type) * * @return Properties * - * @since 1.0 + * @since 0.3 */ public function getProperties() { @@ -105,7 +105,7 @@ function () { * * @return Link[] * - * @since 1.0 + * @since 0.3 */ public function getRelations() { @@ -137,7 +137,7 @@ function () { * @throws \InvalidArgumentException * @throws \Mekras\Atom\Exception\MalformedNodeException * - * @since 1.0 + * @since 0.3 */ public function addRelation($resource, $type = null) { diff --git a/src/Element/Properties.php b/src/Element/Properties.php index c48c811..f7cb339 100644 --- a/src/Element/Properties.php +++ b/src/Element/Properties.php @@ -15,7 +15,7 @@ /** * OData Entry properties. * - * @since 1.0 + * @since 0.3 */ class Properties extends Element implements \Iterator { @@ -32,7 +32,7 @@ class Properties extends Element implements \Iterator * @param Content $parent Parent node. * @param \DOMElement|null $element DOM element. * - * @since 1.0 + * @since 0.3 * * @throws \InvalidArgumentException If $element has invalid namespace. */ @@ -66,7 +66,7 @@ public function __construct(Content $parent, $element = null) * @throws \InvalidArgumentException * @throws \Mekras\OData\Client\Exception\LogicException If property already exist. * - * @since 1.0 + * @since 0.3 */ public function add($name, $value, $type = Primitive::STRING) { @@ -86,7 +86,7 @@ public function add($name, $value, $type = Primitive::STRING) * * @return Primitive * - * @since 1.0 + * @since 0.3 */ public function get($name) { @@ -100,7 +100,7 @@ public function get($name) * * @return bool * - * @since 1.0 + * @since 0.3 */ public function has($name) { @@ -112,7 +112,7 @@ public function has($name) * * @return string * - * @since 1.0 + * @since 0.3 */ public function ns() { @@ -176,7 +176,7 @@ public function rewind() * * @return string * - * @since 1.0 + * @since 0.3 */ protected function getNodeName() { diff --git a/src/Exception/ClientErrorException.php b/src/Exception/ClientErrorException.php index b3d40ba..b025a27 100644 --- a/src/Exception/ClientErrorException.php +++ b/src/Exception/ClientErrorException.php @@ -10,7 +10,7 @@ /** * Client error. * - * @since 1.0 + * @since 0.2 */ class ClientErrorException extends ErrorException { diff --git a/src/Exception/ErrorException.php b/src/Exception/ErrorException.php index 0ac51f7..d7a17ec 100644 --- a/src/Exception/ErrorException.php +++ b/src/Exception/ErrorException.php @@ -8,9 +8,9 @@ namespace Mekras\OData\Client\Exception; /** - * Server issued error + * Server issued error. * - * @since 1.0 + * @since 0.2 */ abstract class ErrorException extends RuntimeException { diff --git a/src/Exception/LogicException.php b/src/Exception/LogicException.php index df6eb28..60167c5 100644 --- a/src/Exception/LogicException.php +++ b/src/Exception/LogicException.php @@ -9,6 +9,8 @@ /** * OData logic exception. + * + * @since 0.3 */ class LogicException extends \LogicException implements ODataException { diff --git a/src/Exception/ODataException.php b/src/Exception/ODataException.php index 0ba35e0..73fbc6f 100644 --- a/src/Exception/ODataException.php +++ b/src/Exception/ODataException.php @@ -9,6 +9,8 @@ /** * OData exception. + * + * @since 0.3 */ interface ODataException { diff --git a/src/Exception/RuntimeException.php b/src/Exception/RuntimeException.php index 6f8ccdd..546064d 100644 --- a/src/Exception/RuntimeException.php +++ b/src/Exception/RuntimeException.php @@ -9,6 +9,8 @@ /** * OData runtime exception. + * + * @since 0.3 */ class RuntimeException extends \RuntimeException implements ODataException { diff --git a/src/Exception/ServerErrorException.php b/src/Exception/ServerErrorException.php index a00a0d2..212bc0e 100644 --- a/src/Exception/ServerErrorException.php +++ b/src/Exception/ServerErrorException.php @@ -10,7 +10,7 @@ /** * Server error. * - * @since 1.0 + * @since 0.2 */ class ServerErrorException extends ErrorException { diff --git a/src/OData.php b/src/OData.php index ba00338..e2287d8 100644 --- a/src/OData.php +++ b/src/OData.php @@ -9,29 +9,39 @@ /** * OData constants. + * + * @since 0.3 */ class OData { /** * OData method: get resource. + * + * @since 0.3 */ const GET = 'GET'; /** * OData method: create resource. + * + * @since 0.3 */ const CREATE = 'POST'; /** * OData method: update resource. + * + * @since 0.3 */ const UPDATE = 'PUT'; /** * OData method: delete resource. + * + * @since 0.3 */ const DELETE = 'DELETE'; - + /* XML namespaces */ const DATA = 'http://schemas.microsoft.com/ado/2007/08/dataservices'; const META = 'http://schemas.microsoft.com/ado/2007/08/dataservices/metadata'; diff --git a/src/ODataExtension.php b/src/ODataExtension.php index e5d1a29..aaaba59 100644 --- a/src/ODataExtension.php +++ b/src/ODataExtension.php @@ -23,6 +23,8 @@ /** * OData extensions. + * + * @since 0.3 */ class ODataExtension implements DocumentExtension, ElementExtension, NamespaceExtension { @@ -34,7 +36,7 @@ class ODataExtension implements DocumentExtension, ElementExtension, NamespaceEx * * @return Document|null * - * @since 1.0 + * @since 0.3 */ public function parseDocument(Extensions $extensions, \DOMDocument $document) { @@ -67,7 +69,7 @@ public function parseDocument(Extensions $extensions, \DOMDocument $document) * * @return Document|null * - * @since 1.0 + * @since 0.3 */ public function createDocument(Extensions $extensions, $name) { @@ -88,7 +90,7 @@ public function createDocument(Extensions $extensions, $name) * * @return Element|null * - * @since 1.0 + * @since 0.3 */ public function parseElement(Node $parent, \DOMElement $element) { @@ -120,7 +122,7 @@ public function parseElement(Node $parent, \DOMElement $element) * * @throws \InvalidArgumentException If $element has invalid namespace. * - * @since 1.0 + * @since 0.3 */ public function createElement(Node $parent, $name) { @@ -140,7 +142,7 @@ public function createElement(Node $parent, $name) * * @return string[] prefix => namespace. * - * @since 1.0 + * @since 0.3 */ public function getNamespaces() { diff --git a/src/Service.php b/src/Service.php index 45007e5..bbcea75 100644 --- a/src/Service.php +++ b/src/Service.php @@ -24,7 +24,7 @@ * * @api * - * @since 1.0 + * @since 0.1 */ class Service { @@ -63,9 +63,9 @@ class Service * @param HttpClient $httpClient HTTP client to use. * @param RequestFactory $requestFactory The HTTP request factory. * - * @since 1.0 + * @since 0.1 * - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions#ServiceRootUri + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions#ServiceRootUri */ public function __construct( $serviceRootUri, @@ -79,7 +79,7 @@ public function __construct( } /** - * Perform actual HTTP request to service + * Perform actual HTTP request to service. * * @param string $method HTTP method. * @param string $uri URI. @@ -89,11 +89,11 @@ public function __construct( * * @throws \InvalidArgumentException If given document is not supported. * @throws \Mekras\Atom\Exception\RuntimeException In case of XML errors. - * @throws \Mekras\OData\Client\Exception\ClientErrorException - * @throws \Mekras\OData\Client\Exception\RuntimeException - * @throws \Mekras\OData\Client\Exception\ServerErrorException + * @throws \Mekras\OData\Client\Exception\ClientErrorException On client error. + * @throws \Mekras\OData\Client\Exception\RuntimeException On other errors. + * @throws \Mekras\OData\Client\Exception\ServerErrorException On server error. * - * @since 1.0 + * @since 0.3 */ public function sendRequest($method, $uri, Document $document = null) { @@ -139,8 +139,8 @@ public function sendRequest($method, $uri, Document $document = null) * * @return string * - * @since 1.0 - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions#ServiceRootUri + * @since 0.3 + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions#ServiceRootUri */ public function getServiceRootUri() { @@ -152,7 +152,7 @@ public function getServiceRootUri() * * @return DocumentFactory * - * @since 1.0 + * @since 0.3.2 */ public function getDocumentFactory() { @@ -160,13 +160,13 @@ public function getDocumentFactory() } /** - * Throw exception if server reports error + * Throw exception if server reports error. * * @param ResponseInterface $response * @param Document $document * - * @throws ServerErrorException - * @throws ClientErrorException + * @throws \Mekras\OData\Client\Exception\ClientErrorException + * @throws \Mekras\OData\Client\Exception\ServerErrorException */ private function checkResponseForErrors(ResponseInterface $response, Document $document) { diff --git a/src/URI/Collection.php b/src/URI/Collection.php index d32e83e..8219920 100644 --- a/src/URI/Collection.php +++ b/src/URI/Collection.php @@ -10,9 +10,9 @@ /** * Collection URI component. * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions/ + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions/ */ class Collection extends UriComponent { @@ -28,7 +28,7 @@ class Collection extends UriComponent * * @param string $name Collection name. * - * @since 1.0 + * @since 0.3 */ public function __construct($name) { @@ -40,7 +40,7 @@ public function __construct($name) * * @return string * - * @since 1.0 + * @since 0.3 */ public function __toString() { @@ -54,7 +54,7 @@ public function __toString() * * @return KeyPredicate * - * @since 1.0 + * @since 0.3 */ public function item($key = null) { @@ -71,7 +71,7 @@ public function item($key = null) * * @return void * - * @since 1.0 + * @since 0.3 */ public function count() { diff --git a/src/URI/Filter.php b/src/URI/Filter.php index 480778f..01ce260 100644 --- a/src/URI/Filter.php +++ b/src/URI/Filter.php @@ -10,9 +10,9 @@ /** * Filter System Query Option. * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#FilterSystemQueryOption + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#FilterSystemQueryOption */ class Filter { diff --git a/src/URI/KeyPredicate.php b/src/URI/KeyPredicate.php index 8c47cf4..b7ef4a7 100644 --- a/src/URI/KeyPredicate.php +++ b/src/URI/KeyPredicate.php @@ -10,9 +10,9 @@ /** * KeyPredicate URI component * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions/ + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions/ */ class KeyPredicate extends UriComponent { @@ -38,7 +38,7 @@ public function __construct($keyValue = null) * * @return string * - * @since 1.0 + * @since 0.3 */ public function __toString() { @@ -64,7 +64,7 @@ public function __toString() * * @return $this * - * @since 1.0 + * @since 0.3 */ public function add($property, $value) { @@ -83,7 +83,7 @@ public function add($property, $value) * * @return Property * - * @since 1.0 + * @since 0.3 */ public function property($name) { diff --git a/src/URI/Options.php b/src/URI/Options.php index 4f1f3ba..d000098 100644 --- a/src/URI/Options.php +++ b/src/URI/Options.php @@ -10,9 +10,9 @@ /** * Query String Options. * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#QueryStringOptions + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#QueryStringOptions */ class Options { @@ -38,7 +38,7 @@ class Options * * @return string * - * @since 1.0 + * @since 0.3 */ public function __toString() { @@ -65,9 +65,9 @@ public function __toString() * * @return $this * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#OrderBySystemQueryOption + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#OrderBySystemQueryOption */ public function orderBy($field, $direction = self::ASC) { @@ -86,9 +86,9 @@ public function orderBy($field, $direction = self::ASC) * * @return $this * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#TopSystemQueryOption + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#TopSystemQueryOption */ public function top($count) { @@ -104,9 +104,9 @@ public function top($count) * * @return $this * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#SkipSystemQueryOption + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#SkipSystemQueryOption */ public function skip($count) { @@ -122,9 +122,9 @@ public function skip($count) * * @return $this * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#FilterSystemQueryOption + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions/#FilterSystemQueryOption */ public function filter($filter) { diff --git a/src/URI/Property.php b/src/URI/Property.php index 42e0fe5..037328d 100644 --- a/src/URI/Property.php +++ b/src/URI/Property.php @@ -8,11 +8,11 @@ namespace Mekras\OData\Client\URI; /** - * Property URI component + * Property URI component. * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions/ + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions/ */ class Property extends UriComponent { @@ -28,7 +28,7 @@ class Property extends UriComponent * * @param string $name Property name. * - * @since 1.0 + * @since 0.3 */ public function __construct($name) { @@ -40,7 +40,7 @@ public function __construct($name) * * @return string * - * @since 1.0 + * @since 0.3 */ public function __toString() { @@ -54,7 +54,7 @@ public function __toString() * * @return void * - * @since 1.0 + * @since 0.3 */ public function value() { diff --git a/src/URI/Uri.php b/src/URI/Uri.php index 039e91a..daf8f2a 100644 --- a/src/URI/Uri.php +++ b/src/URI/Uri.php @@ -8,11 +8,11 @@ namespace Mekras\OData\Client\URI; /** - * OData URI building helper + * OData URI building helper. * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions/ + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions/ */ class Uri extends UriComponent { @@ -26,7 +26,7 @@ class Uri extends UriComponent /** * Create new URI. * - * @since 1.0 + * @since 0.3 */ public function __construct() { @@ -38,7 +38,7 @@ public function __construct() * * @return string * - * @since 1.0 + * @since 0.3 */ public function __toString() { @@ -52,7 +52,7 @@ public function __toString() * * @return Collection * - * @since 1.0 + * @since 0.3 */ public function collection($name) { @@ -67,7 +67,7 @@ public function collection($name) * * @return Options * - * @since 1.0 + * @since 0.3 */ public function options() { diff --git a/src/URI/UriComponent.php b/src/URI/UriComponent.php index cc37d43..9c3069f 100644 --- a/src/URI/UriComponent.php +++ b/src/URI/UriComponent.php @@ -8,11 +8,11 @@ namespace Mekras\OData\Client\URI; /** - * OData URI component + * OData URI component. * - * @since 1.0 + * @since 0.3 * - * @link http://www.odata.org/documentation/odata-version-2-0/uri-conventions/ + * @see http://www.odata.org/documentation/odata-version-2-0/uri-conventions/ */ abstract class UriComponent { @@ -28,7 +28,7 @@ abstract class UriComponent * * @return string * - * @since 1.0 + * @since 0.3 */ public function __toString() { @@ -45,7 +45,7 @@ public function __toString() * * @param UriComponent|string $component * - * @since 1.0 + * @since 0.3 */ protected function addComponent($component) {