gogs-php-api-client/README.md

Gogs PHP API Client

Table of content

1. Gogs
   1. API
      1. Request
         1. Base Base class for request types.
         2. Branch A single Branch
         3. Branches Holds a collection of Branches for a Repository.
         4. Collection Collection is a collection of data of one type.
         5. Exception
            1. InvalidMethodRequestException Thrown whenever a class that inherits the base-classis used wrong (e.g tries to create on a loaded object)
            2. NotImplementedException Thrown when the requested method for a class isn'timplemented.
            3. RequestErrorException Typically thrown when needed data to build the queryis missing.
            4. SearchParamException Thrown when needed parameters for a search is missing.
         6. Org Stores data and methods related to a single organization.
         7. Orgs Orgs is a collection of organizations.
         8. Repo Stores data and methods related to a single repository.
         9. Repos Repos is a collection of repos.
         10. RequestInterface Request interface, used by any kind of request object.
         11. Token A token related to a user
         12. Tokens Collection of tokens for a given user.
         13. User Stores user data and methods related to a single user.
         14. Users Returns one or more users in the Gogs installation,depending on the called method.
      2. Client Gogs API client.
   2. Lib
      1. Curl
         1. Client A trait used for every class referencing the api-url and token.
         2. Exception
            1. HTTPUnexpectedResponse Defines an unexpected response.
            2. NotAuthorizedException When the request fails because of an unauthorized token,this is thrown instead.
      2. ArrayIterator Interface to store one or more elements in arrayproviding an iterator interface.
      3. Collection Base class for collections. Implements basicfunctions and typically used to return collectionswhich wont be a part of the "request package"

---

Documentation

Gogs

• Gogs\API
• Gogs\API\Request
• Gogs\API\Request\Exception
• Gogs\Lib
• Gogs\Lib\Curl
• Gogs\Lib\Curl\Exception

Gogs\API

Classes

Client Gogs\API

• Class uses Gogs\Lib\Curl\Client

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		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.
get_log	array	public	A wrapper function as get_log on Client wontreturn anything. This is bogus, but.

Method details

__construct Gogs\API\Client

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.

---

users Gogs\API\Client

public function users();

Returns a Request\Users to fetch users from the Gogs installation.

Returns: Users

---

user Gogs\API\Client

public function user(string $name = "me");

Get a single user from Gogs.

Returns either

• the authorized user ($name = "" or "me")
• the specified user ($name = anything else)

Parameters

Type	Variable	Description
string	$name	None

Returns: User

---

repos Gogs\API\Client

public function repos();

Returns an \Request\Repos to fetch repositories on the Gogs installation.

Returns: Repos

---

get_log Gogs\API\Client

public function get_log();

A wrapper function as get_log on Client wont return anything. This is bogus, but.

... this workaround WORKS!

Returns: array

---

Gogs\API\Request

Classes

Base Gogs\API\Request

• Class implementsGogs\API\Request\RequestInterface
• Class uses Gogs\Lib\Curl\Client

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		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.
json_set_property	true v array	protected	Set properties for the current object.
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.
set_scope	bool	abstract protected	Set the scope for the request methods accepted by the child.
search	true	protected	Search for an matching object.

Method details

__construct Gogs\API\Request\Base

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

---

load Gogs\API\Request\Base

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

Throws:

• NotImplementedException

---

method_get Gogs\API\Request\Base

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

---

method_post Gogs\API\Request\Base

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

---

method_delete Gogs\API\Request\Base

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

---

get Gogs\API\Request\Base

public function get(string $s);

Get object references by identifier.

Parameters

Type	Variable	Description
string	$s	The idientifier to look up

Returns: object

---

create Gogs\API\Request\Base

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:

• InvalidMethodRequestException
• NotImplementedException

---

patch Gogs\API\Request\Base

public function patch();

Patch (update) object

Returns: bool

Throws:

• InvalidMethodRequestException
• NotImplementedException

---

delete Gogs\API\Request\Base

public function delete();

Delete object.

Returns: bool

Throws:

• NotImplementedException

---

json_decode Gogs\API\Request\Base

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

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

---

