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.
Name | Return | Access | Description |
---|---|---|---|
__construct | public | ||
users | Users | public | Returns a Request\Users to fetch users from theGogs installation. |
user | User | public | Get a single user from Gogs. |
repos | Repos | public | Returns an \Request\Repos to fetch repositorieson the Gogs installation. |
public function __construct(string $api_url, string $api_token);
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. |
public function users();
Returns a Request\Users to fetch users from the Gogs installation.
Returns: Users
public function user(string $name = "me");
Get a single user from Gogs.
Returns either
Parameters
Type | Variable | Description |
---|---|---|
string | $name | None |
Returns: User
public function repos();
Returns an \Request\Repos to fetch repositories on the Gogs installation.
Returns: Repos
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.
Name | Return | Access | Description |
---|---|---|---|
__construct | public | ||
load | object | final public | Load an object. |
method_get | string | final protected | Perform a GET-request against the Gogs API. |
method_post | string | final protected | Perform a POST-request against the Gogs API. |
method_delete | string | final protected | Perform a DELETE-request against the Gogs API. |
get | object | public | Get object references by identifier. |
create | bool | public | Create object inherited by class. |
patch | bool | public | Patch (update) object |
delete | bool | public | Delete object. |
json_decode | object | final protected | Decode JSON-string. |
json_encode | string | final protected | Encode JSON-object/array. |
json_error | final protected | Check for errors on encoding/decoding. | |
property_exists | string v false | final protected | Checks if the property (key) exists within selfor parent class. |
__get | mixed v null | final public | Get property by name. |
__set | mixed v null | final public | Set property by name. |
__isset | bool | final public | Checks if property is set. |
json_set_property | true v array | abstract protected | Set properties for the current object. |
set_scope | bool | abstract protected | Set the scope for the request methods accepted by the child. |
public function __construct(string $api_url, string $api_token);
Parameters
Type | Variable | Description |
---|---|---|
string | $api_url | The URL to the API. |
string | $api_token | A token for an authorized user |
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
final protected function method_get(array $params = array());
Perform a GET-request against the Gogs API.
Ensure the correct scope i set first, with
$this->set_scope("*valid scope*"); // e.g create
Parameters
Type | Variable | Description |
---|---|---|
array | $params | The parameters |
Returns: string
final protected function method_post(array $params = array());
Perform a POST-request against the Gogs API.
Ensure the correct scope i set first, with
$this->set_scope("*valid scope*"); // e.g create
Parameters
Type | Variable | Description |
---|---|---|
array | $params | The parameters |
Returns: string
final protected function method_delete();
Perform a DELETE-request against the Gogs API.
Ensure the correct scope i set first, with
$this->set_scope("*valid scope*"); // e.g delete
Returns: string
public function get(string $s);
Get object references by identifier.
Parameters
Type | Variable | Description |
---|---|---|
string | $s | The idientifier to look up |
Returns: object
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 |
---|---|---|
... | $args | Arguments required by create. |
Returns: bool
Throws:
public function patch();
Patch (update) object
Returns: bool
Throws:
public function delete();
Delete object.
Returns: bool
Throws:
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
final protected function json_encode(iterable $jdec);
Encode JSON-object/array.
Will ensure that there weren't any errors by calling $this->json_error
.
Parameters
Type | Variable | Description |
---|---|---|
iterable | $jdec | JSON-data |
Returns: string
final protected function json_error();
Check for errors on encoding/decoding.
Throws:
final protected function property_exists(mixed $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;
Parameters
Type | Variable | Description |
---|---|---|
mixed | $name | Name of the key. |
Returns: string v false
final public function __get(string $name);
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
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
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.
Parameters
Type | Variable | Description |
---|---|---|
string | $name | Property name |
Returns: bool
abstract 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 v array
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 is a collection of data of one type.
Name | Return | Access | Description |
---|---|---|---|
add | mixed v int | public | Add an object to the collection. |
remove | bool | public | Remove an element in collection. |
all | array | public | |
len | int | public | |
by_key | mixed | public | |
next | mixed | public | |
prev | mixed | public | |
current | public | ||
reset | mixed | public | |
search | Collection | abstract public | Search for an object. |
public function add(mixed $obj, mixed $key = null);
Add an object to the collection.
When adding a key the object will be stored on the particual key, also overwriting existing data.
Parameters
Type | Variable | Description |
---|---|---|
mixed | $obj | Element to store |
mixed | $key | Index key to store on |
Returns: mixed v int
public function remove(mixed $any, bool $deep = true);
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
public function all();
Returns: array
public function len();
Returns: int
public function by_key(mixed $idx);
Parameters
Type | Variable | Description |
---|---|---|
mixed | $idx | Index key. |
Returns: mixed
public function next();
Returns: mixed
public function prev();
Returns: mixed
public function current();
public function reset();
Returns: mixed
abstract public function search(array $params = array());
Search for an object.
Parameters
Type | Variable | Description |
---|---|---|
array | $params | Parameters |
Returns: Collection
Stores data and methods related to a single organization.
By now the following are supported:
/orgs/username
/admin/users/username/orgs
(Requires admin rights. Curl will throw NotAuthorized exception if not).Name | Return | Access | Description |
---|---|---|---|
__construct | public | Initialize an organization. | |
set_scope | bool | protected | |
search | public | ||
create | bool | public | Create a new user |
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 | $owner | The owner of the organization |
string | $oname | Organization name |
protected function set_scope(string $method);
Parameters
Type | Variable | Description |
---|---|---|
string | $method | Method type, e.g "get" |
Returns: bool
Throws:
public function search(string $q);
Parameters
Type | Variable | Description |
---|---|---|
string | $q | None |
public function create(... $args);
Create a new user
Valid parameters:
This reflects the API v1 doc, but is in an order where the required fields is first.
Parameters
Type | Variable | Description |
---|---|---|
... | $args | Arguments required by create. |
Returns: bool
Orgs is a collection of organizations.
Name | Return | Access | Description |
---|---|---|---|
__construct | public | ||
set_scope | bool | protected | Set the scope for the request methods accepted by the child. |
create | bool | public | Create object inherited by class. |
get | object | public | Get an organization by indentifier. |
search | Collection | public | Search for an organization. |
json_set_property | true v array | protected |
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 | $owner | None |
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
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 |
---|---|---|
... | $args | Arguments required by create. |
Returns: bool
Throws:
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
public function search(array $params = array());
Search for an organization.
Params can be an array of
$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
Throws:
protected function json_set_property(mixed $obj);
Parameters
Type | Variable | Description |
---|---|---|
mixed | $obj | None |
Returns: true v array
Stores data and methods related to a single repository.
By now the following are supported:
/repos/username/reponame
/user/repos
/admin/user/username/repos
/org/orgname/repos
/repos/username/reponame
Name | Return | Access | Description |
---|---|---|---|
__construct | public | Initialize a repo object. | |
set_scope | bool | protected | |
json_set_property | true v array | protected | |
search | public | ||
create | bool | public | Create a new repo |
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 | $owner | The owner of the repo |
string | $name | The repo name |
protected function set_scope(string $method);
Parameters
Type | Variable | Description |
---|---|---|
string | $method | Method type, e.g "get" |
Returns: bool
Throws:
protected function json_set_property(mixed $obj);
Parameters
Type | Variable | Description |
---|---|---|
mixed | $obj | None |
Returns: true v array
public function search(string $q);
Parameters
Type | Variable | Description |
---|---|---|
string | $q | None |
public function create(... $args);
Create a new repo
Valid paramters:
This reflects the API v1 documentation, but is in an order where the required fields are first.
Parameters
Type | Variable | Description |
---|---|---|
... | $args | Arguments required by create. |
Returns: bool
Repos is a collection of repos.
Name | Return | Access | Description |
---|---|---|---|
__construct | public | Initialize a repos collection | |
set_scope | bool | protected | |
create | bool | public | |
search | Collection | public | Searches for a repo. |
json_set_property | true v array | protected |
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 | $owner | The owner of the collection |
protected function set_scope(string $method);
Parameters
Type | Variable | Description |
---|---|---|
string | $method | Method type, e.g "get" |
Returns: bool
public function create(... $args);
Parameters
Type | Variable | Description |
---|---|---|
... | $args | Arguments required by create. |
Returns: bool
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
protected function json_set_property(mixed $obj);
Parameters
Type | Variable | Description |
---|---|---|
mixed | $obj | None |
Returns: true v array
Stores user data and methods related to a single user.
By now the following are supported:
/user
/users/username
/admin/users
(Requires admin rights. Curl will throw NotAuthorized exception if not)./admin/users
(Requires admin rights. Curl will throw NotAuthorized exception if not).A user can also list it's repos and organizations.
Name | Return | Access | Description |
---|---|---|---|
__construct | public | Initialize an user object. | |
set_scope | bool | protected | |
search | public | ||
authenticated | bool | public | Returns if the user is the authenticated user. |
repos | Repos | public | Returns every repo under user. |
repo | Repo | public | Return a single repo. |
organizations | Orgs | public | Return every organization under user. |
organization | Org | public | Return a single organization. |
create | bool | public | Create a new user. |
json_set_property | true v array | protected |
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 |
protected function set_scope(string $method);
Parameters
Type | Variable | Description |
---|---|---|
string | $method | Method type, e.g "get" |
Returns: bool
Throws:
public function search(string $q);
Parameters
Type | Variable | Description |
---|---|---|
string | $q | None |
public function authenticated();
Returns if the user is the authenticated user.
Returns: bool
public function repos();
Returns every repo under user.
Returns: Repos
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
public function organizations();
Return every organization under user.
Returns: Orgs
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
public function create(... $args);
Create a new user.
Valid parameters
This reflects the API v1 documentation, but is in an order where the required fields are first.
Parameters
Type | Variable | Description |
---|---|---|
... | $args | Arguments required by create. |
Returns: bool
protected function json_set_property(mixed $obj);
Parameters
Type | Variable | Description |
---|---|---|
mixed | $obj | None |
Returns: true v array
Returns one or more users in the Gogs installation, depending on the called method.
Name | Return | Access | Description |
---|---|---|---|
set_scope | bool | protected | Set the scope for the request methods accepted by the child. |
create | bool | public | Returns a new user object. If argumentsis specified the user will be "created". |
get | object | public | Get object references by identifier. |
search | Collection | public | Search for an object. |
json_set_property | true v array | protected | Set properties for the current object. |
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
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 |
---|---|---|
... | $args | Arguments required by create. |
Returns: bool
public function get(string $s = "");
Get object references by identifier.
Parameters
Type | Variable | Description |
---|---|---|
string | $s | The idientifier to look up |
Returns: object
public function search(array $params = array());
Search for an object.
Parameters
Type | Variable | Description |
---|---|---|
array | $params | Parameters |
Returns: Collection
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 v array
Request interface, used by any kind of request object.
Name | Return | Access | Description |
---|---|---|---|
load | object | public | Load object. |
get | object | public | Get by identifier |
create | bool | public | Create object |
patch | bool | public | Patch (update) object |
delete | bool | public | Delete object |
public function load(bool $force = false);
Load object.
Parameters
Type | Variable | Description |
---|---|---|
bool | $force | Force update, default: true |
Returns: object
public function get(string $s);
Get by identifier
Parameters
Type | Variable | Description |
---|---|---|
string | $s | The idientifier to look up |
Returns: object
public function create(... $args);
Create object
Parameters
Type | Variable | Description |
---|---|---|
... | $args | Arguments required by create. |
Returns: bool
public function patch();
Patch (update) object
Returns: bool
public function delete();
Delete object
Returns: bool
Thrown whenever a class that inherits the base-class is used wrong (e.g tries to create on a loaded object)
Thrown when the requested method for a class isn't implemented.
Typically thrown when needed data to build the query is missing.
Thrown when needed parameters for a search is missing.
Base class for collections. Implements basic functions and typically used to return collections which wont be a part of the "request package"
Name | Return | Access | Description |
---|---|---|---|
set | public | Set value(e) to the collection. | |
by_key | mixed | public | |
all | array | public | |
len | int | public | |
next | mixed | public | |
prev | mixed | public | |
current | public | ||
reset | mixed | public |
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 |
public function by_key(mixed $idx);
Parameters
Type | Variable | Description |
---|---|---|
mixed | $idx | Index key. |
Returns: mixed
public function all();
Returns: array
public function len();
Returns: int
public function next();
Returns: mixed
public function prev();
Returns: mixed
public function current();
public function reset();
Returns: mixed
Interface to store one or more elements in array providing an iterator interface.
Name | Return | Access | Description |
---|---|---|---|
current | public | Get current element in collection. | |
next | mixed | public | Get next element in collection. |
prev | mixed | public | Return previous element in collection. |
reset | mixed | public | Reset collection (set array to head). |
len | int | public | Return collection size. |
all | array | public | Return the whole colection. |
by_key | mixed | public | Get element by index key. |
public function current();
Get current element in collection.
public function next();
Get next element in collection.
Returns: mixed
public function prev();
Return previous element in collection.
Returns: mixed
public function reset();
Reset collection (set array to head).
Returns: mixed
public function len();
Return collection size.
Returns: int
public function all();
Return the whole colection.
Returns: array
public function by_key(mixed $idx);
Get element by index key.
Parameters
Type | Variable | Description |
---|---|---|
mixed | $idx | Index key. |
Returns: mixed
A trait used for every class referencing the api-url and token.
Name | Return | Access | Description |
---|---|---|---|
method | int | protected | Initializes a curl request of different kinds, dependingon the specified method. This can be |
authorized | 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. |
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
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:
Defines an unexpected response.
Name | Return | Access | Description |
---|---|---|---|
__construct | public | Sets the exceptions. | |
__toString | string | public | Visual representation of the exception. |
getResponse | string | public | Get the actual response from the body or the request. |
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 |
public function __toString();
Visual representation of the exception.
Returns: string
public function getResponse();
Get the actual response from the body or the request.
Returns: string
When the request fails because of an unauthorized token, this is thrown instead.
Name | Return | Access | Description |
---|---|---|---|
__construct | public | Sets the exceptions. |
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 |