Browse Source

Added submodule for read me

Joachim M. Giæver 6 years ago
parent
commit
344ce2d69f

+ 3 - 0
.gitmodules

@@ -0,0 +1,3 @@
+[submodule "sami-markdown"]
+	path = sami-markdown
+	url = giaever@git.giaever.org:joachimmg/sami-markdown.git

+ 0 - 4
markdown/manifest.yml

@@ -1,4 +0,0 @@
-name: markdown
-
-global:
-    'readme.twig':  'README.md'

+ 0 - 13
markdown/readme.twig

@@ -1,13 +0,0 @@
-{% block content %}
-
-{% block content_header %}
-    {{- project.config('title')|default('Read me')}}
-    {{- "\n===" }}
-{% endblock %}
-
-{% block toc %}
-    {%- block toc_title %}# Table of content{% endblock %}
-    {%- include 'toc.twig' %}
-{% endblock %}
-    
-{% endblock %}

+ 0 - 2
markdown/toc.twig

@@ -1,2 +0,0 @@
-
-{{toc(tree, 0)|raw}}

+ 1 - 0
sami-markdown

@@ -0,0 +1 @@
+Subproject commit 5ad6e981d28c8a4ec452bf79527357fdd221a0c7

+ 0 - 86
sami.conf.php

@@ -1,86 +0,0 @@
-<?php
-
-class Markdown_Sami_Twig_Extension extends Twig_Extension {
-    public function getFunctions() {
-        return array(
-            new Twig_Function("toc", array($this, "toc")),
-            new Twig_Function("href", array($this, "href")),
-            new Twig_Function("dep", array($this, "dep"))
-        );
-    }
-
-    private static function dep($ref) {
-        return sprintf("%s%s", $ref->getName(), $ref->getDeprecated() ? "(DEP)" : "");
-    }
-
-    private static function tab(int $depth) {
-        return str_repeat("\t", $depth);
-    }
-
-    public static function href(string $ltxt, string $lurl, string $desc = null) {
-        $desc = $desc ? sprintf(' "%s"', $desc) : null;
-        return sprintf("[%s](%s%s)", $ltxt, str_replace("\\", "_", $lurl), $desc);
-    }
-
-    public static function toc(array $tree, int $depth) {
-
-        $append = (function(string &$into, int $depth, int $idx, string $from) {
-            $into .= sprintf("%s%d. %s\n", self::tab($depth), $idx + 1, $from);
-        });
-
-        $str = "";
-
-        foreach ($tree as $key => $elem) {
-            $append($str, $depth, $key, self::href(is_string($elem[1]) ? $elem[1] : self::dep($elem), sprintf("#%s", $elem[1]), $elem[1])); 
-
-            if (isset($elem[2]) && !empty($elem[2])) {
-                $last = array();
-                $pos = 0;
-                
-                foreach($elem[2] as $key2 => $elem2) {
-                    if (isset($elem2[2]) && !empty($elem2[2]))
-                        $last[$key2] = $elem2;
-                    else
-                        $append($str, ($depth+1), $pos++, self::href(self::dep($elem2[1]), sprintf("#%s", $elem2[1]), $elem2[1]));
-                }
-
-                foreach($last as $key2 => $elem2) {
-                    $append($str, ($depth+1), $pos + $key2, self::href(is_string($elem2[1]) ? $elem2[1] : self::dep($elem2[1]), sprintf("#%s", $elem2[1]), $elem2[1]));
-                    $str .= self::toc($elem2[2], ($depth+2));
-                }
-            }
-        }
-
-        return $str;
-    }
-}
-
-use Sami\Sami;
-use Sami\RemoteRepository\GitHubRemoteRepository;
-use Sami\Version\GitVersionCollection;
-use Symfony\Component\Finder\Finder;
-
-$iterator = Finder::create()
-    ->files()
-    ->name('*.php')
-    ->in($dir = './src')
-;
-
-$versions = GitVersionCollection::create($dir)
-    ->add('master', 'master branch')
-;
-
-$s =  new Sami($iterator, array(
-    'theme'                => 'markdown',
-    'template_dirs'        => array( __DIR__ . '/markdown'),
-    'versions'             => $versions,
-    'title'                => 'Symfony2 API',
-    'build_dir'            => __DIR__.'/build/%version%',
-    'cache_dir'            => __DIR__.'/cache/%version%',
-));
-
-$s["twig"]->addExtension(new Markdown_Sami_Twig_Extension());
-
-return $s;
-
-?>