json_error Gogs\API\Request\Base

final protected function json_error();

Check for errors on encoding/decoding.

Throws:

• RequestErrorException

---

json_set_property Gogs\API\Request\Base

protected function json_set_property(iterable $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
iterable	$obj	None

Returns: true v array

---

property_exists Gogs\API\Request\Base

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

---

__get Gogs\API\Request\Base

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

---

__set Gogs\API\Request\Base

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

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

---

set_scope Gogs\API\Request\Base

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

---

search Gogs\API\Request\Base

protected function search(array $params = array(), bool $strict = false);

Search for an matching object.

Methods do OR-ing and not AND-ing by default.

Params should be key (object property) and value that this parameter should match, e.g

$repo->search(
 "name" => "this",
 "owner" => array(
     "username" => "that"
 )
);

will match "this" IN $repo->name OR "that" IN $repo->owner->username .

Parameters

Type	Variable	Description
array	$params	Parameters
bool	$strict	Turn search into AND-ing, require match in each field.

Returns: true

Throws:

• SearchParamException

---

Branch Gogs\API\Request

• Class extends Gogs\API\Request\Base
• Class implementsGogs\API\Request\RequestInterface

A single Branch

Methods

Name	Return	Access	Description
__construct		public	Initialize a branch for the given repository.
set_scope	bool	protected

Method details

__construct Gogs\API\Request\Branch

public function __construct(string $api_url, string $api_token, Repo $repo);

Initialize a branch for the given repository.

Parameters

Type	Variable	Description
string	$api_url	The URL to the API.
string	$api_token	A token for an authorized user
Repo	$repo	Related repository

---

set_scope Gogs\API\Request\Branch

protected function set_scope(string $method);

Parameters

Type	Variable	Description
string	$method	Method type, e.g "get"

Returns: bool

---

Branches Gogs\API\Request

• Class extends Gogs\API\Request\Collection
• Class implements
  • Gogs\Lib\ArrayIterator
  • Gogs\API\Request\RequestInterface

Holds a collection of Branches for a Repository.

Supported:

• GET /repos/username/repo/branches

Methods

Name	Return	Access	Description
__construct		public	Initialize Brances for a given repo
set_scope	bool	protected
search	true	public	Search for a branch.
sort_by	Collection	public
add_object	array	protected

Method details

__construct Gogs\API\Request\Branches

public function __construct(string $api_url, string $api_token, Repo $repo);

Initialize Brances for a given repo

Parameters

Type	Variable	Description
string	$api_url	The URL to the API.
string	$api_token	A token for an authorized user
Repo	$repo	The repository

---

set_scope Gogs\API\Request\Branches

protected function set_scope(string $method);

Parameters

Type	Variable	Description
string	$method	Method type, e.g "get"

Returns: bool

---

search Gogs\API\Request\Branches

public function search(array $params = array(), bool $strict = true);

Search for a branch.

This method doesnt search by a uri, instead it will load every branch from Gogs and do a match on this.

Params can be an array of

$branches->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 branch and then do a match on each entry.

Parameters

Type	Variable	Description
array	$params	Parameters
bool	$strict	Turn search into AND-ing, require match in each field.

Returns: true

Throws:

• SearchParamException

---

sort_by Gogs\API\Request\Branches

public function sort_by(int $flag = Collection::SORT_INDEX);

Parameters

Type	Variable	Description
int	$flag	Sorting flag

Returns: Collection

---

add_object Gogs\API\Request\Branches

protected function add_object(iterable $obj);

Parameters

Type	Variable	Description
iterable	$obj	None

Returns: array

---

Collection Gogs\API\Request

• Class extends Gogs\API\Request\Base
• Class implements
  • Gogs\Lib\ArrayIterator
  • Gogs\API\Request\RequestInterface

Collection is a collection of data of one type.

Methods

Name	Return	Access	Description
__construct		public	Initialize a collection.
add	mixed v int	protected	Add an object to the collection.
remove	bool	protected	Remove an element in collection.
copy	Colletion	public
all	array	public
len	int	public
by_key	mixed	public
next	mixed	public
prev	mixed	public
current		public
reset	mixed	public
sort	Collection	public
filter	Collection	public
limit	Collection	public
offset	Collection	public
reverse	Collection	public
json_set_property	true v array	protected
search	true	public	Search an collection.
add_object	array	abstract protected	Add an object to the collection with the specific type.
sort_by	Collection	abstract public	Sort the object

Method details

__construct Gogs\API\Request\Collection

public function __construct(string $api_url, string $api_token, Collection $other = null);

Initialize a collection.

Parameters

Type	Variable	Description
string	$api_url	The URL to the API.
string	$api_token	A token for an authorized user
Collection	$other	Collection to initialize from

---

add Gogs\API\Request\Collection

protected 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

---

remove Gogs\API\Request\Collection

protected 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

---

copy Gogs\API\Request\Collection

public function copy();

Returns: Colletion

---

all Gogs\API\Request\Collection

public function all();

Returns: array

---

len Gogs\API\Request\Collection

public function len();

Returns: int

---

by_key Gogs\API\Request\Collection

public function by_key(mixed $idx);

Parameters

Type	Variable	Description
mixed	$idx	Index key.

Returns: mixed

---

next Gogs\API\Request\Collection

public function next();

Returns: mixed

---

prev Gogs\API\Request\Collection

public function prev();

Returns: mixed

---

current Gogs\API\Request\Collection

public function current();

---

reset Gogs\API\Request\Collection

public function reset();

Returns: mixed

---

sort Gogs\API\Request\Collection

public function sort(callable $f);

Parameters

Type	Variable	Description
callable	$f	None

Returns: Collection

---

filter Gogs\API\Request\Collection

public function filter(callable $f);

Parameters

Type	Variable	Description
callable	$f	None

Returns: Collection

---

limit Gogs\API\Request\Collection

public function limit(int $lim);

Parameters

Type	Variable	Description
int	$lim	Maximum entries returned

Returns: Collection

---

offset Gogs\API\Request\Collection

public function offset(int $off);

Parameters

Type	Variable	Description
int	$off	Offset from in collection

Returns: Collection

---

reverse Gogs\API\Request\Collection

public function reverse();

Returns: Collection

---

json_set_property Gogs\API\Request\Collection

protected function json_set_property(iterable $obj);

Parameters

Type	Variable	Description
iterable	$obj	None

Returns: true v array

---

search Gogs\API\Request\Collection

public function search(array $params = array(), bool $strict = false);

Search an collection.

Parameters

Type	Variable	Description
array	$params	Parameters
bool	$strict	Turn search into AND-ing, require match in each field.

Returns: true

Throws:

• NotImplementedException

---

add_object Gogs\API\Request\Collection

abstract protected function add_object(iterable $object);

Add an object to the collection with the specific type.

Typically it will create an instance of the type that the collection will consist of.

Should call json set property

Parameters

Type	Variable	Description
iterable	$object	None

Returns: array

---

sort_by Gogs\API\Request\Collection

abstract public function sort_by(int $flag = \Gogs\Lib\ArrayIterator::SORT_INDEX);

Sort the object

Should call sort on parent with the specified sort method, given by $flag

Parameters

Type	Variable	Description
int	$flag	Sorting flag

Returns: Collection

---

Org Gogs\API\Request

• Class extends Gogs\API\Request\User
• Class implementsGogs\API\Request\RequestInterface

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		public	Initialize an organization.
set_scope	bool	protected
create	bool	public	Create a new user

Method details

__construct Gogs\API\Request\Org

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

---

set_scope Gogs\API\Request\Org

protected function set_scope(string $method);

Parameters

Type	Variable	Description
string	$method	Method type, e.g "get"

Returns: bool

Throws:

• InvalidMethodRequestException
• RequestErrorException

---

create Gogs\API\Request\Org

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
...	$args	Arguments required by create.

Returns: bool

---

Orgs Gogs\API\Request

• Class extends Gogs\API\Request\Collection
• Class implements
  • Gogs\Lib\ArrayIterator
  • Gogs\API\Request\RequestInterface

Orgs is a collection of organizations.

Methods

Name	Return	Access	Description
__construct		public	Initialize an organization collection for user.
set_scope	bool	protected
create	bool	public	Create a new organization
get	object	public	Get an organization by indentifier.
search	true	public	Search for an organization.
add_object	array	protected
sort_by	Collection	public

Method details

__construct Gogs\API\Request\Orgs

public function __construct(string $api_url, string $api_token, User $owner);

Initialize an organization collection for 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 user

---

set_scope Gogs\API\Request\Orgs

protected function set_scope(string $method);

Parameters

Type	Variable	Description
string	$method	Method type, e.g "get"

Returns: bool

---

create Gogs\API\Request\Orgs

public function create(... $args);

Create a new organization

If arguments are given, the User will be created, otherise it will return an initialized object, leaving the programmer to create the user.

Parameters

Type	Variable	Description
...	$args	Arguments required by create.

Returns: bool

---

get Gogs\API\Request\Orgs

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

public function search(array $params = array(), bool $strict = false);

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
bool	$strict	Turn search into AND-ing, require match in each field.

Returns: true

Throws:

• SearchParamException

---

add_object Gogs\API\Request\Orgs

protected function add_object(iterable $obj);

Parameters

Type	Variable	Description
iterable	$obj	None

Returns: array

---

sort_by Gogs\API\Request\Orgs

public function sort_by(int $flag = Collection::SORT_INDEX);

Parameters

Type	Variable	Description
int	$flag	Sorting flag

Returns: Collection

---

Repo Gogs\API\Request

• Class extends Gogs\API\Request\Base
• Class implementsGogs\API\Request\RequestInterface

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		public	Initialize a repo object.
set_scope	bool	protected
branches	Branches	public	Return branches for repository.
json_set_property	true v array	protected	Overrides Base method as this should set owner as well
create	bool	public	Create a new repo
migrate		public	Migrate a repository from other Git hosting sources.
sync	bool	public	Add repo to sync queue.

Method details

__construct Gogs\API\Request\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

---

set_scope Gogs\API\Request\Repo

protected function set_scope(string $method);

Parameters

Type	Variable	Description
string	$method	Method type, e.g "get"

Returns: bool

Throws:

• RequestErrorException

---

branches Gogs\API\Request\Repo

public function branches();

Return branches for repository.

Returns: Branches

---

json_set_property Gogs\API\Request\Repo

protected function json_set_property(iterable $obj);

Overrides Base method as this should set owner as well

Parameters

Type	Variable	Description
iterable	$obj	None

Returns: true v array

---

create Gogs\API\Request\Repo

public function create(... $args);

Create a new repo

Valid paramters:

1. name, required
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
...	$args	Arguments required by create.

Returns: bool

---

migrate Gogs\API\Request\Repo

public function migrate(mixed $args);

Migrate a repository from other Git hosting sources.

Valid parameters:

1. clone_addr, required
2. repo_name, required
3. auth_username
4. auth_password
5. mirror (default: false)
6. private (default: false)
7. description

UID will be set to owner. Either a User or an Organization. From API doc: To migrate a repository for a organization, the authenticated user must be a owner of the specified organization.

This reflects the API v1 documentation, but is in an order where the required fields as first.

Parameters

Type	Variable	Description
mixed	$args	None

Throws:

• RequestErrorException

---

sync Gogs\API\Request\Repo

public function sync();

Add repo to sync queue.

Requires the repository to be a mirror.

Returns: bool

---

Repos Gogs\API\Request

• Class extends Gogs\API\Request\Collection
• Class implements
  • Gogs\Lib\ArrayIterator
  • Gogs\API\Request\RequestInterface

Repos is a collection of repos.

Methods

Name	Return	Access	Description
__construct		public	Initialize a repos collection
set_scope	bool	protected
get	object	public	Get a single repository by name.
create	bool	public
search	true	public	Searches for a repo.
sort_by	Collection	public	Sort repos by method.
add_object	array	protected
privates	Collection	public	Get private repositories
publics	Collection	public	Get public repositories
personals	Collection	public	Get personal repositories
contributions	Collection	public	Get repositories contributed to
personals_privates	Collection	public	Get personal private repositories
personals_publics	Collection	public	Get personal public repositories
contributions_privates	Collection	public	Get private contributions
contributions_publics	Collection	public	Get public contributions

Method details

__construct Gogs\API\Request\Repos

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

---

set_scope Gogs\API\Request\Repos

protected function set_scope(string $method);

Parameters

Type	Variable	Description
string	$method	Method type, e.g "get"

Returns: bool

---

get Gogs\API\Request\Repos

public function get(string $name);

Get a single repository by name.

If the owner is set, the name can be just the actual name of the repo

Parameters

Type	Variable	Description
string	$name	None

Returns: object

---

create Gogs\API\Request\Repos

public function create(... $args);

Parameters

Type	Variable	Description
...	$args	Arguments required by create.

Returns: bool

---

search Gogs\API\Request\Repos

public function search(array $params = array(), bool $strict = false);

Searches for a repo.

If the owner is specified the search will be limited to the actual user.

Params can be an array of

$repos->search(array(
 "name"  => "name",      // alt. "q". required
 "limit" => 10,          // not required, default: 10
));

If repositories is allready loaded it will do a match on the existing collection.

Parameters

Type	Variable	Description
array	$params	Parameters
bool	$strict	Turn search into AND-ing, require match in each field.

Returns: true

Throws:

• SearchParamException

---

sort_by Gogs\API\Request\Repos

public function sort_by(int $flag = Collection::SORT_INDEX, bool $asc = false);

Sort repos by method.

Valid methods:

• SORT_UPDATED: Sort on updated_at value
• SORT_CREATED: Sort on created_at value
• SORT_OWNER: Sort on owner (organization repos etc may appear)

Parameters

Type	Variable	Description
int	$flag	Sorting flag
bool	$asc	Ascending order

Returns: Collection

---

add_object Gogs\API\Request\Repos

protected function add_object(iterable $obj);

Parameters

Type	Variable	Description
iterable	$obj	None

Returns: array

---

privates Gogs\API\Request\Repos

public function privates();

Get private repositories

Returns: Collection

---

publics Gogs\API\Request\Repos

public function publics();

Get public repositories

Returns: Collection

---

personals Gogs\API\Request\Repos

public function personals();

Get personal repositories

Returns: Collection

---

contributions Gogs\API\Request\Repos

public function contributions();

Get repositories contributed to

Returns: Collection

---

personals_privates Gogs\API\Request\Repos

public function personals_privates();

Get personal private repositories

Returns: Collection

---

personals_publics Gogs\API\Request\Repos

public function personals_publics();

Get personal public repositories

Returns: Collection

---

contributions_privates Gogs\API\Request\Repos

public function contributions_privates();

Get private contributions

Returns: Collection

---

contributions_publics Gogs\API\Request\Repos

public function contributions_publics();

Get public contributions

Returns: Collection

---

Token Gogs\API\Request

• Class extends Gogs\API\Request\Base
• Class implementsGogs\API\Request\RequestInterface

A token related to a user

Supports:

• POST /users/{username}/tokens

Note! Tokens doesnt have a "GET" method. @see Tokens as this can load them.

Methods

Name	Return	Access	Description
__construct		public	Initializes a token
set_scope	bool	protected
create	bool	public	Create a new token

Method details

__construct Gogs\API\Request\Token

public function __construct(string $api_url, string $password, User $user);

Initializes a token

Parameters

Type	Variable	Description
string	$api_url	The URL to the API.
string	$password	The users personal password
User	$user	None

---

set_scope Gogs\API\Request\Token

protected function set_scope(string $method);

Parameters

Type	Variable	Description
string	$method	Method type, e.g "get"

Returns: bool

---

create Gogs\API\Request\Token

public function create(... $args);

Create a new token

Valid parameters:

1. name

This reflects the API v1 documentation.

Parameters

Type	Variable	Description
...	$args	Arguments required by create.

Returns: bool

---

Tokens Gogs\API\Request

• Class extends Gogs\API\Request\Collection
• Class implements
  • Gogs\Lib\ArrayIterator
  • Gogs\API\Request\RequestInterface

Collection of tokens for a given user.

Supports:

• GET /users/{username}/tokens

Methods

Name	Return	Access	Description
__construct		public	Initialize a token collection.
set_scope	bool	protected
create	bool	public	Create a new token.
add_object	array	protected
get	object	public	Return a token by name
search	true	public	Search for a token.
sort_by	Collection	public

Method details

__construct Gogs\API\Request\Tokens

public function __construct(string $api_url, string $password, User $user);

Initialize a token collection.

Parameters

Type	Variable	Description
string	$api_url	The URL to the API.
string	$password	User's personal password
User	$user	Owner of tokens

---

set_scope Gogs\API\Request\Tokens

protected function set_scope(string $method);

Parameters

Type	Variable	Description
string	$method	Method type, e.g "get"

Returns: bool

---

create Gogs\API\Request\Tokens

public function create(... $args);

Create a new token.

Returns a new token object. If arguments is specified the "token" will be created.

Arguments can be left empty to "create" the token, leaving the programmer to call create on the token object with the arguments itself, to create it.

Creating the token through this function will store the function in the collection. If not created, it wont be added, and collection must be reloaded (->load(true)) to add it.

Parameters

Type	Variable	Description
...	$args	Arguments required by create.

Returns: bool

---

add_object Gogs\API\Request\Tokens

protected function add_object(iterable $obj);

Parameters

Type	Variable	Description
iterable	$obj	None

Returns: array

---

get Gogs\API\Request\Tokens

public function get(string $s);

Return a token by name

Parameters

Type	Variable	Description
string	$s	The idientifier to look up

Returns: object

---

search Gogs\API\Request\Tokens

public function search(array $params = array(), bool $strict = false);

Search for a token.

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 token and then do a match on each entry.

Parameters

Type	Variable	Description
array	$params	Parameters
bool	$strict	Turn search into AND-ing, require match in each field.

Returns: true

Throws:

• SearchParamException

---

sort_by Gogs\API\Request\Tokens

public function sort_by(int $flag = Collection::SORT_INDEX);

Parameters

Type	Variable	Description
int	$flag	Sorting flag

Returns: Collection

---

User Gogs\API\Request

• Class extends Gogs\API\Request\Base
• Class implementsGogs\API\Request\RequestInterface

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		public	Initialize an user object.
set_scope	bool	protected
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.
orgs		public
organization	Org	public	Return a single organization.
org		public
create	bool	public	Create a new user.
tokens	Tokens	public	Returns user tokens

Method details

__construct Gogs\API\Request\User

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

protected function set_scope(string $method);

Parameters

Type	Variable	Description
string	$method	Method type, e.g "get"

Returns: bool

Throws:

• InvalidMethodRequest
• RequestErrorException

---

authenticated Gogs\API\Request\User

public function authenticated();

Returns if the user is the authenticated user.

Returns: bool

---

repos Gogs\API\Request\User

public function repos();

Returns every repo under user.

Returns: Repos

---

repo Gogs\API\Request\User

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

---

organizations Gogs\API\Request\User

public function organizations();

Return every organization under user.

Returns: Orgs

---

orgs Gogs\API\Request\User

public function orgs();

---

organization Gogs\API\Request\User

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 Gogs\API\Request\User

public function org(string $name);

Parameters

Type	Variable	Description
string	$name	None

---

create Gogs\API\Request\User

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
...	$args	Arguments required by create.

Returns: bool

---

tokens Gogs\API\Request\User

public function tokens(string $password);

Returns user tokens

Parameters

Type	Variable	Description
string	$password	User personal password.

Returns: Tokens

---

Users Gogs\API\Request

• Class extends Gogs\API\Request\Collection
• Class implements
  • Gogs\Lib\ArrayIterator
  • Gogs\API\Request\RequestInterface

Returns one or more users in the Gogs installation, depending on the called method.

Methods

Name	Return	Access	Description
set_scope	bool	protected
create	bool	public	Returns a new user object. If argumentsis specified the user will be "created".
get	object	public	Return a user by username.
search	true	public	Search for an user
sort_by	Collection	public
add_object	array	protected

Method details

set_scope Gogs\API\Request\Users

protected function set_scope(string $method);

Parameters

Type	Variable	Description
string	$method	Method type, e.g "get"

Returns: bool

---

create Gogs\API\Request\Users

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

---

get Gogs\API\Request\Users

public function get(string $s);

Return a user by username.

Parameters

Type	Variable	Description
string	$s	The idientifier to look up

Returns: object

---

search Gogs\API\Request\Users

public function search(array $params = array(), bool $strict = false);

Search for an user

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
bool	$strict	Turn search into AND-ing, require match in each field.

Returns: true

Throws:

• SearchParamException

---

sort_by Gogs\API\Request\Users

public function sort_by(int $flag = Collection::SORT_INDEX);

Parameters

Type	Variable	Description
int	$flag	Sorting flag

Returns: Collection

---

add_object Gogs\API\Request\Users

protected function add_object(iterable $obj);

Parameters

Type	Variable	Description
iterable	$obj	None

Returns: array

---

Interfaces

RequestInterface Gogs\API\Request

Request interface, used by any kind of request object.

Methods

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

Method details

load Gogs\API\Request\RequestInterface

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

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

public function create(... $args);

Create object

Parameters

Type	Variable	Description
...	$args	Arguments required by create.

Returns: bool

---

patch Gogs\API\Request\RequestInterface

public function patch();

Patch (update) object

Returns: bool

---

delete Gogs\API\Request\RequestInterface

public function delete();

Delete object

Returns: bool

---

Gogs\API\Request\Exception

Exceptions

InvalidMethodRequestException Gogs\API\Request\Exception

• Class extends 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

Thrown when the requested method for a class isn't implemented.

RequestErrorException Gogs\API\Request\Exception

• Class extends Exception

Typically thrown when needed data to build the query is missing.

SearchParamException Gogs\API\Request\Exception

• Class extends Exception

Thrown when needed parameters for a search is missing.

Gogs\Lib

Classes

Collection Gogs\Lib

• Class implementsGogs\Lib\ArrayIterator

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
__construct		public
set		public	Set value(e) to the collection.
by_key	mixed	public
copy	Colletion	public	Copy collection
all	array	public
len	int	public
next	mixed	public
prev	mixed	public
current		public
reset	mixed	public
sort	Collection	public
filter	Collection	public	Filter collection
limit	Collection	public
offset	Collection	public
reverse	Collection	public
remove	bool	public	Remove an element in collection.

Method details

__construct Gogs\Lib\Collection

public function __construct(array $arr = array());

Parameters

Type	Variable	Description
array	$arr	None

---

set Gogs\Lib\Collection

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

public function by_key(mixed $idx);

Parameters

Type	Variable	Description
mixed	$idx	Index key.

Returns: mixed

---

copy Gogs\Lib\Collection

public function copy();

Copy collection

Returns: Colletion

---

all Gogs\Lib\Collection

public function all();

Returns: array

---

len Gogs\Lib\Collection

public function len();

Returns: int

---

next Gogs\Lib\Collection

public function next();

Returns: mixed

---

prev Gogs\Lib\Collection

public function prev();

Returns: mixed

---

current Gogs\Lib\Collection

public function current();

---

reset Gogs\Lib\Collection

public function reset();

Returns: mixed

---

sort Gogs\Lib\Collection

public function sort(callable $f);

Parameters

Type	Variable	Description
callable	$f	None

Returns: Collection

---

filter Gogs\Lib\Collection

public function filter(callable $f);

Filter collection

Parameters

Type	Variable	Description
callable	$f	None

Returns: Collection

---

limit Gogs\Lib\Collection

public function limit(int $lim);

Parameters

Type	Variable	Description
int	$lim	Maximum entries returned

Returns: Collection

---

offset Gogs\Lib\Collection

public function offset(int $off);

Parameters

Type	Variable	Description
int	$off	Offset from in collection

Returns: Collection

---

reverse Gogs\Lib\Collection

public function reverse();

Returns: Collection

---

remove Gogs\Lib\Collection

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

---

Interfaces

ArrayIterator Gogs\Lib

Interface to store one or more elements in array providing an iterator interface.

Methods

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.
copy	Colletion	public	Copy collection
limit	Collection	public	Limit until in collection
offset	Collection	public	Get from offset collection
reverse	Collection	public	Reverse the collection
sort	Collection	public	Sort collection
filter	Collection	public	Filter collection

Method details

current Gogs\Lib\ArrayIterator

public function current();

Get current element in collection.

---

next Gogs\Lib\ArrayIterator

public function next();

Get next element in collection.

Returns: mixed

---

prev Gogs\Lib\ArrayIterator

public function prev();

Return previous element in collection.

Returns: mixed

---

reset Gogs\Lib\ArrayIterator

public function reset();

Reset collection (set array to head).

Returns: mixed

---

len Gogs\Lib\ArrayIterator

public function len();

Return collection size.

Returns: int

---

all Gogs\Lib\ArrayIterator

public function all();

Return the whole colection.

Returns: array

---

by_key Gogs\Lib\ArrayIterator

public function by_key(mixed $idx);

Get element by index key.

Parameters

Type	Variable	Description
mixed	$idx	Index key.

Returns: mixed

---

copy Gogs\Lib\ArrayIterator

public function copy();

Copy collection

Returns: Colletion

---

limit Gogs\Lib\ArrayIterator

public function limit(int $lim);

Limit until in collection

Parameters

Type	Variable	Description
int	$lim	Maximum entries returned

Returns: Collection

---

offset Gogs\Lib\ArrayIterator

public function offset(int $off);

Get from offset collection

Parameters

Type	Variable	Description
int	$off	Offset from in collection

Returns: Collection

---

reverse Gogs\Lib\ArrayIterator

public function reverse();

Reverse the collection

Returns: Collection

---

sort Gogs\Lib\ArrayIterator

public function sort(callable $f);

Sort collection

Parameters

Type	Variable	Description
callable	$f	None

Returns: Collection

---

filter Gogs\Lib\ArrayIterator

public function filter(callable $f);

Filter collection

Parameters

Type	Variable	Description
callable	$f	None

Returns: Collection

---

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
basic		protected	Basic sets the user for basic HTTP-authentication.
set_param		protected	Set param into array
filter_params		protected	Filter out NULL values from parameters.
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.
get_log	array	public static	Returns log entries for the client.

Method details

basic Gogs\Lib\Curl\Client

protected function basic(string $user);

Basic sets the user for basic HTTP-authentication.

Parameters

Type	Variable	Description
string	$user	None

---

set_param Gogs\Lib\Curl\Client

protected function set_param(array $params, string $param_name, array $args, int $index, string $type, mixed $default = null, callable $f = null);

Set param into array

The specified callback will only run if the expected parameter is set. This callback can either overwrite paramtere as passing them as reference or throw an exception to indicate invalid data.

Parameters

Type	Variable	Description
array	$params	&$params Array to insert to
string	$param_name	Index in params-array
array	$args	Arguments array
int	$index	Index in arguments array
string	$type	Expected type of data
mixed	$default	Default if not expected type on index
callable	$f	Callback method if param is set

---

filter_params Gogs\Lib\Curl\Client

protected function filter_params(array $params);

Filter out NULL values from parameters.

Saves transferring size.

Parameters

Type	Variable	Description
array	$params	&$params Parameters

---

method Gogs\Lib\Curl\Client

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

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

---

get_log Gogs\Lib\Curl\Client

public static function get_log();

Returns log entries for the client.

Returns: array

---

Gogs\Lib\Curl\Exception

Exceptions

HTTPUnexpectedResponse Gogs\Lib\Curl\Exception

• Class extends Exception

Defines an unexpected response.

Methods

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.

Method details

__construct Gogs\Lib\Curl\Exception\HTTPUnexpectedResponse

public function __construct(string $message, int $code, 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

public function __toString();

Visual representation of the exception.

Returns: string

---

getResponse Gogs\Lib\Curl\Exception\HTTPUnexpectedResponse

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

When the request fails because of an unauthorized token, this is thrown instead.

Methods

Name	Return	Access	Description
__construct		public	Sets the exceptions.

Method details

__construct Gogs\Lib\Curl\Exception\NotAuthorizedException

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