path: root/app/class/issue.class.php

<?php

/*
 * SCROTT IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
 * OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
 * OTHER DEALINGS IN THE SOFTWARE.
 *
 * For more information, please refer to UNLICENSE
 */

require_once "class/obj.class.php";
require_once "class/stage.class.php";
require_once "class/user.class.php";
require_once "class/mesg.class.php";

/*
 * This class models Scrott issues.  Issues represent units of work, can
 * be assigned to users, and advance through a pipeline.
 */
class issue extends obj
{
    /*
     * Constructor
     */
    public function __construct(?string $guid = NULL)
    {
        $this->fields['issues'] = array(
            "guid",
            "numb",
            "assignee",
            "author",
            "closer",
            "seen",
            "description",
            "opened",
            "assigned",
            "authored",
            "closed",
            "due",
            "tags",
        );

        parent::__construct($guid);
        $this->expectType("issue");
    }

    /*
     * Initialize a new issue object with the given name, parent, and
     * owner.
     */
    public static function initNew(string $name, user $owner, stage $parent) : issue
    {
        $pad = $parent->getParent();
        $numb = $pad->issueNumb++;
        $pad->saveObj();

        $issue = new issue();
        $issue->setOwner($owner);
        $issue->setParent($parent);
        $issue->name = $name;
        $issue->objtype = "issue";
        $issue->numb = $numb;
        $issue->setAuthor($owner);
        $issue->saveObj(); // get timestamp
        $issue->opened = $issue->created;
        $issue->authored = $issue->created;
        $issue->saveObj();
        return $issue;
    }

    /*
     * Get the assignee for this issue
     */
    public function getAssignee() : ?user
    {
        if (!isset($this->assignee) || $this->assignee == "")
            return NULL;

        return new user($this->assignee);
    }

    /*
     * Reset the seen flag and reassign this issue.
     */
    public function assignTo(user $assignee) : void
    {
        $this->seen = 0;
        $this->assignee = $assignee->guid;
        $this->assigned = self::getCurrentTimestamp();
        $this->saveObj();
    }

    /*
     * Get the author of this issue.  This is usually the user
     * that opened the issue, but may differ if this issue was
     * elevated from a previous discussion thread.
     */
    public function getAuthor() : user
    {
        if (!isset($this->author) || $this->author == "")
            return NULL;

        return new user($this->author);
    }

    /*
     * Set the author of this issue.  This should usually only
     * be done while constructing a new message or to clear out
     * references to a user that got removed.
     */
    public function setAuthor(user $author) : void
    {
        $this->author = $author->guid;
        $this->saveObj();
    }

    /*
     * Get the user that closed this issue.  If the issue is still
     * open, NULL is returned.
     */
    public function getCloser() : ?user
    {
        if (!isset($this->closer) || $this->closer == "")
            return NULL;

        return new user($this->closer);
    }

    /*
     * Mark the user that closed this issue.
     */
    public function setCloser(user $closer) : void
    {
        $this->closer = $closer->guid;
        $this->saveObj();
    }

    /*
     * Get the pad this issue exists under
     */
    public function getPad() : pad
    {
        $parent = $this->getParent();

        if ($parent->objtype == "pad")
            return $parent;

        return $parent->getParent();
    }

    /*
     * Advance this issue in the pipeline, closing it if already in the
     * last stage.
     */
    public function advance() : void
    {
        $stage = $this->getParent();

        if ($stage->objtype != "stage")
            return;

        if (!($next = $stage->getNext()))
            $this->close();
        else
            $this->setParent($next);
    }

    /*
     * Mark this issue as completed and closed.
     */
    public function close(user $closer) : void
    {
        $pad = $this->getParent()->getParent();

        if ($pad)
        {
            $this->closed = self::getCurrentTimestamp();
            $this->setCloser($closer);
            $this->setParent($pad);
        }
    }

    /*
     * Check whether issue is currently open or closed.
     */
    public function isOpen() : bool
    {
        return self::typeOf($this->parent) != "pad";
    }
}

?>