+ 69 - 64
src/API/Client.php

@@ -1,75 +1,80 @@
-<?php namespace Gogs\API;
+<?php 
 
-/** 
- * Gogs API client. This class initially provide 
- * the programmer with a starting point and a kind
- * of an interface to start from, to keep  track of
- * the context.
- * 
- * @author Joachim M. Giaever (joachim[]giaever.org)
- * @version 0.1
- */
-
-class Client {
-    use \Gogs\Lib\Curl\Client;
+namespace Gogs\API {
 
     /** 
-     * Constructor of the class to store the api data.
+     * Gogs API client. 
+     *
+     * This class initially provide the programmer with a starting 
+     * point and a kind of an interface to start from, to keep 
+     * track of the context when going from a user, to a repo,
+     * organization etc.
      *
-     * @deprecated "No longer user"
-     * @param string $api_url 
-     * @param string $api_token 
-     * @return null
+     * @deprecated
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     * @version 0.1
      */
-    public function __construct(string $api_url, string $api_token) {
-        $this->url = $api_url;
-        $this->token = $api_token;
-    }
 
-    /** 
-     * Returns an object to fetch users from the
-     * Gogs installation. See \Request\Users class
-     * to understand usage (e.g ->load() to fetch all, 
-     * ->search(array params) to search for one or several 
-     * users etc).
-     * 
-     * @return \Request\Users
-     */
-    public function users() {
-        return new Request\Users($this->url, $this->token);
-    }
+    final class Client {
+        use \Gogs\Lib\Curl\Client;
 
-    /** 
-     * Returns an object to fetch the repositories
-     * on the Gogs installation. See \Request\Repos to
-     * understand usage. Inherits the same class as \R\Users,
-     * but the usage may differ!
-     *
-     * Note! To fetch a particular repo under a user, you
-     * should go through the user (see method below).
-     * 
-     * @return \Request\Repos
-     */
-    public function repos() {
-        return new Request\Repos($this->url, $this->token);
-    }
+        /** 
+         * @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;
+            $this->token = $api_token;
+        }
 
-    /** 
-     * Returns either
-     * * the authorized user ($name = "" or "me")
-     * * the specified user ($name = anything else)
-     * 
-     * @return \Request\User
-     */
-    public function user(string $name = "me") {
-        return new Request\User($this->url, $this->token, $name);
-    }
+        /** 
+         * Returns a Request\Users object to fetch users from the
+         * Gogs installation. 
+         *
+         * @see Request\Users class to understand usage (e.g ->load() to fetch all, 
+         * ->search(array params) to search for one or several 
+         * users etc).
+         * 
+         * @return Request\Users
+         */
+        public function users() {
+            return new Request\Users($this->url, $this->token);
+        }
 
-    /** 
-     * Nothing to "destruct" at this time. 
-     * 
-     * @return null
-     */
-    public function __destruct() {}
+        /** 
+         * Get a single user from Gogs.
+         *
+         * Returns either
+         * * the authorized user ($name = "" or "me")
+         * * the specified user ($name = anything else)
+         * 
+         * @return Request\User
+         */
+        public function user(string $name = "me") {
+            return new Request\User($this->url, $this->token, $name);
+        }
+
+        /** 
+         * Returns an \Request\Repos to fetch repositories
+         * on the Gogs installation. 
+         *
+         * @see \Request\Repos to understand usage. Inherits 
+         * the same class as \R\Users, but the usage may differ!
+         *
+         * Note! To fetch a particular repo under a user, you
+         * should go through the user (see method below).
+         * 
+         * @return Request\Repos
+         */
+        public function repos() {
+            return new Request\Repos($this->url, $this->token);
+        }
+
+        /** 
+         * @return null
+         */
+        public function __destruct() {}
+    }
 }
 ?>

+ 82 - 4
src/API/Request/Base.php

@@ -2,6 +2,16 @@
 
 namespace Gogs\API\Request {
 
+    /**
+     * 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.
+     *
+     * @deprecated since 0.1, to be removed in 3.0
+     * @abstact
+     */
     abstract class Base implements RequestInterface {
 
         protected $loaded = false;
@@ -13,12 +23,25 @@ namespace Gogs\API\Request {
             delete as private mdelete;
         }
 
+        /**
+         * @param string $api_url The URL to the API.
+         * @param string $api_token A token for an authorized user
+         */
         public function __construct(string $api_url, string $api_token) {
             $this->url = $api_url;
             $this->token = $api_token;
         }
 
-        public function load(bool $force = false) {
+        /**
+         * Load an object.
+         *
+         * If `$force = true` the object will be fetched
+         * from the Gogs API again.
+         *
+         * @deprecated since 2.0 to be removed in 3.0
+         * @return object
+         */
+        final public function load(bool $force = false) {
             $this->set_scope("get");
 
             if ($this->loaded && !$force)
@@ -32,23 +55,72 @@ namespace Gogs\API\Request {
             return $this;
         }
 
-        protected function method_get(array $params = array()) {
+        /**
+         * Perform a GET-request against the Gogs API.
+         *
+         * Ensure the correct scope i set first, with
+         * ```php
+         * $this->set_scope("*valid scope*"); // e.g create
+         * ```
+         *
+         * @param array $params The parameters
+         * @return string
+         */
+        final protected function method_get(array $params = array()) {
             return $this->mget($this->scope, $params);
         }
 
-        protected function method_post(array $params = array()) {
+        /**
+         * Perform a POST-request against the Gogs API.
+         *
+         * Ensure the correct scope i set first, with
+         * ```php
+         * $this->set_scope("*valid scope*"); // e.g create
+         * ```
+         *
+         * @param array $params The parameters
+         * @return string
+         */
+        final protected function method_post(array $params = array()) {
             return $this->mpost($this->scope, $params);
         }
 
-        protected function method_delete() {
+        /**
+         * 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
+         * ```
+         *
+         * @return string
+         */
+        final protected function method_delete() {
             return $this->mdelete($this->scope);
         }
 
+        /** 
+         * Get object references by identifier.
+         *
+         * @param string $s Identifier to look up.
+         * @return null
+         */
         public function get(string $s) {
             if (!$this->set_scope("get"))
                 throw new Exception\NotImplementedException("::get:: Not implemented for class");
+
+            return null;
         }
 
+        /** 
+         * 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.
+         *
+         * @param string $args yeah, well
+         * @return true
+         */
         public function create(...$args) {
 
             if ($this->loaded)
@@ -64,6 +136,12 @@ namespace Gogs\API\Request {
             return true;
         }
 
+        /**
+         * Patch (update) object
+         *
+         * @throws Exception\InvalidMethodRequestException
+         * @throws Exception\NotImplementedException
+         */
         public function patch() {
 
             if (!$this->loaded)

+ 6 - 1
src/API/Request/Collection.php

@@ -51,7 +51,12 @@ namespace Gogs\API\Request {
             return reset($this->objs);
         }
 
-        //abstract public function create(...$args);
+        /** 
+         * Search for an object.
+         *
+         * @param array $params Parameters
+         * @return Gogs\Lib\Collection
+         */
         abstract public function search(array $params = array());
     }
 

+ 1 - 1
src/API/Request/Org.php

@@ -2,7 +2,7 @@
 
 namespace Gogs\API\Request {
 
-    class Org extends User {
+    final class Org extends User {
         public $udescription;
         public $uwebsite;
         public $ulocation;

+ 37 - 1
src/API/Request/Orgs.php

@@ -2,7 +2,13 @@
 
 namespace Gogs\API\Request {
 
-    class Orgs extends Collection {
+    /** 
+     * Orgs is a collection of organizations.
+     *
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     * @version 0.1
+     */
+    final class Orgs extends Collection {
         protected $owner;
 
         public function __construct(string $api_url, string $api_token, User $owner) {
@@ -28,6 +34,20 @@ namespace Gogs\API\Request {
             return $org;
         }
 
+        /** 
+         * 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. 
+         * 
+         * @param string $s 
+         * @return Org
+         */
         public function get(string $s) {
 
             if (($org = $this->by_key($s)))
@@ -36,6 +56,22 @@ namespace Gogs\API\Request {
             return new Org($this->url, $this->token, $s, $this->owner);
         }
 
+        /**
+         * 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.
+         *
+         * @param array $params
+         * @return CollectionResult
+         */
         public function search(array $params = array()) {
 
             if (!isset($params["name"]) && !isset($params["q"]))

+ 1 - 1
src/API/Request/Repo.php

@@ -2,7 +2,7 @@
 
 namespace Gogs\API\Request {
 
-    class Repo extends Base {
+    final class Repo extends Base {
         
         public $rid;
         public $rowner;

+ 77 - 77
src/API/Request/Repos.php

@@ -2,105 +2,105 @@
 
 namespace Gogs\API\Request {
 
-class Repos extends Collection {
+    final class Repos extends Collection {
 
-    protected $owner;
+        protected $owner;
 
-    public function __construct(string $api_url, string $api_token, User $owner = null) {
-        $this->owner = $owner;
-        parent::__construct($api_url, $api_token);
-    }
-
-    protected function set_scope(string $method) {
-        switch ($method) {
-        case "get":
-            if ($this->owner instanceof Org)
-                $this->scope = "/orgs/" . $this->owner->uusername . "/repos";
-            else
-                $this->scope = ($this->owner == null || $this->owner->authenticated() ? "/user" : "/users/" . $this->owner->uusername ) . "/repos";
-            break;
-        case "search":
-            $this->scope = "/repos/search";
-            break;
-        default:
-            return false;
+        public function __construct(string $api_url, string $api_token, User $owner = null) {
+            $this->owner = $owner;
+            parent::__construct($api_url, $api_token);
         }
 
-        return true;
-    }
+        protected function set_scope(string $method) {
+            switch ($method) {
+            case "get":
+                if ($this->owner instanceof Org)
+                    $this->scope = "/orgs/" . $this->owner->uusername . "/repos";
+                else
+                    $this->scope = ($this->owner == null || $this->owner->authenticated() ? "/user" : "/users/" . $this->owner->uusername ) . "/repos";
+                break;
+            case "search":
+                $this->scope = "/repos/search";
+                break;
+            default:
+                return false;
+            }
 
-    public function create(...$args) {
+            return true;
+        }
 
-        $repo = new Repo($this->url, $this->token, $this->owner);
+        public function create(...$args) {
 
-        if (count($args) > 0)
-            $repo->create(...$args);
+            $repo = new Repo($this->url, $this->token, $this->owner);
 
-        return $repo;
-    }
+            if (count($args) > 0)
+                $repo->create(...$args);
 
-    public function search(array $params = array()) {
-        $scope = substr($this->scope, 1, strpos($this->scope, "/", 1)-1);
+            return $repo;
+        }
 
-        if (!isset($params["name"]) && !isset($params["q"]))
-            throw new Exception\SearchParamException("Missing param <name>|<q>");
+        public function search(array $params = array()) {
+            $scope = substr($this->scope, 1, strpos($this->scope, "/", 1)-1);
 
-        if (isset($params["name"])) {
-            $params["q"] = $params["name"];
-            unset($params["name"]);
-        }
+            if (!isset($params["name"]) && !isset($params["q"]))
+                throw new Exception\SearchParamException("Missing param <name>|<q>");
 
-        if (!isset($params["user"]))
-            $params["user"] = 0;
-
-        if (!isset($params["limit"]))
-            $params["limit"] = 10;
-
-        $repos = new \Gogs\Lib\Collection();
-        
-        switch ($scope) {
-        case "user":
-        case "users":
-        case "org":
-            $this->load();
-
-            foreach($this->all() as $key => $repo) {
-                if ($repo->search($params["q"]))
-                    $repos->set($repo);
-                if ($repos->len() == $params["limit"])
-                    break;
+            if (isset($params["name"])) {
+                $params["q"] = $params["name"];
+                unset($params["name"]);
             }
 
-        default:
-            $this->set_scope("search");
-            $jenc = $this->method_get($params);
-            $jdec = $this->json_decode($jenc);
+            if (!isset($params["user"]))
+                $params["user"] = 0;
 
-            foreach($this->json_set_property($jdec) as $key)
-                $repos->set($this->by_key($key), $key);
+            if (!isset($params["limit"]))
+                $params["limit"] = 10;
 
-        }
-        
-        return $repos;
-    }
+            $repos = new \Gogs\Lib\Collection();
+            
+            switch ($scope) {
+            case "user":
+            case "users":
+            case "org":
+                $this->load();
+
+                foreach($this->all() as $key => $repo) {
+                    if ($repo->search($params["q"]))
+                        $repos->set($repo);
+                    if ($repos->len() == $params["limit"])
+                        break;
+                }
 
-    protected function json_set_property($obj) {
-        if (isset($obj->data))
-            return $this->json_set_property($obj->data);
+            default:
+                $this->set_scope("search");
+                $jenc = $this->method_get($params);
+                $jdec = $this->json_decode($jenc);
 
-        $rnames = array();
+                foreach($this->json_set_property($jdec) as $key)
+                    $repos->set($this->by_key($key), $key);
 
-        if (is_array($obj)) {
-            foreach ($obj as $key => $val) {
-                $repo = new Repo($this->url, $this->token);
-                $repo->json_set_property($val);
-                $this->add($repo, $repo->rfull_name);
-                array_push($rnames, $repo->rfull_name);
             }
+            
+            return $repos;
         }
 
-        return $rnames;
+        protected function json_set_property($obj) {
+            if (isset($obj->data))
+                return $this->json_set_property($obj->data);
+
+            $rnames = array();
+
+            if (is_array($obj)) {
+                foreach ($obj as $key => $val) {
+                    $repo = new Repo($this->url, $this->token);
+                    $repo->json_set_property($val);
+                    $this->add($repo, $repo->rfull_name);
+                    array_push($rnames, $repo->rfull_name);
+                }
+            }
+
+            return $rnames;
+        }
     }
-}
 
 }

+ 41 - 1
src/API/Request/RequestInterface.php

@@ -2,11 +2,51 @@
 
 namespace Gogs\API\Request {
 
+    /** 
+     * Request interface, used by any kind of request object.
+     *
+     * @author Joachim M. Giaever (joachim[]giaever.org)
+     * @version 0.1
+     */
     interface RequestInterface {
-        public function load(bool $force = true);
+
+        /** 
+         * Load object. 
+         *
+         * @todo reconsider $force = false
+         * @param bool $force Force update, default: true
+         * @return object
+         */
+        public function load(bool $force = false);
+
+        /** 
+         * Get by identifier
+         *
+         * @param string $s The idientifier to look up
+         * @return object
+         */
         public function get(string $s);
+
+        /**
+         * Create object
+         *
+         * @param ... $args Arguments required by create.
+         * @return bool
+         */
         public function create(...$args);
+
+        /**
+         * Patch (update) object
+         * 
+         * @return bool
+         */
         public function patch();
+
+        /**
+         * Delete object
+         *
+         * @return bool
+         */
         public function delete();
     }
 

+ 1 - 1
src/API/Request/User.php

@@ -2,7 +2,7 @@
 
 namespace Gogs\API\Request {
 
-    class User extends Base {
+    final class User extends Base {
 
         private $authenticated;
         public $uid;

+ 1 - 1
src/API/Request/Users.php

@@ -8,7 +8,7 @@ namespace Gogs\API\Request {
      * @author Joachim M. Giaever (joachim[]giaever.org)
      * @package request
      */
-    class Users extends Collection {
+    final class Users extends Collection {
 
         protected function set_scope(string $method) {
             switch ($method) {