Ferreteria/v0.6/clade/Sys/Events/ItWent

clade: Sys\Events\ItWent

Clade Family
StandardBase	→ ItWent	→ CommOp → ReadOp
Clade Aliases Alias Clade Base* StandardBase Msg* Message

About

• purpose: an object that can report status and any related messages (usually errors or warnings) resulting from an attempted action, i.e. "how it went"

Any object can make use of this feature via the Sys\Events\has\ItWent iface/trait.

Code

as of 2025-10-01

interface iItWent extends BaseIface {
    // SETUP
    static function AsNoOp() : self;
    // ACTION
    function WasTried() : bool;
    function SetOkay(bool $ok);
    function GetOkay() : bool;
    function SetNoOp();
    function GetStatusText() : string;
    // MESSAGES
    function AllMessages() : array; // mainly diagnostic
    function AnyMessages() : bool;
    function AddMsgObject(MsgIface $o) : void;
    function AddMsgString(string $s) : void;
    function RenderMessages() : string;
    // ERRORS
    function HasError() : bool;
    function SetError(int $n);
}

class cItWent extends BaseClass implements SelfIface {

    // ++ CONFIG ++ //

    protected function MessageClass() : string { return MsgClass::class; }

    // -- CONFIG -- //
    // ++ SETUP ++ //

    static public function AsNoOp() : SelfIface { $o = new static; $o->SetNoOp(); return $o; }

    // -- SETUP -- //
    // ++ ACTION ++ //
    
    private $isTried = FALSE; // was the action tried?
    public function WasTried() : bool { return $this->isTried; }
    
    private $isOkay = FALSE;          // if tried, did it succeed?
    public function SetOkay(bool $ok) {
        $this->isTried = TRUE;
        $this->isOkay = $ok;
    }
    public function GetOkay() : bool {
        if ($this->isTried {{|}}{{|}} $this->isOkay) {
            return $this->isOkay;
        } else {
            $sError = 'action status requested before action attempted.';
            throw new \exception('Internal error: '.$sError);
        }
    }
    public function SetNoOp() {
        $this->isTried = FALSE;
        $this->isOkay = TRUE;
    }
    public function GetStatusText() : string {
        if ($this->WasTried()) {
            if ($this->GetOkay()) {
                $out = 'Operation successful.';
            } else {
                if ($this->HasError()) {
                    $nErr = $this->GetNumber();
                    $sErr = $this->GetMessage();
                    $out = "Error #$nErr: $sErr";
                } else {
                    $out = 'Operation failed.';
                }
                $out .= ' (TODO: add any Messages, or note how many there are.)';   // 2025-01-24
            }
        } else {
            $out = 'Operation has not been attempted yet!';
        }
        return $out;
    }
    
    // -- ACTION -- //
    // ++ RESULT ++ //

    private $arMsgs = [];
    public function AllMessages() : array { return $this->arMsgs; }
    public function AnyMessages() : bool { return count($this->arMsgs) > 0; }
    public function AddMsgObject(MsgIface $o) : void { $this->arMsgs[] = $o; }
    public function AddMsgString(string $s) : void {
        $o = new ($this->MessageClass())($s);
        $this->AddMsgObject($o);
    }
    public function RenderMessages() : string {
        $oScrn = self::Screen();
        if ($this->GetOkay()) {
            $sOut = '';
        } else {
            $sOut = $oScrn->ErrorIt('Error report');
            if ($this->HasError()) {
                $ftErNum = $oScrn->BoldIt($this->GetNumber());
                $sOut .= " code $ftErNum.".CRLF;  // 2025-01-25 This will need some revision.
            } else {
                $sOut .= ':'.CRLF;
            }
        }
        $ar = $this->arMsgs;
        foreach ($ar as $oMsg) {
            $sOut .= ' - '.$oMsg->Full().CRLF;
        }
        return $sOut;
    }

    // ++ RESULT: errors ++ //

    private $nErr = NULL;
    public function SetError(int $n) { $this->nErr = $n; }
    public function GetError() : int { return $this->nErr; }
    public function HasError() : bool { return $this->nErr > 0; }

    // -- RESULT -- //
}