ProjectService.php

<?php

namespace JiraCloud\Project;

use JiraCloud\Component\Component;
use JiraCloud\Issue\IssueType;
use JiraCloud\Issue\Reporter;
use JiraCloud\Issue\Version;
use JiraCloud\JiraException;
use JiraCloud\Role\Role;

class ProjectService extends \JiraCloud\JiraClient
{
    private $uri = '/project';

    /**
     * get all project list.
     *
     * @param array $paramArray
     *
     * @throws \JiraCloud\JiraException
     *
     * @return Project[] array of Project class
     */
    public function getAllProjects($paramArray = [])
    {
        $ret = $this->exec($this->uri.$this->toHttpQueryParameter($paramArray), null);

        $prjs = $this->json_mapper->mapArray(
            json_decode($ret, false),
            new \ArrayObject(),
            Project::class
        );

        return $prjs;
    }

    /**
     * get a paginated list of projects.
     *
     * @param array $paramArray
     *
     * @throws \JiraCloud\JiraException
     *
     * @return PaginatedResult
     */
    public function getProjectsPaginated($paramArray = []): PaginatedResult
    {
        $ret = $this->exec($this->uri.'/search'.$this->toHttpQueryParameter($paramArray), null);

        $decodedRet = json_decode($ret, false);

        $decodedRet->values = $this->json_mapper->mapArray(
            $decodedRet->values,
            new \ArrayObject(),
            Project::class
        );

        $prjsPag = $this->json_mapper->map(
            $decodedRet,
            new PaginatedResult()
        );

        return $prjsPag;
    }

    /**
     * get Project id By Project Key.
     * throws HTTPException if the project is not found, or the calling user does not have permission or view it.
     *
     * @param string|int $projectIdOrKey projectName or Project Key(Ex: Test, MyProj)
     *
     * @throws \JiraCloud\JiraException
     * @throws \JsonMapper_Exception
     */
    public function get(string|int $projectIdOrKey): Project
    {
        $ret = $this->exec($this->uri."/$projectIdOrKey", null);

        $this->log->info('Result='.$ret);

        $prj = $this->json_mapper->map(
            json_decode($ret),
            new Project()
        );

        return $prj;
    }

    /**
     * get assignable Users for a given project.
     * throws HTTPException if the project is not found, or the calling user does not have permission or view it.
     *
     * @param string|int $projectIdOrKey Project Key
     *
     * @throws \JiraCloud\JiraException
     *
     * @return Reporter[]
     */
    public function getAssignable(string|int $projectIdOrKey): array
    {
        $ret = $this->exec("/user/assignable/search?project=$projectIdOrKey", null);
        $json = json_decode($ret);
        $results = array_map(function ($elem) {
            return $this->json_mapper->map($elem, new Reporter());
        }, $json);

        return $results;
    }

    /**
     * @param string|int $projectIdOrKey
     *
     * @throws \JiraCloud\JiraException
     *
     * @return IssueType[]
     */
    public function getStatuses($projectIdOrKey)
    {
        $ret = $this->exec($this->uri."/$projectIdOrKey/statuses", null);
        $json = json_decode($ret);
        $results = array_map(function ($elem) {
            return $this->json_mapper->map($elem, new IssueType());
        }, $json);

        return $results;
    }

    /**
     * Get the Components defined in a Jira Project.
     *
     * @param string|int $projectIdOrKey
     *
     * @throws \JiraCloud\JiraException
     *
     * @return \JiraCloud\Component\Component[]
     */
    public function getProjectComponents($projectIdOrKey)
    {
        $ret = $this->exec($this->uri."/$projectIdOrKey/components", null);
        $json = json_decode($ret);
        $results = array_map(function ($elem) {
            return $this->json_mapper->map($elem, new Component());
        }, $json);

        return $results;
    }

