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
Code
as of 2026-01-04:
#
interface iItWent extends BaseIface {
// SETUP
static function AsNoOp() : self;
function CopyFrom(self $o); // direct copy, overriding self
function Assimilate(self $o); // include any errors or messages from $o
function Clear();
// 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 QtyMessages() : int;
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 InspectorClass() : string { return ViewClass::class; }
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();
}
public function Assimilate(SelfIface $o) {
$this->isTried = $o->WasTried();
if ($this->isOkay) $this->isOkay = $o->GetOkay();
$this->arMsgs = array_merge($this->arMsgs, $o->AllMessages());
if ($o->HasError) $this->nErr = $o->GetError();
}
public function Clear() {
$this->isTried = FALSE;
$this->arMsgs = [];
$this->nErr = NULL;
}
// -- SETUP -- //
// ++ STATE ++ //
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;
}
// -- STATE -- //
// ++ RESULT ++ //
private $arMsgs = [];
public function AllMessages() : array { return $this->arMsgs; }
public function AnyMessages() : bool { return count($this->arMsgs) > 0; }
public function QtyMessages() : int { return count($this->arMsgs); }
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 -- //
}