1<p align="center">
2  <img src="https://static.hoa-project.net/Image/Hoa.svg" alt="Hoa" width="250px" />
3</p>
4
5---
6
7<p align="center">
8  <a href="https://travis-ci.org/hoaproject/protocol"><img src="https://img.shields.io/travis/hoaproject/protocol/master.svg" alt="Build status" /></a>
9  <a href="https://coveralls.io/github/hoaproject/protocol?branch=master"><img src="https://img.shields.io/coveralls/hoaproject/protocol/master.svg" alt="Code coverage" /></a>
10  <a href="https://packagist.org/packages/hoa/protocol"><img src="https://img.shields.io/packagist/dt/hoa/protocol.svg" alt="Packagist" /></a>
11  <a href="https://hoa-project.net/LICENSE"><img src="https://img.shields.io/packagist/l/hoa/protocol.svg" alt="License" /></a>
12</p>
13<p align="center">
14  Hoa is a <strong>modular</strong>, <strong>extensible</strong> and
15  <strong>structured</strong> set of PHP libraries.<br />
16  Moreover, Hoa aims at being a bridge between industrial and research worlds.
17</p>
18
19# Hoa\Protocol
20
21[![Help on IRC](https://img.shields.io/badge/help-%23hoaproject-ff0066.svg)](https://webchat.freenode.net/?channels=#hoaproject)
22[![Help on Gitter](https://img.shields.io/badge/help-gitter-ff0066.svg)](https://gitter.im/hoaproject/central)
23[![Documentation](https://img.shields.io/badge/documentation-hack_book-ff0066.svg)](https://central.hoa-project.net/Documentation/Library/Protocol)
24[![Board](https://img.shields.io/badge/organisation-board-ff0066.svg)](https://waffle.io/hoaproject/protocol)
25
26This library provides the `hoa://` protocol, which is a way to abstract resource
27accesses.
28
29[Learn more](https://central.hoa-project.net/Documentation/Library/Protocol).
30
31## Installation
32
33With [Composer](https://getcomposer.org/), to include this library into
34your dependencies, you need to
35require [`hoa/protocol`](https://packagist.org/packages/hoa/protocol):
36
37```sh
38$ composer require hoa/protocol '~1.0'
39```
40
41For more installation procedures, please read [the Source
42page](https://hoa-project.net/Source.html).
43
44## Testing
45
46Before running the test suites, the development dependencies must be installed:
47
48```sh
49$ composer install
50```
51
52Then, to run all the test suites:
53
54```sh
55$ vendor/bin/hoa test:run
56```
57
58For more information, please read the [contributor
59guide](https://hoa-project.net/Literature/Contributor/Guide.html).
60
61## Quick usage
62
63We propose a quick overview of how to list the current tree of the protocol, how
64to resolve a `hoa://` path and finally how to add a new node in this tree.
65
66### Explore resources
67
68First of all, to get the instance of the `hoa://` protocol, you should use the
69static `getInstance` method on the `Hoa\Protocol\Protocol` class which
70represents the root of the protocol tree:
71
72```php
73echo Hoa\Protocol\Protocol::getInstance();
74
75/**
76 * Might output:
77 *   Application
78 *     Public
79 *   Data
80 *     Etc
81 *       Configuration
82 *       Locale
83 *     Lost+found
84 *     Temporary
85 *     Variable
86 *       Cache
87 *       Database
88 *       Log
89 *       Private
90 *       Run
91 *       Test
92 *   Library
93 */
94```
95
96We see that there is 3 “sub-roots”:
97
98  1. `Application`, representing resources of the application, like public files
99     (in the `Public` node), models, resources… everything related to the
100     application,
101  2. `Data`, representing data required by the application, like configuration
102     files, locales, databases, tests etc.
103  3. `Library`, representing all Hoa's libraries.
104
105Thus, `hoa://Library/Protocol/README.md` represents the abstract path to this
106real file. No matter where you are on the disk, this path will always be valid
107and pointing to this file. This becomes useful in an application where you would
108like to access to a configuration file like this
109`hoa://Data/Etc/Configuration/Foo.php`: Maybe the `Data` directory does not
110exist, maybe the `Etc` or `Configuration` directories do not exist neither, but
111each node of the `hoa://` tree resolves to a valid directory which contains your
112`Foo.php` configuration file. This is an **abstract path for a resource**.
113
114### Resolving a path
115
116We can either resolve a path by using the global `resolve` function or the
117`Hoa\Protocol\Protocol::resolve` method:
118
119```php
120var_dump(
121    resolve('hoa://Library/Protocol/README.md')
122);
123
124/**
125 * Might output:
126 *     string(37) "/usr/local/lib/Hoa/Protocol/README.md"
127 */
128```
129
130### Register new nodes in the tree
131
132The `hoa://` protocol is a tree. Thus, to add a new “component”/“directory” in
133this tree, we must create a node and register it as a child of an existing node.
134Thus, in the following example we will create a `Usb` node, pointing to the
135`/Volumes` directory, and we will add it as a new sub-root, so an immediate
136child of the root:
137
138```php
139$protocol   = Hoa\Protocol\Protocol::getInstance();
140$protocol[] = new Hoa\Protocol\Node('Usb', '/Volumes/');
141```
142
143Here we are. Now, resolving `hoa://Usb/StickA` might point to `/Volumes/StickA`
144(if exists):
145
146```php
147var_dump(
148    resolve('hoa://Usb/StickA')
149);
150
151/**
152 * Might output:
153 *     string(15) "/Volumes/StickA"
154 */
155```
156
157## Documentation
158
159The
160[hack book of `Hoa\Protocol`](https://central.hoa-project.net/Documentation/Library/Protocol)
161contains detailed information about how to use this library and how it works.
162
163To generate the documentation locally, execute the following commands:
164
165```sh
166$ composer require --dev hoa/devtools
167$ vendor/bin/hoa devtools:documentation --open
168```
169
170More documentation can be found on the project's website:
171[hoa-project.net](https://hoa-project.net/).
172
173## Getting help
174
175There are mainly two ways to get help:
176
177  * On the [`#hoaproject`](https://webchat.freenode.net/?channels=#hoaproject)
178    IRC channel,
179  * On the forum at [users.hoa-project.net](https://users.hoa-project.net).
180
181## Contribution
182
183Do you want to contribute? Thanks! A detailed [contributor
184guide](https://hoa-project.net/Literature/Contributor/Guide.html) explains
185everything you need to know.
186
187## License
188
189Hoa is under the New BSD License (BSD-3-Clause). Please, see
190[`LICENSE`](https://hoa-project.net/LICENSE) for details.
191