Small changes to code, added documentation and read me

README.md

@@ -1,167 +1,2101 @@
-# gogs-php-api-client
 
-A client to query Gogs (https://gogs.io) API from PHP.
+Sami Markdown Extension
+===
 
-## Uages: 
+# Table of content    
+1. [Gogs](#gogs "Gogs")
+	1. [API](#gogsapi "Gogs\API")
+		1. [Request](#gogsapirequest "Gogs\API\Request")
+			1. [Base](#base-gogsapirequest "Gogs\API\Request\Base") `@deprecated` Base class for request types.
+			2. [Collection](#collection-gogsapirequest "Gogs\API\Request\Collection") Collection is a collection of data of one type.
+			3. [Exception](#gogsapirequestexception "Gogs\API\Request\Exception")
+				1. [InvalidMethodRequestException](#invalidmethodrequestexception-gogsapirequestexception "Gogs\API\Request\Exception\InvalidMethodRequestException") Thrown whenever a class that inherits the base-classis used wrong (e.g tries to create on a loaded object)
+				2. [NotImplementedException](#notimplementedexception-gogsapirequestexception "Gogs\API\Request\Exception\NotImplementedException") Thrown when the requested method for a class isn'timplemented.
+				3. [RequestErrorException](#requesterrorexception-gogsapirequestexception "Gogs\API\Request\Exception\RequestErrorException") Typically thrown when needed data to build the queryis missing.
+				4. [SearchParamException](#searchparamexception-gogsapirequestexception "Gogs\API\Request\Exception\SearchParamException") Thrown when needed parameters for a search is missing.
+			4. [Org](#org-gogsapirequest "Gogs\API\Request\Org") Stores data and methods related to a single organization.
+			5. [Orgs](#orgs-gogsapirequest "Gogs\API\Request\Orgs") Orgs is a collection of organizations.
+			6. [Repo](#repo-gogsapirequest "Gogs\API\Request\Repo") Stores data and methods related to a single repository.
+			7. [Repos](#repos-gogsapirequest "Gogs\API\Request\Repos") Repos is a collection of repos.
+			8. [RequestInterface](#requestinterface-gogsapirequest "Gogs\API\Request\RequestInterface") Request interface, used by any kind of request object.
+			9. [User](#user-gogsapirequest "Gogs\API\Request\User") Stores user data and methods related to a single user.
+			10. [Users](#users-gogsapirequest "Gogs\API\Request\Users") Returns one or more users in the Gogs installation,depending on the called method.
+		2. [Client](#client-gogsapi "Gogs\API\Client") `@deprecated` Gogs API client.
+	2. [Lib](#gogslib "Gogs\Lib")
+		1. [Curl](#gogslibcurl "Gogs\Lib\Curl")
+			1. [Client](#client-gogslibcurl "Gogs\Lib\Curl\Client") A trait used for every class referencing the api-url and token.
+			2. [Exception](#gogslibcurlexception "Gogs\Lib\Curl\Exception")
+				1. [HTTPUnexpectedResponse](#httpunexpectedresponse-gogslibcurlexception "Gogs\Lib\Curl\Exception\HTTPUnexpectedResponse") Defines an unexpected response.
+				2. [NotAuthorizedException](#notauthorizedexception-gogslibcurlexception "Gogs\Lib\Curl\Exception\NotAuthorizedException") When the request fails because of an unauthorized token,this is thrown instead.
+		2. [ArrayIterator](#arrayiterator-gogslib "Gogs\Lib\ArrayIterator") Interface to store one or more elements in arrayproviding an iterator interface.
+		3. [Collection](#collection-gogslib "Gogs\Lib\Collection") Base class for collections. Implements basicfunctions and typically used to return collectionswhich wont be a part of the "request package"
 
-A guide on how to use will come shortly!
 
-### Quick example:
+---
+Documentation
+---
 
-Clone the repo. Set the `API_URL` and `API_TOKEN` in the index-file. 
+# Gogs
 
-```php
-$client =  new \Client\GogsAPI(API_URL, API_TOKEN);
+ * [Gogs\API](#gogsapi "Namespace: Gogs\API")
+ * [Gogs\API\Request](#gogsapirequest "Namespace: Gogs\API\Request")
+ * [Gogs\API\Request\Exception](#gogsapirequestexception "Namespace: Gogs\API\Request\Exception")
+ * [Gogs\Lib](#gogslib "Namespace: Gogs\Lib")
+ * [Gogs\Lib\Curl](#gogslibcurl "Namespace: Gogs\Lib\Curl")
+ * [Gogs\Lib\Curl\Exception](#gogslibcurlexception "Namespace: Gogs\Lib\Curl\Exception")
 
-$me = $client->user();
-$other = $client->user("username");
+# Gogs\API
 
-$repos = $me->get("/repos")->load();
+## Classes
 
-// Loop through every repo
-for($repo = $repos->current(); $repo != false; $repo = $repos->next())
-    var_dump($repo);
-```
+### Client `Gogs\API`
 
-# Progress
 
-## Users
+* `@deprecated`: 
+* Class uses [Gogs\Lib\Curl\Client](#client-gogslibcurl)
 
-### Search
-```
-GET /users/search
-```
+Gogs API client.
+
+This class initially provide the programmer with a starting
+point (a kind of an "interface" to start from), to keep
+track of the context when going from a user, to a repo,
+organization etc.
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[__construct](#__construct-gogsapiclient)||public| |
+|[users](#users-gogsapiclient)|[Users](#users-gogsapirequest)|public| Returns a Request\Users to fetch users from theGogs installation.|
+|[user](#user-gogsapiclient)|[User](#user-gogsapirequest)|public| Get a single user from Gogs.|
+|[repos](#repos-gogsapiclient)|[Repos](#repos-gogsapirequest)|public| Returns an \Request\Repos to fetch repositorieson the Gogs installation.|
+
+#### Method details
+
+##### __construct `Gogs\API\Client`
 ```php
-$users = $client->users()->search(array("name" => /* username */));
+public function __construct(string $api_url, string $api_token);
 ```
-The array-param can be
-* name/q: The username
-* limit: maximum number of results, default: 10
 
-Returns a `CollectionResult`, e.g
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$api_url|The base URL for the Gogs API (e.g https://git.domain.tld/api/v1)|
+|string|$api_token|The token for an authorized user to query Gogs API.|
+---
+
+
+##### users `Gogs\API\Client`
 ```php
-foreach ($users as $user)
-    echo $user->ufull_name . "\n";
+public function users();
 ```
+ Returns a Request\Users to fetch users from the
+Gogs installation.
 
-### Get authenticated user
-```
-GET /user
-```
+
+Returns: [Users](#users-gogsapirequest)
+
+---
+
+
+##### user `Gogs\API\Client`
 ```php
-$me = $client->user(); // alt: $client->users()->get()
+public function user(string $name = "me");
 ```
+ Get a single user from Gogs.
 
-### Get a single user
-```
-GET /users/:username
-```
+Returns either
+* the authorized user ($name = "" or "me")
+* the specified user ($name = anything else)
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$name|*None*|
+
+Returns: [User](#user-gogsapirequest)
+
+---
+
+
+##### repos `Gogs\API\Client`
 ```php
-$user = $client->user("username"); // alt: $client->users()->get("username")
+public function repos();
 ```
+ Returns an \Request\Repos to fetch repositories
+on the Gogs installation.
+
+
+Returns: [Repos](#repos-gogsapirequest)
+
+---
+
+# Gogs\API\Request
+
+## Classes
 
-### Create a user
+### Base `Gogs\API\Request`
+
+
+* `@deprecated`: since 0.1, to be removed in 3.0
+* Class implements[Gogs\API\Request\RequestInterface](#requestinterface-gogsapirequest)
+* Class uses [Gogs\Lib\Curl\Client](#client-gogslibcurl)
+
+Base class for request types.
+
+Each request shall inherit this class to ensure
+it will have the correct methods required by interface,
+and get the cURL functionality.
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[__construct](#__construct-gogsapirequestbase)||public| |
+|[load](#load-gogsapirequestbase)|object|final public| Load an object.|
+|[method_get](#method_get-gogsapirequestbase)|string|final protected| Perform a GET-request against the Gogs API.|
+|[method_post](#method_post-gogsapirequestbase)|string|final protected| Perform a POST-request against the Gogs API.|
+|[method_delete](#method_delete-gogsapirequestbase)|string|final protected| Perform a DELETE-request against the Gogs API.|
+|[get](#get-gogsapirequestbase)|object|public| Get object references by identifier.|
+|[create](#create-gogsapirequestbase)|bool|public| Create object inherited by class.|
+|[patch](#patch-gogsapirequestbase)|bool|public| Patch (update) object|
+|[delete](#delete-gogsapirequestbase)|bool|public| Delete object.|
+|[json_decode](#json_decode-gogsapirequestbase)|object|final protected| Decode JSON-string.|
+|[json_encode](#json_encode-gogsapirequestbase)|string|final protected| Encode JSON-object/array.|
+|[json_error](#json_error-gogsapirequestbase)||final protected| Check for errors on encoding/decoding.|
+|[property_exists](#property_exists-gogsapirequestbase)|string ***v*** [false](#false-gogsapirequest)|final protected| Checks if the property (key) exists within selfor parent class.|
+|[__get](#__get-gogsapirequestbase)|mixed ***v*** null|final public| Get property by name.|
+|[__set](#__set-gogsapirequestbase)|mixed ***v*** null|final public| Set property by name.|
+|[__isset](#__isset-gogsapirequestbase)|bool|final public| Checks if property is set.|
+|[json_set_property](#json_set_property-gogsapirequestbase)|[true](#true-gogsapirequest) ***v*** array|abstract protected| Set properties for the current object.|
+|[set_scope](#set_scope-gogsapirequestbase)|bool|abstract protected| Set the scope for the request methods accepted by the child.|
+
+#### Method details
+
+##### __construct `Gogs\API\Request\Base`
+```php
+public function __construct(string $api_url, string $api_token);
 ```
-POST /admin/users
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$api_url|The URL to the API.|
+|string|$api_token|A token for an authorized user|
+---
+
+
+##### load `Gogs\API\Request\Base`
+```php
+final public function load(bool $force = false);
 ```
+ Load an object.
+
+If `$force = true` the object will be fetched
+from the Gogs API again.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|bool|$force|Force update, default: true|
+
+Returns: object
+
+---
+
+
+##### method_get `Gogs\API\Request\Base`
 ```php
-$user = $clients->users()->new(
-    "new user", "users@email.com"
-);
+final protected function method_get(array $params = array());
 ```
-The params should be in the order
-* username (required)
-* email (required)
-* source_id
-* login_name
-* password
-* send_notify
+ Perform a GET-request against the Gogs API.
 
-Requires the authenticated user to have admin rights.
-### Delete a user
+Ensure the correct scope i set first, with
+```php
+$this->set_scope("*valid scope*"); // e.g create
 ```
-DELETE /admin/users/:username
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|array|$params|The parameters|
+
+Returns: string
+
+---
+
+
+##### method_post `Gogs\API\Request\Base`
+```php
+final protected function method_post(array $params = array());
 ```
+ Perform a POST-request against the Gogs API.
+
+Ensure the correct scope i set first, with
 ```php
-$user->delete();
+$this->set_scope("*valid scope*"); // e.g create
 ```
-Requires the authenticated user to have admin rights.
 
-### Get a user's repos
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|array|$params|The parameters|
+
+Returns: string
+
+---
+
+
+##### method_delete `Gogs\API\Request\Base`
+```php
+final protected function method_delete();
 ```
-GET /user/repos
+ Perform a DELETE-request against the Gogs API.
+
+Ensure the correct scope i set first, with
+```php
+$this->set_scope("*valid scope*"); // e.g delete
 ```
-or
+
+
+Returns: string
+
+---
+
+
+##### get `Gogs\API\Request\Base`
+```php
+public function get(string $s);
 ```
-GET /users/:username/repos
+ Get object references by identifier.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$s|The idientifier to look up|
+
+Returns: object
+
+---
+
+
+##### create `Gogs\API\Request\Base`
+```php
+public function create(... $args);
 ```
+ Create object inherited by class.
+
+Child class must add a scope for 'create' and ensure child is not *loaded*,
+otherwise will `create` throw an exception.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|[...](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list)|$args|Arguments required by create.|
+
+Returns: bool
+
+Throws: 
+
+* [InvalidMethodRequestException](#invalidmethodrequestexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\InvalidMethodRequestException")
+* [NotImplementedException](#notimplementedexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\NotImplementedException")
+
+---
+
+
+##### patch `Gogs\API\Request\Base`
 ```php
-$repos = $user->repos()->load();
+public function patch();
 ```
+ Patch (update) object
+
+
+Returns: bool
+
+Throws: 
 
-### Get specific user's repo
+* [InvalidMethodRequestException](#invalidmethodrequestexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\InvalidMethodRequestException")
+* [NotImplementedException](#notimplementedexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\NotImplementedException")
+
+---
+
+
+##### delete `Gogs\API\Request\Base`
+```php
+public function delete();
 ```
-GET /repos/:owner/:repo
+ Delete object.
+
+
+Returns: bool
+
+Throws: 
+
+* [NotImplementedException](#notimplementedexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\NotImplementedException")
+
+---
+
+
+##### json_decode `Gogs\API\Request\Base`
+```php
+final protected function json_decode(string $jenc);
 ```
+ Decode JSON-string.
+
+Will ensure that there weren't any errors by calling `$this->json_error`.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$jenc|Encoded JSON string|
+
+Returns: object
+
+---
+
+
+##### json_encode `Gogs\API\Request\Base`
 ```php
-$repo = $user->repo( /* repo */ );
+final protected function json_encode(iterable $jdec);
 ```
+ Encode JSON-object/array.
 
-### Create a user's repo
+Will ensure that there weren't any errors by calling `$this->json_error`.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|[iterable](http://php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration.types)|$jdec|JSON-data|
+
+Returns: string
+
+---
+
+
+##### json_error `Gogs\API\Request\Base`
+```php
+final protected function json_error();
 ```
-POST /user/repos
+ Check for errors on encoding/decoding.
+
+Throws: 
+
+* [RequestErrorException](#requesterrorexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\RequestErrorException")
+
+---
+
+
+##### property_exists `Gogs\API\Request\Base`
+```php
+final protected function property_exists(mixed $name);
 ```
-or
+ Checks if the property (key) exists within self
+or parent class.
+
+Returns the actual key if it does. A class key (aka property)
+start with the tag `classname_` followed by property name,
+reflecting the JSON-object, and can be reached by
+
+ * `$class->parameter`,
+ * `$class->classname_parameter` or alternatively (for classes that inherits another class).
+ * `$class->parentclassname_parameter`.
+
+ If a class override a parent class with the same parameter,
+ the class's own parameter will be favoured.
+
+As this is public properties this wont be an security issue;
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$name|Name of the key.|
+
+Returns: string ***v*** [false](#false-gogsapirequest)
+
+---
+
+
+##### __get `Gogs\API\Request\Base`
+```php
+final public function __get(string $name);
 ```
-POST /admin/users/:username/repos
+ Get property by name.
+
+Checks both self and parent for the property.
+
+Returns the value if property exists, otherwise an `E_USER_NOTICE`
+is triggered.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$name|*None*|
+
+Returns: mixed ***v*** null
+
+---
+
+
+##### __set `Gogs\API\Request\Base`
+```php
+final public function __set(string $name, mixed $value);
 ```
+ Set property by name.
+
+Checks both self and parent for the property.
+
+Returns the value if property exists, otherwise an `E_USER_NOTICE`
+is triggered.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$name|Property name|
+|mixed|$value|Property value|
+
+Returns: mixed ***v*** null
+
+---
+
+
+##### __isset `Gogs\API\Request\Base`
 ```php
-$user->repos()->new(
-    "name"
-);
+final public function __isset(string $name);
 ```
+ Checks if property is set.
+
+Checks both self and parent for property.
+
+Triggers E_USER_NOTICE if property is unknown.
+
 
-The params should be in the order
-* name
-* description
-* private
-* bool
-* auto_init
-* gitignores
-* license
-* readme
+Parameters
 
-Requires the authenticated user to have admin rights to be able to create repos for other users than itself.
+| Type | Variable | Description |
+|---|---|---|
+|string|$name|Property name|
 
-### Delete a user's repo
+Returns: bool
+
+---
+
+
+##### json_set_property `Gogs\API\Request\Base`
+```php
+abstract protected function json_set_property(mixed $obj);
 ```
-DELETE /repos/:owner/:repo
+ Set properties for the current object.
+
+Each child class must implement this to set its data. Will
+be called by methods such as `load` and from collection
+classes.
+
+Will return true/false for singel objects but an array on collections.
+The array will contain the newly inserted elements. This to prevent
+additional iterations.
+
+This method should also set loaded to true or false, depending
+on success or failure.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$obj|*None*|
+
+Returns: [true](#true-gogsapirequest) ***v*** array
+
+---
+
+
+##### set_scope `Gogs\API\Request\Base`
+```php
+abstract protected function set_scope(string $method);
 ```
+ Set the scope for the request methods accepted by the child.
+
+This can be
+ * `get`,
+ * `search`,
+ * `delete` etc.
+
+ Must return true if scope exists of false otherwise. Methods
+ the calls this will throw an exception if not true is returned.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$method|Method type, e.g "get"|
+
+Returns: bool
+
+---
+
+
+### Collection `Gogs\API\Request`
+
+
+* Class extends [Gogs\API\Request\Base](#base-gogsapirequest)
+* Class implements
+	* [Gogs\Lib\ArrayIterator](#arrayiterator-gogslib)
+	* [Gogs\API\Request\RequestInterface](#requestinterface-gogsapirequest)
+
+Collection is a collection of data of one type.
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[add](#add-gogsapirequestcollection)|mixed ***v*** int|public| Add an object to the collection.|
+|[remove](#remove-gogsapirequestcollection)|bool|public| Remove an element in collection.|
+|[all](#all-gogsapirequestcollection)|array|public| |
+|[len](#len-gogsapirequestcollection)|int|public| |
+|[by_key](#by_key-gogsapirequestcollection)|mixed|public| |
+|[next](#next-gogsapirequestcollection)|mixed|public| |
+|[prev](#prev-gogsapirequestcollection)|mixed|public| |
+|[current](#current-gogsapirequestcollection)||public| |
+|[reset](#reset-gogsapirequestcollection)|mixed|public| |
+|[search](#search-gogsapirequestcollection)|[Collection](#collection-gogslib)|abstract public| Search for an object.|
+
+#### Method details
+
+##### add `Gogs\API\Request\Collection`
 ```php
-$repo->delete();
+public function add(mixed $obj, mixed $key = null);
 ```
-Requires the authenticated user to have admin rights to be able to delete repos for other users than itself.
+ Add an object to the collection.
+
+When adding a key the object will be stored
+on the particual key, also overwriting existing data.
 
-### Get a user's organizations
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$obj|Element to store|
+|mixed|$key|Index key to store on|
+
+Returns: mixed ***v*** int
+
+---
+
+
+##### remove `Gogs\API\Request\Collection`
+```php
+public function remove(mixed $any, bool $deep = true);
 ```
-GET /user/orgs
+ Remove an element in collection.
+
+The function will first look for the element as a
+index key, but if its not found it will look for the
+element as a value.
+
+Deep functions only when the value is given and not the key.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$any|Index key or element value|
+|bool|$deep|Delete every item and not just the first|
+
+Returns: bool
+
+---
+
+
+##### all `Gogs\API\Request\Collection`
+```php
+public function all();
 ```
-or
+
+Returns: array
+
+---
+
+
+##### len `Gogs\API\Request\Collection`
+```php
+public function len();
 ```
-GET /users/:username/orgs
+
+Returns: int
+
+---
+
+
+##### by_key `Gogs\API\Request\Collection`
+```php
+public function by_key(mixed $idx);
 ```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$idx|Index key.|
+
+Returns: mixed
+
+---
+
+
+##### next `Gogs\API\Request\Collection`
 ```php
-$orgs = $user->organizations();
+public function next();
 ```
 
-## Organizations
+Returns: mixed
+
+---
 
-### Get an organizations repositories
+
+##### prev `Gogs\API\Request\Collection`
+```php
+public function prev();
 ```
-GET /orgs/:orgname/repos
+
+Returns: mixed
+
+---
+
+
+##### current `Gogs\API\Request\Collection`
+```php
+public function current();
 ```
+---
+
+
+##### reset `Gogs\API\Request\Collection`
 ```php
-$org = $user->organizations()->load()->current();
+public function reset();
+```
 
-$repos = $org->repos();
+Returns: mixed
+
+---
+
+
+##### search `Gogs\API\Request\Collection`
+```php
+abstract public function search(array $params = array());
 ```
+ Search for an object.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|array|$params|Parameters|
+
+Returns: [Collection](#collection-gogslib)
+
+---
+
+
+### Org `Gogs\API\Request`
+
+
+* Class extends [Gogs\API\Request\User](#user-gogsapirequest)
+* Class implements[Gogs\API\Request\RequestInterface](#requestinterface-gogsapirequest)
+
+Stores data and methods related to a single organization.
+
+By now the following are supported:
+
+ * GET `/orgs/username`
+ * POST `/admin/users/username/orgs` (**Requires** admin rights. Curl will throw NotAuthorized exception if not).
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[__construct](#__construct-gogsapirequestorg)||public| Initialize an organization.|
+|[set_scope](#set_scope-gogsapirequestorg)|bool|protected| |
+|[search](#search-gogsapirequestorg)||public| |
+|[create](#create-gogsapirequestorg)|bool|public| Create a new user|
+
+#### Method details
+
+##### __construct `Gogs\API\Request\Org`
+```php
+public function __construct(string $api_url, string $api_token, User $owner = null, string $oname = null);
+```
+ Initialize an organization.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$api_url|The URL to the API.|
+|string|$api_token|A token for an authorized user|
+|[User](#request-gogsapi)|$owner|The owner of the organization|
+|string|$oname|Organization name|
+---
+
+
+##### set_scope `Gogs\API\Request\Org`
+```php
+protected function set_scope(string $method);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$method|Method type, e.g "get"|
+
+Returns: bool
+
+Throws: 
+
+* [InvalidMethodRequestException](#invalidmethodrequestexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\InvalidMethodRequestException")
+* [RequestErrorException](#requesterrorexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\RequestErrorException")
+
+---
+
+
+##### search `Gogs\API\Request\Org`
+```php
+public function search(string $q);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$q|*None*|
+---
+
+
+##### create `Gogs\API\Request\Org`
+```php
+public function create(... $args);
+```
+ Create a new user
+
+Valid parameters:
+
+ 1. username
+ 2. full_name
+ 3. description
+ 4. website
+ 5. location
+
+ This reflects the API v1 doc, but is in an order
+ where the required fields is first.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|[...](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list)|$args|Arguments required by create.|
+
+Returns: bool
+
+---
+
+
+### Orgs `Gogs\API\Request`
+
+
+* Class extends [Gogs\API\Request\Collection](#collection-gogsapirequest)
+* Class implements
+	* [Gogs\Lib\ArrayIterator](#arrayiterator-gogslib)
+	* [Gogs\API\Request\RequestInterface](#requestinterface-gogsapirequest)
+
+Orgs is a collection of organizations.
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[__construct](#__construct-gogsapirequestorgs)||public| |
+|[set_scope](#set_scope-gogsapirequestorgs)|bool|protected| Set the scope for the request methods accepted by the child.|
+|[create](#create-gogsapirequestorgs)|bool|public| Create object inherited by class.|
+|[get](#get-gogsapirequestorgs)|object|public| Get an organization by indentifier.|
+|[search](#search-gogsapirequestorgs)|[Collection](#collection-gogslib)|public| Search for an organization.|
+|[json_set_property](#json_set_property-gogsapirequestorgs)|[true](#true-gogsapirequest) ***v*** array|protected| |
+
+#### Method details
+
+##### __construct `Gogs\API\Request\Orgs`
+```php
+public function __construct(string $api_url, string $api_token, User $owner);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$api_url|The URL to the API.|
+|string|$api_token|A token for an authorized user|
+|[User](#request-gogsapi)|$owner|*None*|
+---
+
+
+##### set_scope `Gogs\API\Request\Orgs`
+```php
+protected function set_scope(string $method);
+```
+ Set the scope for the request methods accepted by the child.
+
+This can be
+ * `get`,
+ * `search`,
+ * `delete` etc.
+
+ Must return true if scope exists of false otherwise. Methods
+ the calls this will throw an exception if not true is returned.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$method|Method type, e.g "get"|
+
+Returns: bool
+
+---
+
+
+##### create `Gogs\API\Request\Orgs`
+```php
+public function create(... $args);
+```
+ Create object inherited by class.
+
+Child class must add a scope for 'create' and ensure child is not *loaded*,
+otherwise will `create` throw an exception.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|[...](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list)|$args|Arguments required by create.|
+
+Returns: bool
+
+Throws: 
+
+* [InvalidMethodRequestException](#invalidmethodrequestexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\InvalidMethodRequestException")
+* [NotImplementedException](#notimplementedexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\NotImplementedException")
+
+---
+
+
+##### get `Gogs\API\Request\Orgs`
+```php
+public function get(string $s);
+```
+ Get an organization by indentifier.
+
+Method will first look through organizations
+already loaded. If not found it will return a
+new object.
+
+Method does not ensure the organization in loaded
+from Gogs so the user should call `->load()` on
+returned element.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$s|The idientifier to look up|
+
+Returns: object
+
+---
+
+
+##### search `Gogs\API\Request\Orgs`
+```php
+public function search(array $params = array());
+```
+ Search for an organization.
+
+Params can be an array of
+```php
+$orgs->search(array(
+ "name"  => "name",      // alt. "q". required
+ "limit" => 10,          // not required, default: 10
+));
+```
+By now, this method can be intensive, as it will load
+every organization and then do a match on each entry.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|array|$params|Parameters|
+
+Returns: [Collection](#collection-gogslib)
+
+Throws: 
+
+* [SearchParamException](#searchparamexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\SearchParamException")
+
+---
+
+
+##### json_set_property `Gogs\API\Request\Orgs`
+```php
+protected function json_set_property(mixed $obj);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$obj|*None*|
+
+Returns: [true](#true-gogsapirequest) ***v*** array
+
+---
+
+
+### Repo `Gogs\API\Request`
+
+
+* Class extends [Gogs\API\Request\Base](#base-gogsapirequest)
+* Class implements[Gogs\API\Request\RequestInterface](#requestinterface-gogsapirequest)
+
+Stores data and methods related to a single repository.
+
+By now the following are supported:
+
+ * GET `/repos/username/reponame`
+ * POST `/user/repos`
+ * POST `/admin/user/username/repos`
+ * POST `/org/orgname/repos`
+ * DELETE `/repos/username/reponame`
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[__construct](#__construct-gogsapirequestrepo)||public| Initialize a repo object.|
+|[set_scope](#set_scope-gogsapirequestrepo)|bool|protected| |
+|[json_set_property](#json_set_property-gogsapirequestrepo)|[true](#true-gogsapirequest) ***v*** array|protected| |
+|[search](#search-gogsapirequestrepo)||public| |
+|[create](#create-gogsapirequestrepo)|bool|public| Create a new repo|
+
+#### Method details
+
+##### __construct `Gogs\API\Request\Repo`
+```php
+public function __construct(string $api_url, string $api_token, User $owner = null, string $name = null);
+```
+ Initialize a repo object.
+
+Note that the owner can also be an Org (organization),
+or any other class that inherits a user.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$api_url|The URL to the API.|
+|string|$api_token|A token for an authorized user|
+|[User](#request-gogsapi)|$owner|The owner of the repo|
+|string|$name|The repo name|
+---
+
+
+##### set_scope `Gogs\API\Request\Repo`
+```php
+protected function set_scope(string $method);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$method|Method type, e.g "get"|
+
+Returns: bool
+
+Throws: 
+
+* [RequestErrorException](#requesterrorexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\RequestErrorException")
+
+---
+
+
+##### json_set_property `Gogs\API\Request\Repo`
+```php
+protected function json_set_property(mixed $obj);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$obj|*None*|
+
+Returns: [true](#true-gogsapirequest) ***v*** array
+
+---
+
+
+##### search `Gogs\API\Request\Repo`
+```php
+public function search(string $q);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$q|*None*|
+---
+
+
+##### create `Gogs\API\Request\Repo`
+```php
+public function create(... $args);
+```
+ Create a new repo
+
+Valid paramters:
+
+ 1. name
+ 2. description
+ 3. private (default: false)
+ 4. auto_init (default: false)
+ 5. gitignore
+ 6. license
+ 7. readme (default: "Default")
+
+  This reflects the API v1 documentation, but is in an order
+  where the required fields are first.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|[...](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list)|$args|Arguments required by create.|
+
+Returns: bool
+
+---
+
+
+### Repos `Gogs\API\Request`
+
+
+* Class extends [Gogs\API\Request\Collection](#collection-gogsapirequest)
+* Class implements
+	* [Gogs\Lib\ArrayIterator](#arrayiterator-gogslib)
+	* [Gogs\API\Request\RequestInterface](#requestinterface-gogsapirequest)
+
+Repos is a collection of repos.
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[__construct](#__construct-gogsapirequestrepos)||public| Initialize a repos collection|
+|[set_scope](#set_scope-gogsapirequestrepos)|bool|protected| |
+|[create](#create-gogsapirequestrepos)|bool|public| |
+|[search](#search-gogsapirequestrepos)|[Collection](#collection-gogslib)|public| Searches for a repo.|
+|[json_set_property](#json_set_property-gogsapirequestrepos)|[true](#true-gogsapirequest) ***v*** array|protected| |
+
+#### Method details
+
+##### __construct `Gogs\API\Request\Repos`
+```php
+public function __construct(string $api_url, string $api_token, User $owner = null);
+```
+ Initialize a repos collection
+
+If owner is not set it will query the whole
+repo archive on Gogs.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$api_url|The URL to the API.|
+|string|$api_token|A token for an authorized user|
+|[User](#request-gogsapi)|$owner|The owner of the collection|
+---
+
+
+##### set_scope `Gogs\API\Request\Repos`
+```php
+protected function set_scope(string $method);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$method|Method type, e.g "get"|
+
+Returns: bool
+
+---
+
+
+##### create `Gogs\API\Request\Repos`
+```php
+public function create(... $args);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|[...](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list)|$args|Arguments required by create.|
+
+Returns: bool
+
+---
+
+
+##### search `Gogs\API\Request\Repos`
+```php
+public function search(array $params = array());
+```
+ Searches for a repo.
+
+If the owner is specified the search will be
+limited to the actual user.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|array|$params|Parameters|
+
+Returns: [Collection](#collection-gogslib)
+
+---
+
+
+##### json_set_property `Gogs\API\Request\Repos`
+```php
+protected function json_set_property(mixed $obj);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$obj|*None*|
+
+Returns: [true](#true-gogsapirequest) ***v*** array
+
+---
+
+
+### User `Gogs\API\Request`
+
+
+* Class extends [Gogs\API\Request\Base](#base-gogsapirequest)
+* Class implements[Gogs\API\Request\RequestInterface](#requestinterface-gogsapirequest)
+
+Stores user data and methods related to a single user.
+
+By now the following are supported:
+
+ * GET `/user`
+ * GET `/users/username`
+ * POST `/admin/users` (**Requires** admin rights. Curl will throw NotAuthorized exception if not).
+ * DELETE `/admin/users` (**Requires** admin rights. Curl will throw NotAuthorized exception if not).
+
+A user can also list it's repos and organizations.
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[__construct](#__construct-gogsapirequestuser)||public| Initialize an user object.|
+|[set_scope](#set_scope-gogsapirequestuser)|bool|protected| |
+|[search](#search-gogsapirequestuser)||public| |
+|[authenticated](#authenticated-gogsapirequestuser)|bool|public| Returns if the user is the authenticated user.|
+|[repos](#repos-gogsapirequestuser)|[Repos](#repos-gogsapirequest)|public| Returns every repo under user.|
+|[repo](#repo-gogsapirequestuser)|[Repo](#repo-gogsapirequest)|public| Return a single repo.|
+|[organizations](#organizations-gogsapirequestuser)|[Orgs](#orgs-gogsapirequest)|public| Return every organization under user.|
+|[organization](#organization-gogsapirequestuser)|[Org](#org-gogsapirequest)|public| Return a single organization.|
+|[create](#create-gogsapirequestuser)|bool|public| Create a new user.|
+|[json_set_property](#json_set_property-gogsapirequestuser)|[true](#true-gogsapirequest) ***v*** array|protected| |
+
+#### Method details
+
+##### __construct `Gogs\API\Request\User`
+```php
+public function __construct(string $api_url, string $api_token, string $user = "");
+```
+ Initialize an user object.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$api_url|The URL to the API.|
+|string|$api_token|A token for an authorized user|
+|string|$user|The username. "Empty" or "me" will return authenticated user|
+---
+
+
+##### set_scope `Gogs\API\Request\User`
+```php
+protected function set_scope(string $method);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$method|Method type, e.g "get"|
+
+Returns: bool
+
+Throws: 
+
+* [InvalidMethodRequest](#invalidmethodrequest-gogsapirequestexception "Exception: Gogs\API\Request\Exception\InvalidMethodRequest")
+* [RequestErrorException](#requesterrorexception-gogsapirequestexception "Exception: Gogs\API\Request\Exception\RequestErrorException")
+
+---
+
+
+##### search `Gogs\API\Request\User`
+```php
+public function search(string $q);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$q|*None*|
+---
+
+
+##### authenticated `Gogs\API\Request\User`
+```php
+public function authenticated();
+```
+ Returns if the user is the authenticated user.
+
+
+Returns: bool
+
+---
+
+
+##### repos `Gogs\API\Request\User`
+```php
+public function repos();
+```
+ Returns every repo under user.
+
+
+Returns: [Repos](#repos-gogsapirequest)
+
+---
+
+
+##### repo `Gogs\API\Request\User`
+```php
+public function repo(string $name);
+```
+ Return a single repo.
+
+Note: This will also load the repo.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$name|Repo name|
+
+Returns: [Repo](#repo-gogsapirequest)
+
+---
+
+
+##### organizations `Gogs\API\Request\User`
+```php
+public function organizations();
+```
+ Return every organization under user.
+
+
+Returns: [Orgs](#orgs-gogsapirequest)
+
+---
+
+
+##### organization `Gogs\API\Request\User`
+```php
+public function organization(string $name);
+```
+ Return a single organization.
+
+Note: This will also load the repo.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$name|Organization name|
+
+Returns: [Org](#org-gogsapirequest)
+
+---
+
+
+##### create `Gogs\API\Request\User`
+```php
+public function create(... $args);
+```
+ Create a new user.
+
+Valid parameters
+
+ 1. username
+ 2. email
+ 3. source_id
+ 4. login_name
+ 5. password
+ 6. send_notify
+
+This reflects the API v1 documentation, but is in an order
+where the required fields are first.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|[...](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list)|$args|Arguments required by create.|
+
+Returns: bool
+
+---
+
+
+##### json_set_property `Gogs\API\Request\User`
+```php
+protected function json_set_property(mixed $obj);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$obj|*None*|
+
+Returns: [true](#true-gogsapirequest) ***v*** array
+
+---
+
+
+### Users `Gogs\API\Request`
+
+
+* Class extends [Gogs\API\Request\Collection](#collection-gogsapirequest)
+* Class implements
+	* [Gogs\Lib\ArrayIterator](#arrayiterator-gogslib)
+	* [Gogs\API\Request\RequestInterface](#requestinterface-gogsapirequest)
+
+Returns one or more users in the Gogs installation,
+depending on the called method.
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[set_scope](#set_scope-gogsapirequestusers)|bool|protected| Set the scope for the request methods accepted by the child.|
+|[create](#create-gogsapirequestusers)|bool|public| Returns a new user object. If argumentsis specified the user will be "created".|
+|[get](#get-gogsapirequestusers)|object|public| Get object references by identifier.|
+|[search](#search-gogsapirequestusers)|[Collection](#collection-gogslib)|public| Search for an object.|
+|[json_set_property](#json_set_property-gogsapirequestusers)|[true](#true-gogsapirequest) ***v*** array|protected| Set properties for the current object.|
+
+#### Method details
+
+##### set_scope `Gogs\API\Request\Users`
+```php
+protected function set_scope(string $method);
+```
+ Set the scope for the request methods accepted by the child.
+
+This can be
+ * `get`,
+ * `search`,
+ * `delete` etc.
+
+ Must return true if scope exists of false otherwise. Methods
+ the calls this will throw an exception if not true is returned.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$method|Method type, e.g "get"|
+
+Returns: bool
+
+---
+
+
+##### create `Gogs\API\Request\Users`
+```php
+public function create(... $args);
+```
+ Returns a new user object. If arguments
+is specified the user will be "created".
+
+The arguments can be left out to "create" the
+user through the user object iteself.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|[...](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list)|$args|Arguments required by create.|
+
+Returns: bool
+
+---
+
+
+##### get `Gogs\API\Request\Users`
+```php
+public function get(string $s = "");
+```
+ Get object references by identifier.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$s|The idientifier to look up|
+
+Returns: object
+
+---
+
+
+##### search `Gogs\API\Request\Users`
+```php
+public function search(array $params = array());
+```
+ Search for an object.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|array|$params|Parameters|
+
+Returns: [Collection](#collection-gogslib)
+
+---
+
+
+##### json_set_property `Gogs\API\Request\Users`
+```php
+protected function json_set_property(mixed $obj);
+```
+ Set properties for the current object.
+
+Each child class must implement this to set its data. Will
+be called by methods such as `load` and from collection
+classes.
+
+Will return true/false for singel objects but an array on collections.
+The array will contain the newly inserted elements. This to prevent
+additional iterations.
+
+This method should also set loaded to true or false, depending
+on success or failure.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$obj|*None*|
+
+Returns: [true](#true-gogsapirequest) ***v*** array
+
+---
+
+## Interfaces
+
+### RequestInterface `Gogs\API\Request`
+
+Request interface, used by any kind of request object.
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[load](#load-gogsapirequestrequestinterface)|object|public| Load object.|
+|[get](#get-gogsapirequestrequestinterface)|object|public| Get by identifier|
+|[create](#create-gogsapirequestrequestinterface)|bool|public| Create object|
+|[patch](#patch-gogsapirequestrequestinterface)|bool|public| Patch (update) object|
+|[delete](#delete-gogsapirequestrequestinterface)|bool|public| Delete object|
+
+#### Method details
+
+##### load `Gogs\API\Request\RequestInterface`
+```php
+public function load(bool $force = false);
+```
+ Load object.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|bool|$force|Force update, default: true|
+
+Returns: object
+
+---
+
+
+##### get `Gogs\API\Request\RequestInterface`
+```php
+public function get(string $s);
+```
+ Get by identifier
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$s|The idientifier to look up|
+
+Returns: object
+
+---
+
+
+##### create `Gogs\API\Request\RequestInterface`
+```php
+public function create(... $args);
+```
+ Create object
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|[...](http://php.net/manual/en/functions.arguments.php#functions.variable-arg-list)|$args|Arguments required by create.|
+
+Returns: bool
+
+---
+
+
+##### patch `Gogs\API\Request\RequestInterface`
+```php
+public function patch();
+```
+ Patch (update) object
+
+
+Returns: bool
+
+---
+
+
+##### delete `Gogs\API\Request\RequestInterface`
+```php
+public function delete();
+```
+ Delete object
+
+
+Returns: bool
+
+---
+
+# Gogs\API\Request\Exception
+
+## Exceptions
+
+### InvalidMethodRequestException `Gogs\API\Request\Exception`
+
+
+* Class extends [Exception](https://www.google.no/search?q=Exception)
+
+Thrown whenever a class that inherits the base-class
+is used wrong (e.g tries to create on a loaded object)
+
+
+### NotImplementedException `Gogs\API\Request\Exception`
+
+
+* Class extends [BadMethodCallException](https://www.google.no/search?q=BadMethodCallException)
+
+Thrown when the requested method for a class isn't
+implemented.
+
+
+### RequestErrorException `Gogs\API\Request\Exception`
+
+
+* Class extends [Exception](https://www.google.no/search?q=Exception)
+
+Typically thrown when needed data to build the query
+is missing.
+
+
+### SearchParamException `Gogs\API\Request\Exception`
+
+
+* Class extends [Exception](https://www.google.no/search?q=Exception)
+
+Thrown when needed parameters for a search is missing.
+
+# Gogs\Lib
+
+## Classes
+
+### Collection `Gogs\Lib`
+
+
+* Class implements[Gogs\Lib\ArrayIterator](#arrayiterator-gogslib)
+
+Base class for collections. Implements basic
+functions and typically used to return collections
+which wont be a part of the "request package"
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[set](#set-gogslibcollection)||public| Set value(e) to the collection.|
+|[by_key](#by_key-gogslibcollection)|mixed|public| |
+|[all](#all-gogslibcollection)|array|public| |
+|[len](#len-gogslibcollection)|int|public| |
+|[next](#next-gogslibcollection)|mixed|public| |
+|[prev](#prev-gogslibcollection)|mixed|public| |
+|[current](#current-gogslibcollection)||public| |
+|[reset](#reset-gogslibcollection)|mixed|public| |
+
+#### Method details
+
+##### set `Gogs\Lib\Collection`
+```php
+public function set(mixed $val, mixed $key = null);
+```
+ Set value(e) to the collection.
+
+If the value is an array it will overwrite
+the whole object-array, aka everything.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$val|*None*|
+|mixed|$key|*None*|
+---
+
+
+##### by_key `Gogs\Lib\Collection`
+```php
+public function by_key(mixed $idx);
+```
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$idx|Index key.|
+
+Returns: mixed
+
+---
+
+
+##### all `Gogs\Lib\Collection`
+```php
+public function all();
+```
+
+Returns: array
+
+---
+
+
+##### len `Gogs\Lib\Collection`
+```php
+public function len();
+```
+
+Returns: int
+
+---
+
+
+##### next `Gogs\Lib\Collection`
+```php
+public function next();
+```
+
+Returns: mixed
+
+---
+
+
+##### prev `Gogs\Lib\Collection`
+```php
+public function prev();
+```
+
+Returns: mixed
+
+---
+
+
+##### current `Gogs\Lib\Collection`
+```php
+public function current();
+```
+---
+
+
+##### reset `Gogs\Lib\Collection`
+```php
+public function reset();
+```
+
+Returns: mixed
+
+---
+
+## Interfaces
+
+### ArrayIterator `Gogs\Lib`
+
+Interface to store one or more elements in array
+providing an iterator interface.
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[current](#current-gogslibarrayiterator)||public| Get current element in collection.|
+|[next](#next-gogslibarrayiterator)|mixed|public| Get next element in collection.|
+|[prev](#prev-gogslibarrayiterator)|mixed|public| Return previous element in collection.|
+|[reset](#reset-gogslibarrayiterator)|mixed|public| Reset collection (set array to head).|
+|[len](#len-gogslibarrayiterator)|int|public| Return collection size.|
+|[all](#all-gogslibarrayiterator)|array|public| Return the whole colection.|
+|[by_key](#by_key-gogslibarrayiterator)|mixed|public| Get element by index key.|
+
+#### Method details
+
+##### current `Gogs\Lib\ArrayIterator`
+```php
+public function current();
+```
+ Get current element in collection.
+
+---
+
+
+##### next `Gogs\Lib\ArrayIterator`
+```php
+public function next();
+```
+ Get next element in collection.
+
+
+Returns: mixed
+
+---
+
+
+##### prev `Gogs\Lib\ArrayIterator`
+```php
+public function prev();
+```
+ Return previous element in collection.
+
+
+Returns: mixed
+
+---
+
+
+##### reset `Gogs\Lib\ArrayIterator`
+```php
+public function reset();
+```
+ Reset collection (set array to head).
+
+
+Returns: mixed
+
+---
+
+
+##### len `Gogs\Lib\ArrayIterator`
+```php
+public function len();
+```
+ Return collection size.
+
+
+Returns: int
+
+---
+
+
+##### all `Gogs\Lib\ArrayIterator`
+```php
+public function all();
+```
+ Return the whole colection.
+
+
+Returns: array
+
+---
+
+
+##### by_key `Gogs\Lib\ArrayIterator`
+```php
+public function by_key(mixed $idx);
+```
+ Get element by index key.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|mixed|$idx|Index key.|
+
+Returns: mixed
+
+---
+
+# Gogs\Lib\Curl
+
+## Traits
+
+### Client `Gogs\Lib\Curl`
+
+A trait used for every class referencing the api-url and token.
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[method](#method-gogslibcurlclient)|int|protected| Initializes a curl request of different kinds, dependingon the specified method. This can be|
+|[authorized](#authorized-gogslibcurlclient)|bool|protected| Checks if the user is authorized for the scope. Shouldn'tbe used frequently. One test for one scope should be enough,but if you know for sure thats you're programming with theuse of an authorized user you should leave this and justhandle the NotAuthorizedExeption whenever thrown.|
+
+#### Method details
+
+##### method `Gogs\Lib\Curl\Client`
+```php
+protected function method(string $method, string $req, string $scope, array $params, bool $ret);
+```
+ Initializes a curl request of different kinds, depending
+on the specified method. This can be
+
+DELETE, PATCH, POST or GET. An unidentified value will
+become a GET-request.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$method|either DELETE, PATCH, POST, GET|
+|string|$req|&$req variable to store request body in|
+|string|$scope|scope within the API (e.g /user/repos)|
+|array|$params|parameters to pass|
+|bool|$ret|return transfer|
+
+Returns: int
+
+---
+
+
+##### authorized `Gogs\Lib\Curl\Client`
+```php
+protected function authorized(string $scope = "");
+```
+ Checks if the user is authorized for the scope. Shouldn't
+be used frequently. One test for one scope should be enough,
+but if you know for sure thats you're programming with the
+use of an authorized user you should leave this and just
+handle the NotAuthorizedExeption whenever thrown.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$scope|the scope, a relative uri.|
+
+Returns: bool
+
+Throws: 
+
+* [Not](#not-gogslibcurl "Exception: Gogs\Lib\Curl\Not")
+
+---
+
+# Gogs\Lib\Curl\Exception
+
+## Exceptions
+
+### HTTPUnexpectedResponse `Gogs\Lib\Curl\Exception`
+
+
+* Class extends [Exception](https://www.google.no/search?q=Exception)
+
+Defines an unexpected response.
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[__construct](#__construct-gogslibcurlexceptionhttpunexpectedresponse)||public| Sets the exceptions.|
+|[__toString](#__tostring-gogslibcurlexceptionhttpunexpectedresponse)|string|public| Visual representation of the exception.|
+|[getResponse](#getresponse-gogslibcurlexceptionhttpunexpectedresponse)|string|public| Get the actual response from the body or the request.|
+
+#### Method details
+
+##### __construct `Gogs\Lib\Curl\Exception\HTTPUnexpectedResponse`
+```php
+public function __construct(string $message, int $code = -1, Exception $previous = null);
+```
+ Sets the exceptions.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$message|*None*|
+|int|$code|*None*|
+|Exception|$previous|*None*|
+---
+
+
+##### __toString `Gogs\Lib\Curl\Exception\HTTPUnexpectedResponse`
+```php
+public function __toString();
+```
+ Visual representation of the exception.
+
+
+Returns: string
+
+---
+
+
+##### getResponse `Gogs\Lib\Curl\Exception\HTTPUnexpectedResponse`
+```php
+public function getResponse();
+```
+ Get the actual response from the body or the request.
+
+
+Returns: string
+
+---
+
+
+### NotAuthorizedException `Gogs\Lib\Curl\Exception`
+
+
+* Class extends [Gogs\Lib\Curl\Exception\HTTPUnexpectedResponse](#httpunexpectedresponse-gogslibcurlexception)
+
+When the request fails because of an unauthorized token,
+this is thrown instead.
+
+#### Methods
+
+|Name|Return|Access|Description|
+|:---|:---|:---|:---|
+|[__construct](#__construct-gogslibcurlexceptionnotauthorizedexception)||public| Sets the exceptions.|
+
+#### Method details
+
+##### __construct `Gogs\Lib\Curl\Exception\NotAuthorizedException`
+```php
+public function __construct(string $message, int $code = 401, Exception $previous = null);
+```
+ Sets the exceptions.
+
+
+Parameters
+
+| Type | Variable | Description |
+|---|---|---|
+|string|$message|*None*|
+|int|$code|*None*|
+|Exception|$previous|*None*|
+---
+
+
+ - Genetated using Sami and the [Sami/Twig Markdown Extension](https://git.giaever.org/joachimmg/sami-markdown)
+

index.php

@@ -19,38 +19,52 @@ define('API_TOKEN', 'ccc9a0ea6fefa8df558f4994e8c8ada2efa97f12');
 try {
     $client =  new Gogs\API\Client(API_URL, API_TOKEN);
 
-    $users = $client->users()->search(array("name" => "bje007"));
-
     $me = $client->user()->load();
 
-    var_dump($me, $users);
-    
-    #try {
-    #    // Create new repo under authorized user
-    #    $repo = $me->repos()->new(
-    #        /*name*/        "gogs-php-api-client-test", 
-    #        /*desc*/        "Repository created from test file.",
-    #        /*private*/     false,
-    #        /*auto init*/   true,
-    #        /*git ignore*/  "Vim",
-    #        /*license*/     "MIT License"
-    #        /* default read me */
-    #    );
+    $user_search = $client->users()->search(array(
+        "name" => "tester2"
+    ));
+
+    if ($user_search->len() > 0)
+        echo " * Found user(s) " . var_export($user_search, true);
+    else
+        echo " * User 'tester2' not found"; 
+
+    try {
+
+        echo " * Creating new repo under autorized user: " . $me->username;
+        // Create new repo under authorized user
+        $repo = $me->repos()->create(
+            /*name*/        "gogs-php-api-client-test", 
+            /*desc*/        "Repository created from test file.",
+            /*private*/     false,
+            /*auto init*/   true,
+            /*git ignore*/  "Vim",
+            /*license*/     "MIT License"
+            /* default read me */
+        );
         
-    #   echo "New repo '" . $repo->rfull_name . "' created!\n";
+       echo "New repo '" . $repo->full_name . "' created!\n";
 
-    #} catch(\Lib\HTTPUnexpectedResponse $e) {
+    } catch(ApiException\HTTPUnexpectedResponse $e) {
 
-    #    // Repo exists, get it!
-    #    $repo = $me->repo("gogs-php-api-client-test");
+        // Repo exists, get it!
+        $repo = $me->repo("gogs-php-api-client-test");
 
-    #    // Delete it (it will now be created on reload!)
-    #    $repo->delete();
+        // Delete it (it will now be created again on reload!)
+        $repo->delete();
 
-    #    echo "Repo '" . $repo->rfull_name . "' deleted\n";
-    #}
+        echo "Repo '" . $repo->full_name . "' deleted\n";
+    }
+
+    // Loop through organizations
+    foreach($me->organizations()->load()->all() as $org)
+        var_dump("ORG", $org->username);
 
-    //$orgs = $me->organizations();
+    echo sprintf(
+        "org->username: %s\norg->org_username: %s\norg->user_username: %s\n",
+        $org->username, $org->org_username, $org->user_username
+    ); 
 
     // Requires ADMIN rights to the authenticated user
     #try {
@@ -98,10 +112,10 @@ try {
     #    echo "User '" . $user->uusername . "' deleted!\n";
     #}
 
-    var_dump($me->organizations()->load()->all()["FlyViking"]->repos()->create(
+    /*var_dump($me->organizations()->load()->all()["FlyViking"]->repos()->create(
         "test-repo-for-org",
         "this is desc."
-    ));
+    ));*/
 
 } catch (ApiException\NotAuthorizedException $e) {
     die("NOT AUTH: " . $e->getMessage());

sami-markdown

@@ -1 +1 @@
-Subproject commit 5ad6e981d28c8a4ec452bf79527357fdd221a0c7
+Subproject commit ea769268e2a2cc9598f83cf8f46484b7ec87d67f

src/API/Client.php

@@ -6,7 +6,7 @@ namespace Gogs\API {
      * Gogs API client. 
      *
      * This class initially provide the programmer with a starting 
-     * point and a kind of an interface to start from, to keep 
+     * point (a kind of an "interface" to start from), to keep 
      * track of the context when going from a user, to a repo,
      * organization etc.
      *
@@ -21,7 +21,6 @@ namespace Gogs\API {
         /** 
          * @param string $api_url The base URL for the Gogs API (e.g https://git.domain.tld/api/v1) 
          * @param string $api_token The token for an authorized user to query Gogs API.
-         * @return null
          */
         public function __construct(string $api_url, string $api_token) {
             $this->url = $api_url;
@@ -29,7 +28,7 @@ namespace Gogs\API {
         }
 
         /** 
-         * Returns a Request\Users object to fetch users from the
+         * Returns a Request\Users to fetch users from the
          * Gogs installation. 
          *
          * @see Request\Users class to understand usage (e.g ->load() to fetch all, 
@@ -70,11 +69,6 @@ namespace Gogs\API {
         public function repos() {
             return new Request\Repos($this->url, $this->token);
         }
-
-        /** 
-         * @return null
-         */
-        public function __destruct() {}
     }
 }
 ?>

src/API/Request/Base.php

@@ -10,10 +10,13 @@ namespace Gogs\API\Request {
      * and get the cURL functionality.
      *
      * @deprecated since 0.1, to be removed in 3.0
+     * @author Joachim M. Giaever (joachim[]giaever.org)
      * @abstact
      */
     abstract class Base implements RequestInterface {
 
+        private $tag;
+
         protected $loaded = false;
         protected $scope;
 
@@ -30,6 +33,7 @@ namespace Gogs\API\Request {
         public function __construct(string $api_url, string $api_token) {
             $this->url = $api_url;
             $this->token = $api_token;
+            $this->tag = strtolower(basename(str_replace("\\", "/", get_class($this))));
         }
 
         /**
@@ -50,6 +54,10 @@ namespace Gogs\API\Request {
             $jenc =  $this->mget($this->scope);
 
             $this->json_set_property($this->json_decode($jenc));
+            /*
+             * JSON set property should also do this, but
+             * to ensure its done, we'll also do it here
+             */
             $this->loaded = true;
 
             return $this;
@@ -107,7 +115,7 @@ namespace Gogs\API\Request {
          */
         public function get(string $s) {
             if (!$this->set_scope("get"))
-                throw new Exception\NotImplementedException("::get:: Not implemented for class");
+                throw new Exception\NotImplementedException("::get:: Not implemented for class '" . get_class($this) . "'");
 
             return null;
         }
@@ -120,6 +128,8 @@ namespace Gogs\API\Request {
          *
          * @param string $args yeah, well
          * @return true
+         * @throws Exception\InvalidMethodRequestException
+         * @throws Exception\NotImplementedException
          */
         public function create(...$args) {
 
@@ -127,7 +137,7 @@ namespace Gogs\API\Request {
                 throw new Exception\InvalidMethodRequestException("::create:: Cant create on an git-initialized object. Create new object.");
 
             if (!$this->set_scope("create"))
-                throw new Exception\NotImplementedException("::create:: Not implemented for class");
+                throw new Exception\NotImplementedException("::create:: Not implemented for class '" . get_class($this) . "'");
 
             $ret = $this->method_post(...$args);
 
@@ -148,17 +158,30 @@ namespace Gogs\API\Request {
                 throw new Exception\InvalidMethodRequestException("::patch:: Cant patch an git-uninitialized object. Load it first.");
 
             if (!$this->set_scope("patch"))
-                throw new Exception\NotImplementedException("::patch:: Not implemented for class");
+                throw new Exception\NotImplementedException("::patch:: Not implemented for class '" . get_class($this) . "'");
         }
 
+        /**
+         * Delete object.
+         *
+         * @throws Exception\NotImplementedException
+         */
         public function delete() {
             if (!$this->set_scope("delete"))
-                throw new Exception\NotImplementedException("::delete:: Not implemented for class");
+                throw new Exception\NotImplementedException("::delete:: Not implemented for class '" . get_class($this) . "'");
 
             return $this->method_delete();
         }
 
-        protected function json_decode(string $jenc) {
+        /** 
+         * Decode JSON-string.
+         *
+         * Will ensure that there weren't any errors by calling `$this->json_error`.
+         *
+         * @param string $jenc Encoded JSON string
+         * @return object
+         */
+        final protected function json_decode(string $jenc) {
             $obj = json_decode($jenc);
 
             $this->json_error();
@@ -166,7 +189,15 @@ namespace Gogs\API\Request {
             return $obj;
         }
 
-        protected function json_encode(iterable $jdec) {
+        /** 
+         * Encode JSON-object/array.
+         *
+         * Will ensure that there weren't any errors by calling `$this->json_error`.
+         *
+         * @param iterable $jdec JSON-data
+         * @return string
+         */
+        final protected function json_encode(iterable $jdec) {
             $jenc = json_encode($jdec);
 
             $this->json_error();
@@ -174,15 +205,239 @@ namespace Gogs\API\Request {
             return $jenc;
         }
 
-        protected function json_error() {
+        /** 
+         * Check for errors on encoding/decoding.
+         *
+         * @throws Exception\RequestErrorException
+         */
+        final protected function json_error() {
             if (($err = json_last_error()) != JSON_ERROR_NONE)
                 throw new Exception\RequestErrorException(json_last_error_msg(), $err);
         }
 
+        /** 
+         * Get basename of a class (remove namespace).
+         * 
+         * @param string $class The FQN
+         * @return string
+         */
+        private function basename_class(string $class) {
+            return strtolower(basename(str_replace("\\", "/", $class)));
+        }
+
+        /** 
+         * Return basename of parent class.
+         * 
+         * @return string
+         */
+        private function get_parent() {
+            $parent = get_parent_class($this);
+
+            if ($parent != __CLASS__)
+                return $this->basename_class($parent);
+
+            return null;
+        }
+
+        /**
+         * Get property key by name.
+         *
+         * Classes sets property from json directly, but they are
+         * named within the class by `classname_propertyname`. This
+         * method returns the key name.
+         *
+         * @param string $name Name of the key
+         * @param bool $parent Get key in parent
+         * @return string
+         */
+        final private function key(string $name, bool $parent = false) {
+
+            $tag = sprintf("%s_", $this->tag);
+
+            if (strpos($name, $tag) === 0) {
+                if ($parent && !empty($ptag = $this->get_parent()))
+                    return sprintf("%s_%s", $ptag, substr($name, strlen($tag)));
+
+                return $name . "?";
+            }
+
+            if ($parent && !empty($ptag = $this->get_parent()))
+                return sprintf("%s_%s", $ptag, $name);
+
+            return $tag . $name;
+        }
+
+        /** 
+         * Checks if the property (key) exists within self
+         * or parent class.
+         *
+         * Returns the actual key if it does. A class key (aka property)
+         * start with the tag `classname_` followed by property name, 
+         * reflecting the JSON-object, and can be reached by
+         *
+         *  * `$class->parameter`,
+         *  * `$class->classname_parameter` or alternatively (for classes that inherits another class).
+         *  * `$class->parentclassname_parameter`.
+         *
+         *  If a class override a parent class with the same parameter,
+         *  the class's own parameter will be favoured.
+         *
+         * As this is public properties this wont be an security issue;
+         * 
+         * @param $name Name of the key.
+         * @return string|false False on failure
+         */
+        final protected function property_exists($name) {
+            if (property_exists($this, $key = $this->key($name)))
+                return $key;
+
+            if (property_exists($this, $key = $this->key($name, true)))
+                return $key;
+
+            return false;
+        }
+
+        /** 
+         * Get property by name.
+         *
+         * Checks both self and parent for the property.
+         *
+         * Returns the value if property exists, otherwise an `E_USER_NOTICE`
+         * is triggered.
+         *
+         * @param string $name 
+         * @return mixed|null Null when unknown
+         */
+        final public function __get(string $name) {
+
+            $key = $this->property_exists($name);
+
+            if ($key)
+                return $this->{$key};
+
+            $trace = debug_backtrace();
+
+            trigger_error(
+                sprintf(
+                    "Undefined property '%s' {%s} in '%s' on line %s. Neither does its parent '%s'",
+                    $name,
+                    $this->key($name),
+                    $trace[0]["file"],
+                    $trace[0]["line"],
+                    $this->basename_class(get_parent_class($this))
+                ),
+                E_USER_NOTICE
+            ); 
+
+            return null;
+        }
+
+        /** 
+         * Set property by name.
+         *
+         * Checks both self and parent for the property.
+         *
+         * Returns the value if property exists, otherwise an `E_USER_NOTICE`
+         * is triggered.
+         *
+         * @param string $name Property name
+         * @param mixed $value Property value
+         * @return mixed|null Null when unknown
+         */
+        final public function __set(string $name, $value) {
+
+            $key = $this->property_exists($name);
+
+            if ($key)
+                return $this->{$key} = $value;
+
+            $trace = debug_backtrace();
+
+            trigger_error(
+                sprintf(
+                    "Undefined property '%s' {%s} in '%s' on line %s. Neither does its parent '%s'",
+                    $name,
+                    $this->key($name),
+                    $trace[0]["file"],
+                    $trace[0]["line"],
+                    $this->basename_class(get_parent_class($this))
+                ),
+                E_USER_NOTICE
+            ); 
+
+            return null;
+        }
+
+        /** 
+         * Checks if property is set.
+         *
+         * Checks both self and parent for property.
+         *
+         * Triggers E_USER_NOTICE if property is unknown.
+         *
+         * @param string $name Property name
+         * @return bool
+         */
+        final public function __isset(string $name) {
+
+            $key = $this->property_exists($name);
+
+            if ($key)
+                return isset($this->{$key});
+
+            $trace = debug_backtrace();
+
+            trigger_error(
+                sprintf(
+                    "Undefined property '%s' {%s} in '%s' on line %s. Neither does its parent '%s'",
+                    $name,
+                    $this->key($name),
+                    $trace[0]["file"],
+                    $trace[0]["line"],
+                    $this->basename_class(get_parent_class($this))
+                ),
+                E_USER_NOTICE
+            ); 
+
+            return false;
+        }
+
+        /** 
+         * Set properties for the current object.
+         *
+         * Each child class must implement this to set its data. Will
+         * be called by methods such as `load` and from collection
+         * classes.
+         *
+         * Will return true/false for singel objects but an array on collections.
+         * The array will contain the newly inserted elements. This to prevent
+         * additional iterations.
+         *
+         * This method should also set loaded to true or false, depending
+         * on success or failure.
+         *
+         * @see Collection
+         * @param mixed $obj
+         * @return true|array
+         */
         abstract protected function json_set_property($obj);
+
+        /** 
+         * Set the scope for the request methods accepted by the child.
+         *
+         * This can be
+         *  * `get`,
+         *  * `search`,
+         *  * `delete` etc.
+         *
+         *  Must return true if scope exists of false otherwise. Methods
+         *  the calls this will throw an exception if not true is returned.
+         *
+         * @param string $method Method type, e.g "get"
+         * @return bool
+         */
         abstract protected function set_scope(string $method);
 
-        public function __destruct() {}
     }
 
 }

src/API/Request/Collection.php

@@ -2,51 +2,111 @@
 
 namespace Gogs\API\Request {
 
+    /** 
+     * Collection is a collection of data of one type.
+     *
+     * @see Users
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     * @version 0.1
+     */
     abstract class Collection extends Base implements \Gogs\Lib\ArrayIterator {
         private $objs = array();
 
+        /**
+         * Add an object to the collection.
+         *
+         * When adding a key the object will be stored
+         * on the particual key, also overwriting existing data.
+         *
+         * @param mixed $obj Element to store
+         * @param mixed $key Index key to store on
+         * @return mixed|int The index key. If key is null the returned value will be an integer.
+         */
         public function add($obj, $key = null) {
             if (!isset($key))
                 array_push($this->objs, $obj);
             else
                 $this->objs[$key] = $obj;
+
+            return $key == null ? $this->len - 1 : $key;
         }
 
-        public function remove($any) {
+        /** 
+         * Remove an element in collection.
+         *
+         * The function will first look for the element as a
+         * index key, but if its not found it will look for the
+         * element as a value.
+         *
+         * Deep functions only when the value is given and not the key.
+         *
+         * @param mixed $any Index key or element value
+         * @param bool $deep Delete every item and not just the first 
+         * @return bool
+         */
+        public function remove($any, bool $deep = true) {
             if (isset($this->objs[$any])) {
                 unset($this->objs[$any]);
                 return true;
             } else if (in_array($any, $this->objs)) {
                 $key = array_search($any, $this->objs, true);
-                return $this->remove($key);
+
+                // No need to add deep ($key deletion)
+                $val = $this->remove($key);
+
+                if ($val && $deep) // Delete every object
+                    $this->remove($any, $deep);
+
+                return $val;
             }
             return false;
         }
 
+        /**
+         * @see \Gogs\Lib\ArrayIterator
+         */
         public function all() {
             return $this->objs;
         }
 
+        /**
+         * @see \Gogs\Lib\ArrayIterator
+         */
         public function len() {
             return count($this->objs);
         }
 
+        /**
+         * @see \Gogs\Lib\ArrayIterator
+         */
         public function by_key($idx) {
             return isset($this->objs[$idx]) ? $this->objs[$idx] : false;
         }
 
+        /**
+         * @see \Gogs\Lib\ArrayIterator
+         */
         public function next() {
             return next($this->objs);
         }
 
+        /**
+         * @see \Gogs\Lib\ArrayIterator
+         */
         public function prev() {
             return prev($this->objs);
         }
 
+        /**
+         * @see \Gogs\Lib\ArrayIterator
+         */
         public function current() {
             return current($this->objs);
         }
 
+        /**
+         * @see \Gogs\Lib\ArrayIterator
+         */
         public function reset() {
             return reset($this->objs);
         }
@@ -55,7 +115,7 @@ namespace Gogs\API\Request {
          * Search for an object.
          *
          * @param array $params Parameters
-         * @return Gogs\Lib\Collection
+         * @return \Gogs\Lib\Collection
          */
         abstract public function search(array $params = array());
     }

src/API/Request/Exception/InvalidMethodRequestException.php

@@ -1,5 +1,12 @@
 <?php
 namespace Gogs\API\Request\Exception {
+    
+    /** 
+     * Thrown whenever a class that inherits the base-class
+     * is used wrong (e.g tries to create on a loaded object)
+     *
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     */
     class InvalidMethodRequestException extends \Exception {};
 }
 ?>

src/API/Request/Exception/NotImplementedException.php

@@ -1,5 +1,11 @@
 <?php
 namespace Gogs\API\Request\Exception {
+    /** 
+     * Thrown when the requested method for a class isn't
+     * implemented.
+     *
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     */
     class NotImplementedException extends \BadMethodCallException{}
 }
 ?>

src/API/Request/Exception/RequestErrorException.php

@@ -1,5 +1,11 @@
 <?php
 namespace Gogs\API\Request\Exception {
+    /** 
+     * Typically thrown when needed data to build the query
+     * is missing.
+     *
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     */
     class RequestErrorException extends \Exception {};
 }
 ?>

src/API/Request/Exception/SearchParamException.php

@@ -1,5 +1,10 @@
 <?php
 namespace Gogs\API\Request\Exception {
+    /** 
+     * Thrown when needed parameters for a search is missing.
+     *
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     */
     class SearchParamException extends \Exception {};
 }
 ?>

src/API/Request/Org.php

@@ -2,43 +2,90 @@
 
 namespace Gogs\API\Request {
 
+    /** 
+     * Stores data and methods related to a single organization.
+     *
+     * By now the following are supported:
+     *
+     *  * GET `/orgs/username`
+     *  * POST `/admin/users/username/orgs` (**Requires** admin rights. Curl will throw NotAuthorized exception if not).
+     *
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     * @version 0.1
+     */
     final class Org extends User {
-        public $udescription;
-        public $uwebsite;
-        public $ulocation;
+        public $org_description;
+        public $org_website;
+        public $org_location;
 
         private $owner;
 
-        public function __construct(string $api_url, string $api_token, string $oname = null, User $owner = null) {
-            $this->ousername = $oname;
-            $this->owner = $owner;
+        /**
+         * Initialize an organization.
+         *
+         * @param string $api_url The api-url
+         * @param string $api_token The api-token
+         * @param User $owner The owner of the organization
+         * @param string $oname Organization name
+         */
+        public function __construct(string $api_url, string $api_token, User $owner = null, string $oname = null)  {
             parent::__construct($api_url, $api_token);
+            $this->username = $oname;
+            $this->owner = $owner;
         }
 
+        /** 
+         * @see Base
+         * @throws Exception\InvalidMethodRequestException when owner is not set
+         * @throws Exception\RequestErrorException when missing organization data
+         */
         protected function set_scope(string $method) {
             switch ($method) {
             case "create":
                 if ($this->owner == null)
                     throw new Exception\InvalidMethodRequestException("Cant create organization without a related User");
 
-                $this->scope = "/admin/users/" . $this->owner->uusername . "/orgs";
+                $this->scope = "/admin/users/" . $this->owner->username . "/orgs";
                 return true;
             case "get":
-                $this->scope = "/orgs/" . $this->uusername;
+                if (!$this->username)
+                    throw new Exception\RequestErrorException("Missing organization-data 'username'.");
+
+                $this->scope = "/orgs/" . $this->username;
                 return true;
             }
         }
 
+        /** 
+         * @see Base
+         */
         public function search(string $q) {
-            $searchable = sprintf("%s %s %s", $this->ufull_name, $this->uusername, $this->udescription);
+            $searchable = sprintf("%s %s %s", $this->full_name, $this->username, $this->description);
 
             return stripos($searchable, $q) !== false;
         }
 
+        /** 
+         * Create a new user
+         *
+         * Valid parameters:
+         *
+         *  1. username
+         *  2. full_name
+         *  3. description
+         *  4. website
+         *  5. location
+         *
+         *  This reflects the API v1 doc, but is in an order
+         *  where the required fields is first.
+         *
+         * @param ...$args The parameter values.
+         * @return  bool
+         */
         public function create(...$args) {
             $params = array(
                 "username" => isset($args[0]) && is_string($args[0]) ? $args[0] : null,
-                "ufull_name" => isset($args[1]) && is_string($args[1]) ? $args[1] : null,
+                "full_name" => isset($args[1]) && is_string($args[1]) ? $args[1] : null,
                 "description" => isset($args[2]) && is_string($args[2]) ? $args[2] : null,
                 "website" => isset($args[3]) && is_string($args[3]) ? $args[3] : null,
                 "location" => isset($args[4]) && is_string($args[4]) ? $args[4] : null

src/API/Request/Orgs.php

@@ -19,14 +19,14 @@ namespace Gogs\API\Request {
         protected function set_scope(string $method) {
             switch ($method) {
             case "get":
-                $this->scope = ($this->owner == null || $this->owner->authenticated() ? "/user" : "/users/" . $this->owner->uusername) . "/orgs";
+                $this->scope = ($this->owner == null || $this->owner->authenticated() ? "/user" : "/users/" . $this->owner->username) . "/orgs";
                 return true;
             }
         }
 
         public function create(...$args) {
 
-            $org = new Org($this->url, $this->token, null, $this->owner);
+            $org = new Org($this->url, $this->token, $this->owner);
 
             if (count($args) > 0)
                 $org->create(...$args);
@@ -53,7 +53,7 @@ namespace Gogs\API\Request {
             if (($org = $this->by_key($s)))
                 return $org;
 
-            return new Org($this->url, $this->token, $s, $this->owner);
+            return new Org($this->url, $this->token, $this->owner, $s);
         }
 
         /**
@@ -71,6 +71,7 @@ namespace Gogs\API\Request {
          *
          * @param array $params
          * @return CollectionResult
+         * @throws Exception\SearchParamException on missing parameters
          */
         public function search(array $params = array()) {
 
@@ -94,12 +95,21 @@ namespace Gogs\API\Request {
             return $orgs;
         }
 
+        /** 
+         * @see Base
+         */
         protected function json_set_property($obj) {
+
+            $rnames = array();
+
             foreach($obj as $val) {
-                $org = new Org($this->url, $this->token, null, $this->owner);
+                $org = new Org($this->url, $this->token, $this->owner, $val->username);
                 $org->json_set_property($val);
                 $this->add($org, $val->username);
+                $rnames[] = $val->username;
             }
+
+            return $rnames;
         }
     }
 

src/API/Request/Repo.php

@@ -2,56 +2,93 @@
 
 namespace Gogs\API\Request {
 
+    /** 
+     * Stores data and methods related to a single repository.
+     *
+     * By now the following are supported:
+     *
+     *  * GET `/repos/username/reponame`
+     *  * POST `/user/repos`
+     *  * POST `/admin/user/username/repos`
+     *  * POST `/org/orgname/repos`
+     *  * DELETE `/repos/username/reponame`
+     *
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     */
     final class Repo extends Base {
         
-        public $rid;
-        public $rowner;
-        public $rname;
-        public $rfull_name;
-        public $rdescription;
-        public $rprivate;
-        public $rfork;
-        public $rparent;
-        public $rempty;
-        public $rmirror;
-        public $rsize;
-        public $rhtml_url;
-        public $rssh_url;
-        public $rclone_url;
-        public $rwebsite;
-        public $rstars_count;
-        public $rforks_count;
-        public $rwatchers_count;
-        public $ropen_issues_count;
-        public $rdefault_branch;
-        public $rcreated_at;
-        public $rupdated_at;
-        public $rpermissions;
-        public $radmin;
-        public $rpush;
-        public $rpull;
+        public $repo_id;
+        public $repo_owner;
+        public $repo_name;
+        public $repo_full_name;
+        public $repo_description;
+        public $repo_private;
+        public $repo_fork;
+        public $repo_parent;
+        public $repo_empty;
+        public $repo_mirror;
+        public $repo_size;
+        public $repo_html_url;
+        public $repo_ssh_url;
+        public $repo_clone_url;
+        public $repo_website;
+        public $repo_stars_count;
+        public $repo_forks_count;
+        public $repo_watchers_count;
+        public $repo_open_issues_count;
+        public $repo_default_branch;
+        public $repo_created_at;
+        public $repo_updated_at;
+        public $repo_permissions;
+        public $repo_admin;
+        public $repo_push;
+        public $repo_pull;
 
+        /**
+         * Initialize a repo object.
+         *
+         * Note that the owner can also be an Org (organization),
+         * or any other class that inherits a user.
+         *
+         * @param string $api_url The api-url
+         * @param string $api_token The api-token
+         * @param User $owner The owner of the repo
+         * @param string $name The repo name
+         */
         public function __construct(string $api_url, string $api_token, User $owner = null, string $name = null) {
-            $this->rowner = $owner;
-            $this->rname = $name;
             parent::__construct($api_url, $api_token);
+            $this->owner = $owner;
+            $this->name = $name;
         }
 
+        /** 
+         * @see Base
+         * @throws Exception\RequestErrorException on missing repo or user data
+         */
         protected function set_scope(string $method) {
             switch ($method) {
             case "create":
-                if ($this->rowner instanceof Org)
-                    $this->scope = "/org/" . $this->rowner->uusername . "/repos";
-                elseif ($this->rowner->authenticated())
+                if (!$this->owner->authenticated() && empty($this->owner->username))
+                    throw new Exception\RequestErrorException("Missing userdata of unauthorized user 'username'");
+
+                if ($this->owner instanceof Org)
+                    $this->scope = "/org/" . $this->owner->username . "/repos";
+                elseif ($this->owner->authenticated())
                     $this->scope = "/user/repos";
                 else
-                    $this->scope = "/admin/users/" . $this->rowner->uusername . "/repos";
+                    $this->scope = "/admin/users/" . $this->owner->username . "/repos";
                 break;
             case "delete":
-                $this->scope = "/repos/" . $this->rowner->uusername . "/" . $this->rname;
+                if (empty($this->owner->username))
+                    throw new Exception\RequestErrorException("Missing userdata 'username'");
+
+                $this->scope = "/repos/" . $this->owner->username . "/" . $this->name;
                 break;
             case "get":
-                $this->scope = "/repos/" . ($this->rowner ? $this->rowner->uusername . "/" . $this->rname : $this->rfull_name);
+                if (empty($this->owner->username) && empty($this->full_name))
+                    throw new Exception\RequestErrorException("Missing userdata 'username' and/or 'full_name'");
+
+                $this->scope = "/repos/" . ($this->owner ? $this->owner->username . "/" . $this->name : $this->full_name);
                 break;
             default:
                 return false;
@@ -60,13 +97,15 @@ namespace Gogs\API\Request {
             return true;
         }
 
+        /** 
+         * @see Base
+         */
         protected function json_set_property($obj) {
             foreach($obj as $key => $val) {
-                $key = 'r' . $key;
-                if (property_exists($this, $key)) {
+                if ($this->property_exists($key)) {
                     switch ($key) {
-                    case 'rowner':
-                        if (!$this->rowner) {
+                    case "owner":
+                        if (!$this->owner) {
                             $user = new User($this->url, $this->token);
                             $user->json_set_property($val);
                             $this->{$key} = $user;
@@ -78,14 +117,38 @@ namespace Gogs\API\Request {
                 }
             }
             $this->loaded = true;
+
+            return true;
         }
 
+        /** 
+         * @see Base
+         */
         public function search(string $q) {
-            $searchable = sprintf("%s %s", $this->rname, $this->rdescription);
+            $searchable = sprintf("%s %s", $this->name, $this->description);
 
             return stripos($searchable, $q) !== false;
         }
 
+        /** 
+         * Create a new repo
+         *
+         * Valid paramters:
+         *
+         *  1. name
+         *  2. description
+         *  3. private (default: false)
+         *  4. auto_init (default: false)
+         *  5. gitignore
+         *  6. license
+         *  7. readme (default: "Default")
+         *   
+         *   This reflects the API v1 documentation, but is in an order
+         *   where the required fields are first.
+         *
+         * @param ...$args The parameter values
+         * @return bool
+         */
         public function create(...$args) {
 
             $params = array(

src/API/Request/Repos.php

@@ -2,22 +2,40 @@
 
 namespace Gogs\API\Request {
 
+    /** 
+     * Repos is a collection of repos.
+     *
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     * @version 0.1
+     */
     final class Repos extends Collection {
-
         protected $owner;
 
+        /**
+         * Initialize a repos collection
+         *
+         * If owner is not set it will query the whole
+         * repo archive on Gogs.
+         *
+         * @param string $api_url The api-url
+         * @param string $api_token The api-token
+         * @param User $owner The owner of the collection
+         */
         public function __construct(string $api_url, string $api_token, User $owner = null) {
-            $this->owner = $owner;
             parent::__construct($api_url, $api_token);
+            $this->owner = $owner;
         }
 
+        /** 
+         * @see Base
+         */
         protected function set_scope(string $method) {
             switch ($method) {
             case "get":
                 if ($this->owner instanceof Org)
-                    $this->scope = "/orgs/" . $this->owner->uusername . "/repos";
+                    $this->scope = "/orgs/" . $this->owner->username . "/repos";
                 else
-                    $this->scope = ($this->owner == null || $this->owner->authenticated() ? "/user" : "/users/" . $this->owner->uusername ) . "/repos";
+                    $this->scope = ($this->owner == null || $this->owner->authenticated() ? "/user" : "/users/" . $this->owner->username ) . "/repos";
                 break;
             case "search":
                 $this->scope = "/repos/search";
@@ -29,6 +47,9 @@ namespace Gogs\API\Request {
             return true;
         }
 
+        /** 
+         * @see Collection
+         */
         public function create(...$args) {
 
             $repo = new Repo($this->url, $this->token, $this->owner);
@@ -39,6 +60,15 @@ namespace Gogs\API\Request {
             return $repo;
         }
 
+        /**
+         * Searches for a repo.
+         *
+         * If the owner is specified the search will be 
+         * limited to the actual user.
+         *
+         * @todo Should rewrite now since set_scope is now the deal
+         * @see Collection
+         */
         public function search(array $params = array()) {
             $scope = substr($this->scope, 1, strpos($this->scope, "/", 1)-1);
 
@@ -51,7 +81,7 @@ namespace Gogs\API\Request {
             }
 
             if (!isset($params["user"]))
-                $params["user"] = 0;
+                $params["user"] = isset($this->owner) ? $this->owner->id : 0;
 
             if (!isset($params["limit"]))
                 $params["limit"] = 10;
@@ -84,6 +114,9 @@ namespace Gogs\API\Request {
             return $repos;
         }
 
+        /** 
+         * @see Base
+         */
         protected function json_set_property($obj) {
             if (isset($obj->data))
                 return $this->json_set_property($obj->data);
@@ -95,7 +128,7 @@ namespace Gogs\API\Request {
                     $repo = new Repo($this->url, $this->token);
                     $repo->json_set_property($val);
                     $this->add($repo, $repo->rfull_name);
-                    array_push($rnames, $repo->rfull_name);
+                    $rnames[] = $repo->rfull_name;
                 }
             }
 

src/API/Request/User.php

@@ -2,56 +2,157 @@
 
 namespace Gogs\API\Request {
 
-    final class User extends Base {
+    /** 
+     * Stores user data and methods related to a single user.
+     *
+     * By now the following are supported:
+     *
+     *  * GET `/user`
+     *  * GET `/users/username`
+     *  * POST `/admin/users` (**Requires** admin rights. Curl will throw NotAuthorized exception if not).
+     *  * DELETE `/admin/users` (**Requires** admin rights. Curl will throw NotAuthorized exception if not).
+     *
+     * A user can also list it's repos and organizations.
+     * 
+     * @see Repos
+     * @see Orgs
+     * 
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     * @version 0.1
+     */
+    class User extends Base {
 
         private $authenticated;
-        public $uid;
-        public $ulogin;
-        public $ufull_name;
-        public $uemail;
-        public $uavatar_url;
-        public $uusername;
 
+        public $user_id;
+        public $user_login;
+        public $user_full_name;
+        public $user_email;
+        public $user_avatar_url;
+        public $user_username;
+
+        /**
+         * Initialize an user object.
+         *
+         * @param string $api_url The api-url
+         * @param string $api_token The api-token
+         * @param string $user The username. "Empty" or "me" will return authenticated user
+         */
         public function __construct(string $api_url, string $api_token, string $user = "") {
-            $this->uusername = (strlen($user) == 0 || $user == "me" ? "me" : $user);
-            $this->authenticated = $this->uusername == "me";
+            $this->authenticated = (strlen($user) == 0 || $user == "me");
             parent::__construct($api_url, $api_token);
         }
 
+        /** 
+         * @see Base
+         * @throws Exception\InvalidMethodRequest when create on loaded
+         * @throws Exception\RequestErrorException when userdata is missing 
+         */
         protected function set_scope(string $method) {
             switch($method) {
             case "create":
-
                 if ($this->loaded)
-                    throw new Exception\InvalidMethodRequest("Cannot create user of existing user");
+                    throw new Exception\InvalidMethodRequestException("Cannot create user of existing user");
 
                 $this->scope = "/admin/users";
-                
-                return true;
+                break;
             case "delete":
-                $this->scope = "/admin/users/" . $this->uusername;
-                return true;
+                if (!$this->username)
+                    throw new Exception\RequestErrorException("Missing userdata 'username'.");
+
+                $this->scope = "/admin/users/" . $this->username;
+                break;
+            case "get":
+                if (!$this->authenticated && empty($this->username))
+                    throw new Exception\RequestErrorException("Missing userdata 'username'.");
+
+                $this->scope = ($this->authenticated ? "/user" : "/users/" . $this->username);
+                break;
             default:
-                $this->scope = ($this->authenticated ? "/user" : "/users/" . $this->uusername);
+                return false;
             }
+
+            return true;
+        }
+
+        /** 
+         * @see Base
+         */
+        public function search(string $q) {
+            $searchable = sprintf("%s %s %s", $this->full_name, $this->username, $this->login);
+
+            return stripos($searchable, $q) !== false;
         }
 
+        /** 
+         * Returns if the user is the authenticated user.
+         *
+         * @return bool
+         */
         public function authenticated() {
             return $this->authenticated;
         }
 
+        /** 
+         * Returns every repo under user.
+         *
+         * @return Repos
+         */
         public function repos() {
             return new Repos($this->url, $this->token, $this);
         }
 
+        /** 
+         * Return a single repo.
+         *
+         * Note: This will also load the repo.
+         *
+         * @param string $name Repo name
+         * @return Repo
+         */
         public function repo(string $name) {
             return (new Repo($this->url, $this->token, $this, $name))->load();
         }
 
+        /** 
+         * Return every organization under user.
+         *
+         * @return Orgs
+         */
         public function organizations() {
             return new Orgs($this->url, $this->token, $this);
         }
 
+        /** 
+         * Return a single organization.
+         *
+         * Note: This will also load the repo.
+         * 
+         * @param string $name Organization name
+         * @return Org
+         */
+        public function organization(string $name) {
+            return (new Org($this->url, $this->token, $this, $name))->load();
+        }
+
+        /** 
+         * Create a new user.
+         *
+         * Valid parameters
+         * 
+         *  1. username
+         *  2. email
+         *  3. source_id
+         *  4. login_name
+         *  5. password
+         *  6. send_notify
+         *
+         * This reflects the API v1 documentation, but is in an order
+         * where the required fields are first.
+         *
+         * @param ...$args The parameter values.
+         * @return bool
+         */
         public function create(...$args) {
             $params = array(
                 "username" => isset($args[0]) && is_string($args[0]) ? $args[0] : null,
@@ -68,13 +169,19 @@ namespace Gogs\API\Request {
             parent::create($params);
         }
 
+        /** 
+         * @see Base
+         */
         protected function json_set_property($obj) {
+
             foreach ($obj as $key => $value) {
-                $key = 'u' . $key;
-                if (property_exists($this, $key))
+                if ($this->property_exists($key)) {
                     $this->{$key} = $value;
+                }
             }
-            $this->loaded = true;
+            $this->loaded = true;   
+
+            return true;
         }
     }
 

src/API/Request/Users.php

@@ -51,7 +51,7 @@ namespace Gogs\API\Request {
 
             $user = (new User($this->url, $this->token, $s))->load();
 
-            $this->add($user, $user->ulogin);
+            $this->add($user, $user->login);
 
             return $user;
         }
@@ -81,13 +81,19 @@ namespace Gogs\API\Request {
         }
 
         protected function json_set_property($obj) {
+            $rnames[] = array();
+
             if (isset($obj->data)) {
                 foreach($obj->data as $key => $val) {
                     $user = new User($this->url, $this->token, $val->login);
                     $user->json_set_property($val);
-                    $this->add($user, $user->ulogin);
+                    $this->add($user, $user->login);
+
+                    $rnames[] = $user->login;
                 }
             }
+
+            return $rnames;
         }
     }
 

src/Lib/ArrayIterator.php

@@ -1,11 +1,56 @@
 <?php namespace Gogs\Lib;
 
+/**
+ * Interface to store one or more elements in array
+ * providing an iterator interface.
+ */
 interface ArrayIterator {
+    /** 
+     * Get current element in collection.
+     * @return 
+     */
     public function current();
+
+    /** 
+     * Get next element in collection.
+     * 
+     * @return mixed
+     */
     public function next();
+
+    /** 
+     * Return previous element in collection.
+     * @return mixed
+     */
+    public function prev();
+
+    /**
+     * Reset collection (set array to head).
+     *
+     * @return mixed Returns first elements value.
+     */
     public function reset();
+    
+    /** 
+     * Return collection size.
+     *
+     * @return int
+     */
     public function len();
+    
+    /** 
+     * Return the whole colection.
+     *
+     * @return array
+     */
     public function all();
+    
+    /** 
+     * Get element by index key.
+     *
+     * @param mixed $idx Index key.
+     * @return mixed
+     */
     public function by_key($idx);
 }
 

src/Lib/Collection.php

@@ -2,9 +2,22 @@
 
 namespace Gogs\Lib {
 
+    /** 
+     * Base class for collections. Implements basic
+     * functions and typically used to return collections
+     * which wont be a part of the "request package"
+     *
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     */
     class Collection implements ArrayIterator {
         private $objs = array();
 
+        /**
+         * Set value(e) to the collection.
+         *
+         * If the value is an array it will overwrite
+         * the whole object-array, aka everything.
+         */
         public function set($val, $key = null) {
             if ($key == null && is_array($val))
                 $this->objs = $val;
@@ -14,26 +27,51 @@ namespace Gogs\Lib {
                 array_push($this->objs, $val);
         }
 
+        /** 
+         * @see ArrayIterator
+         */
         public function by_key($idx) {
             return isset($this->objs[$idx]) ? $this->objs[$idx] : false;
         }
 
+        /** 
+         * @see ArrayIterator
+         */
         public function all() {
             return $this->objs;
         }
 
+        /** 
+         * @see ArrayIterator
+         */
         public function len() {
             return count($this->objs);
         }
 
+        /** 
+         * @see ArrayIterator
+         */
         public function next() {
             return next($this->objs);
         }
 
+        /**
+         * @see ArrayIterator
+         */
+        public function prev() {
+            return prev($this->objs);
+        }
+
+        /** 
+         * @see ArrayIterator
+         */
         public function current() {
             return current($this->objs);
         }
 
+        /** 
+         * @see ArrayIterator
+         */
         public function reset() {
             return reset($this->objs);
         }

src/gpac.php

@@ -2,11 +2,13 @@
 
 define('GPAC_BASE_PATH', realpath(dirname(__FILE__)));
 
+// Autoload classes, withing the Gogs-prefix
 spl_autoload_register(function($class) {
 
     $prefix = "Gogs\\";
     $len = strlen($prefix);
 
+    // Checks if prefix starts with Gogs\
     if (strncmp($prefix, $class, $len) !== 0) {
         return;
     }
@@ -16,8 +18,7 @@ spl_autoload_register(function($class) {
         "\\", DIRECTORY_SEPARATOR, substr($class, $len)
     ) . ".php";
 
-    if (file_exists($file))
-        require_once $file;
+    require_once $file;
 });
 
 return;