1<?php
2
3namespace dokuwiki\plugin\issuelinks\services;
4
5use dokuwiki\Form\Form;
6use dokuwiki\plugin\issuelinks\classes\Issue;
7use dokuwiki\plugin\issuelinks\classes\Repository;
8use dokuwiki\plugin\issuelinks\classes\RequestResult;
9
10interface ServiceInterface
11{
12    const WEBHOOK_URL = DOKU_URL . 'lib/plugins/issuelinks/webhook.php';
13
14    /**
15     * Get the singleton instance of the Services
16     *
17     * @return ServiceInterface
18     */
19    public static function getInstance();
20
21    /**
22     * Decide whether the provided issue is valid
23     *
24     * @param Issue $issue
25     *
26     * @return bool
27     */
28    public static function isIssueValid(Issue $issue);
29
30    /**
31     * Provide the character separation the project name from the issue number, may be different for merge requests
32     *
33     * @param bool $isMergeRequest
34     *
35     * @return string
36     */
37    public static function getProjectIssueSeparator($isMergeRequest);
38
39    public static function isOurWebhook();
40
41    /**
42     * Get the url to the given issue at the given project
43     *
44     * @param      $projectId
45     * @param      $issueId
46     * @param bool $isMergeRequest ignored, GitHub routes the requests correctly by itself
47     *
48     * @return string
49     */
50    public function getIssueURL($projectId, $issueId, $isMergeRequest);
51
52    /**
53     * @param string $issueSyntax
54     *
55     * @return Issue
56     */
57    public function parseIssueSyntax($issueSyntax);
58
59    /**
60     * @return bool
61     */
62    public function isConfigured();
63
64    /**
65     * @param Form $configForm
66     *
67     * @return void
68     */
69    public function hydrateConfigForm(Form $configForm);
70
71    public function handleAuthorization();
72
73    public function getUserString();
74
75    /**
76     * Optional, return HTML to be displayed on the repo page for a project
77     *
78     * @return string
79     */
80    public function getRepoPageText();
81
82    public function retrieveIssue(Issue $issue);
83
84    public function retrieveAllIssues($projectKey, &$startat = 0);
85
86    /**
87     * Get the total of issues currently imported by retrieveAllIssues()
88     *
89     * This may be an estimated number
90     *
91     * @return int
92     */
93    public function getTotalIssuesBeingImported();
94
95    /**
96     * Get a list of all organisations a user is member of
97     *
98     * @return string[] the identifiers of the organisations
99     */
100    public function getListOfAllUserOrganisations();
101
102    /**
103     * @param $organisation
104     *
105     * @return Repository[]
106     */
107    public function getListOfAllReposAndHooks($organisation);
108
109    /**
110     * Create a webhook at the repository
111     *
112     * @param string $project full name of the project
113     *
114     * @return array
115     */
116    public function createWebhook($project);
117
118    /**
119     * Delete our webhook in a source repository
120     *
121     * @param string $project full name of the project
122     * @param int    $hookid  the numerical id of the hook to be deleted
123     *
124     * @return array
125     */
126    public function deleteWebhook($project, $hookid);
127
128    /**
129     * Do all checks to verify that the webhook is expected and actually ours
130     *
131     * @param $webhookBody
132     *
133     * @return true|RequestResult true if the the webhook is our and should be processed RequestResult with explanation
134     *                            otherwise
135     */
136    public function validateWebhook($webhookBody);
137
138    /**
139     * Handle the contents of the webhooks body
140     *
141     * @param $webhookBody
142     *
143     * @return RequestResult
144     */
145    public function handleWebhook($webhookBody);
146}
147