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

clade: Sys\Events\ItWent

Clade Family StandardBase → ItWent → CommOp → ReadOp → ItWent Clade Aliases Alias Clade Base* Aux\StandardBase Msg* Sys\Events\Message Subpages @history CommOp CommOp/MsgsOp ReadOp

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.

Pages

• /@history

Code

as of 2025-10-27

interface iItWent extends BaseIface {
    // SETUP
    static function AsNoOp() : self;
    function CopyFrom(self $o);
    // 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 SetError(int $n);
    function GetError() : ?int;
    function HasError() : bool;
}

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; }
    public function CopyFrom(SelfIface $o) {
        $this->isTried = $o->WasTried();
        $this->isOkay = $o->GetOkay();
        $this->arMsgs = $o->AllMessages();
        $this->nErr = $o->GetError();
    }

    // -- 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->GetError());
                $sOut .= " code $ftErNum.".CRLF;
            } 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 -- //
}

Removed

2025-10-26

Commented out earlier:

// 2025-10-01 old API
    private $hasError = FALSE;
    public function HasError() : bool { return $this->hasError; }
    public function AddError(int $n, string $s) : void {
        $this->hasError = TRUE;
        $o = new ($this->ErrorClass())($n,$s);
        $this->AddMsgObject($o);
    }

    // 2025-01-24 revising message system
    private $sMsg='';
    public function HasMessage() : bool { return !empty($this->sMsg); }
    public function SetMessage(string $s) { $this->sMsg = $s; }
    public function GetMessage() : string { return $this->sMsg; }