    /**
     * make transition info array for project issue transition.
     *
     * @param string|int $projectIdOrKey
     *
     * @throws JiraException
     *
     * @return array
     * @return array
     */
    public function getProjectTransitionsToArray($projectIdOrKey)
    {
        $ret = $this->exec($this->uri."/$projectIdOrKey/statuses", null);
        $json = json_decode($ret);
        $results = array_map(function ($elem) {
            return $this->json_mapper->map($elem, new IssueType());
        }, $json);

        $transitions = [];
        foreach ($results as $issueType) {
            foreach ($issueType->statuses as $status) {
                if (!in_array($status->id, array_column($transitions, 'id'))) {
                    $transitions[] = [
                        'id'               => $status->id,
                        'name'             => $status->name,
                        'untranslatedName' => $status->untranslatedName ?? $status->name,
                    ];
                }
            }
        }

        return $transitions;
    }

    /**
     * @throws \JiraCloud\JiraException
     *
     * @return ProjectType[]
     */
    public function getProjectTypes()
    {
        $ret = $this->exec($this->uri.'/type');

        $this->log->info('Result='.$ret);

        $json = json_decode($ret);
        $results = array_map(function ($elem) {
            return $this->json_mapper->map($elem, new ProjectType());
        }, $json);

        return $results;
    }

    /**
     * @param string|int $key
     *
     * @throws \JiraCloud\JiraException
     * @throws \JsonMapper_Exception
     *
     * @return ProjectType
     */
    public function getProjectType($key)
    {
        $ret = $this->exec($this->uri."/type/$key");

        $this->log->info('Result='.$ret);

        $type = $this->json_mapper->map(
            json_decode($ret, false),
            new ProjectType()
        );

        return $type;
    }

    /**
     * @param string|int $key
     *
     * @throws \JiraCloud\JiraException
     * @throws \JsonMapper_Exception
     *
     * @return ProjectType
     */
    public function getAccessibleProjectType($key)
    {
        $ret = $this->exec($this->uri."/type/$key/accessible");

        $this->log->info('Result='.$ret);

        $type = $this->json_mapper->map(
            json_decode($ret, false),
            new ProjectType()
        );

        return $type;
    }

    /**
     * get pagenated Project versions.
     *
     * @param string|int $projectIdOrKey
     * @param array      $queryParam
     *
     * @throws \JiraCloud\JiraException
     *
     * @return Version[] array of version
     */
    public function getVersionsPagenated($projectIdOrKey, $queryParam = [])
    {
        $default = [
            'startAt'    => 0,
            'maxResults' => 50,
            // order by following field: sequence, name, startDate, releaseDate
            //'orderBy' => null,
            //'expand' => null,
        ];

        $param = $this->toHttpQueryParameter(
            array_merge($default, $queryParam)
        );

        $ret = $this->exec($this->uri."/$projectIdOrKey/version".$param);

        $this->log->info('Result='.$ret);

        //@see https://docs.atlassian.com/jira/REST/server/#api/2/project-getProjectVersions
        $json = json_decode($ret);

        $versions = $this->json_mapper->mapArray(
            $json->values,
            new \ArrayObject(),
            '\JiraCloud\Issue\Version'
        );

        return $versions;
    }

    /**
     * get specified's project versions.
     */
    public function getVersions(string $projectIdOrKey): \ArrayObject
    {
        $ret = $this->exec($this->uri."/$projectIdOrKey/versions");

        $this->log->info('Result='.$ret);

        $versions = $this->json_mapper->mapArray(
            json_decode($ret, false),
            new \ArrayObject(),
            '\JiraCloud\Issue\Version'
        );

        return $versions;
    }

    /**
     * get specified's project version.
     *
     * @param string|int $projectIdOrKey
     * @param string     $versionName
     *
     * @throws \JiraCloud\JiraException
     *
     * @return Version version
     */
    public function getVersion($projectIdOrKey, $versionName)
    {
        $ret = $this->exec($this->uri."/$projectIdOrKey/versions");

        $this->log->info('Result='.$ret);

        $versions = $this->json_mapper->mapArray(
            json_decode($ret, false),
            new \ArrayObject(),
            '\JiraCloud\Issue\Version'
        );

        foreach ($versions as $v) {
            if ($v->name === $versionName) {
                return $v;
            }
        }

        throw new JiraException("Can't found version \"$versionName\" in the Project \"$projectIdOrKey\"");
    }

    /**
     * Creates a new project.
     *
     * @param Project $project
     *
     * @throws JiraException
     *
     * @return Project project
     */
    public function createProject($project)
    {
        $data = json_encode($project);

        $ret = $this->exec($this->uri, $data, 'POST');

        $this->log->info('createProject Result='.$ret);

        return $this->json_mapper->map(
            json_decode($ret),
            new Project()
        );
    }

    /**
     * Updates a project.
     *
     * Only non null values sent in JSON will be updated in the project.
     * Values available for the assigneeType field are: "PROJECT_LEAD" and "UNASSIGNED".
     *
     * @param Project $project
     *
     * @throws JiraException
     * @throws \JsonMapper_Exception
     *
     * @return Project project
     */
    public function updateProject($project, $projectIdOrKey)
    {
        $data = json_encode($project);

        $ret = $this->exec($this->uri.'/'.$projectIdOrKey, $data, 'PUT');

        $this->log->info('updateProject Result='.$ret);

        return $this->json_mapper->map(
            json_decode($ret),
            new Project()
        );
    }

    /**
     * @param string $projectIdOrKey
     *
     * @throws JiraException
     *
     * @return string response status
     *
     * STATUS 401 Returned if the user is not logged in.
     * STATUS 204 - application/json Returned if the project is successfully deleted.
     * STATUS 403 - Returned if the currently authenticated user does not have permission to delete the project.
     * STATUS 404 - Returned if the project does not exist.
     */
    public function deleteProject($projectIdOrKey)
    {
        $ret = $this->exec($this->uri.'/'.$projectIdOrKey, null, 'DELETE');

        return $ret;
    }

    /**
     * Archive a project only available for premium subscription.
     *
     * @param string $projectIdOrKey
     *
     * @throws JiraException
     *
     * @return string response status
     *
     * STATUS 401 Returned if the user is not logged in.
     * STATUS 204 - application/json Returned if the project is successfully archived.
     * STATUS 403 - Returned if the currently authenticated user does not have permission to archive the project.
     * STATUS 404 - Returned if the project does not exist.
     * STATUS 405 - Method not allowed specified request HTTP method was received and recognized by the server, but is not supported by the target resource.
     */
    public function archiveProject($projectIdOrKey)
    {
        $ret = $this->exec($this->uri.'/'.$projectIdOrKey.'/archive', null, 'PUT');

        return $ret;
    }

    /**
     * @param $projectIdOrKey
     *
     * @throws JiraException
     *
     * @return array<string, string>
     *
     * STATUS 401 Returned if the user is not logged in.
     * STATUS 404 - Returned if the project does not exist.
     */
    public function getProjectRoles($projectIdOrKey)
    {
        $response = $this->exec($this->uri.'/'.$projectIdOrKey.'/role');

        $this->log->info('getProjectRoles Result='.$response);

        return (array) json_decode($response);
    }

    /**
     * @param $projectIdOrKey
     * @param $roleId
     *
     * @throws JiraException
     *
     * @return Role
     *
     * STATUS 401 Returned if the user is not logged in.
     * STATUS 404 - Returned if the project does not exist.
     */
    public function getProjectRole($projectIdOrKey, $roleId, $excludeInactiveUsers = false)
    {
        $response = $this->exec($this->uri.'/'.$projectIdOrKey.'/role/'.$roleId.'?excludeInactiveUsers='.$excludeInactiveUsers);

        $this->log->info('getProjectRole Result='.$response);

        $reporters = array_map(
            function ($elem) {
                $reporter = $this->json_mapper->map($elem, new Reporter());
                $reporter->accountId = $elem->actorUser->accountId;

                return $reporter;
            },
            array_filter(json_decode($response)->actors, function ($elem) {
                return $elem->type === 'atlassian-user-role-actor';
            }),
        );

        $role = $this->json_mapper->map(
            json_decode($response),
            new Role()
        );
        $role->actors = $reporters;

        return $role;
    }
}