From 1665b12b860e1b04201eee099637d8dbd6383dd5 Mon Sep 17 00:00:00 2001 From: Pierre Goiffon Date: Thu, 27 Dec 2018 11:50:41 +0100 Subject: [PATCH] :bulb: PHPDoc for \DBObject::DBInsert methods hierarchy (and some more, too O:) ) --- application/cmdbabstract.class.inc.php | 10 ++ core/cmdbobject.class.inc.php | 29 +++- core/dbobject.class.php | 191 ++++++++++++++++++++----- 3 files changed, 197 insertions(+), 33 deletions(-) diff --git a/application/cmdbabstract.class.inc.php b/application/cmdbabstract.class.inc.php index 879c7ebbd..f0562c958 100644 --- a/application/cmdbabstract.class.inc.php +++ b/application/cmdbabstract.class.inc.php @@ -3690,6 +3690,9 @@ EOF return $aErrors; } + /** + * @inheritdoc + */ public function DBInsertNoReload() { $res = parent::DBInsertNoReload(); @@ -3707,6 +3710,7 @@ EOF } /** + * @inheritdoc * Attaches InlineImages to the current object */ protected function OnObjectKeyReady() @@ -3831,6 +3835,12 @@ EOF $this->bAllowWrite = $bAllow; } + /** + * @inheritdoc + * @throws \ArchivedObjectException + * @throws \CoreException + * @throws \OQLException + */ public function DoCheckToWrite() { parent::DoCheckToWrite(); diff --git a/core/cmdbobject.class.inc.php b/core/cmdbobject.class.inc.php index 1cfdb3f3b..0f5db54f7 100644 --- a/core/cmdbobject.class.inc.php +++ b/core/cmdbobject.class.inc.php @@ -188,6 +188,16 @@ abstract class CMDBObject extends DBObject self::$m_oCurrChange->DBInsert(); } + /** + * @inheritdoc + * @throws \ArchivedObjectException + * @throws \CoreCannotSaveObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \CoreWarning + * @throws \MySQLException + * @throws \OQLException + */ protected function RecordObjCreation() { // Delete any existing change tracking about the current object (IDs can be reused due to InnoDb bug; see TRAC #886) @@ -206,6 +216,7 @@ abstract class CMDBObject extends DBObject MetaModel::PurgeData($oFilter); parent::RecordObjCreation(); + $oMyChangeOp = MetaModel::NewObject("CMDBChangeOpCreate"); $oMyChangeOp->Set("objclass", get_class($this)); $oMyChangeOp->Set("objkey", $this->GetKey()); @@ -232,9 +243,17 @@ abstract class CMDBObject extends DBObject } /** - * @param $sAttCode + * @param string $sAttCode * @param $original Original value * @param $value Current value + * + * @throws \ArchivedObjectException + * @throws \CoreCannotSaveObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \CoreWarning + * @throws \MySQLException + * @throws \OQLException */ protected function RecordAttChange($sAttCode, $original, $value) { @@ -438,6 +457,14 @@ abstract class CMDBObject extends DBObject /** * @param array $aValues * @param array $aOrigValues + * + * @throws \ArchivedObjectException + * @throws \CoreCannotSaveObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \CoreWarning + * @throws \MySQLException + * @throws \OQLException */ protected function RecordAttChanges(array $aValues, array $aOrigValues) { diff --git a/core/dbobject.class.php b/core/dbobject.class.php index e9a767248..7b8505328 100644 --- a/core/dbobject.class.php +++ b/core/dbobject.class.php @@ -70,11 +70,14 @@ abstract class DBObject implements iDisplay { private static $m_aMemoryObjectsByClass = array(); - private static $m_aBulkInsertItems = array(); // class => array of ('table' => array of (array of )) - private static $m_aBulkInsertCols = array(); // class => array of ('table' => array of ) + /** @var array class => array of ('table' => array of (array of )) */ + private static $m_aBulkInsertItems = array(); + /** @var array class => array of ('table' => array of ) */ + private static $m_aBulkInsertCols = array(); private static $m_bBulkInsert = false; - protected $m_bIsInDB = false; // true IIF the object is mapped to a DB record + /** @var bool true IIF the object is mapped to a DB record */ + protected $m_bIsInDB = false; protected $m_iKey = null; private $m_aCurrValues = array(); protected $m_aOrigValues = array(); @@ -232,7 +235,9 @@ abstract class DBObject implements iDisplay /** * @param bool $bAllowAllData DEPRECATED: the reload must never fail! + * * @throws CoreException + * @internal */ public function Reload($bAllowAllData = false) { @@ -748,12 +753,24 @@ abstract class DBObject implements iDisplay } } } - + + /** + * Overridable callback, called by \DBObject::DoComputeValues + * + * @api + */ public function ComputeValues() { } - // Compute scalar attributes that depend on any other type of attribute + /** + * Compute scalar attributes that depend on any other type of attribute + * + * @throws \CoreException + * @throws \CoreUnexpectedValue + * + * @internal + */ final public function DoComputeValues() { // TODO - use a flag rather than checking the call stack -> this will certainly accelerate things @@ -1075,7 +1092,9 @@ abstract class DBObject implements iDisplay /** * Gets the name of an object in a safe manner for displaying inside a web page + * * @return string + * @throws \CoreException */ public function GetName() { @@ -1087,13 +1106,20 @@ abstract class DBObject implements iDisplay * since the " < > characters are not escaped and the name may contain some XSS script * instructions. * Use this function only for internal computations or for an output to a non-HTML destination + * * @return string + * @throws \CoreException */ public function GetRawName() { return $this->Get('friendlyname'); } + /** + * @return mixed|string '' if no state attribute, object representing its value otherwise + * @throws \CoreException + * @internal + */ public function GetState() { $sStateAttCode = MetaModel::GetStateAttributeCode(get_class($this)); @@ -1276,9 +1302,15 @@ abstract class DBObject implements iDisplay /** * Returns the set of flags (OPT_ATT_HIDDEN, OPT_ATT_READONLY, OPT_ATT_MANDATORY...) * for the given attribute for the current state of the object considered as an INITIAL state + * * @param string $sAttCode The code of the attribute + * @param array $aReasons + * * @return integer Flags: the binary combination of the flags applicable to this attribute - */ + * @throws \CoreException + * + * @api + */ public function GetInitialStateAttributeFlags($sAttCode, &$aReasons = array()) { $iFlags = 0; @@ -1290,17 +1322,18 @@ abstract class DBObject implements iDisplay return $iFlags; // No need to care about the synchro flags since we'll be creating a new object anyway } - // check if the given (or current) value is suitable for the attribute - // return true if successfull - // return the error desciption otherwise /** + * Check if the given (or current) value is suitable for the attribute + * * @param $sAttCode - * @param null $value + * @param boolean|string $value true if successfull, the error desciption otherwise * * @return bool|string * @throws \ArchivedObjectException * @throws \CoreException * @throws \OQLException + * + * @internal */ public function CheckValue($sAttCode, $value = null) { @@ -1431,8 +1464,13 @@ abstract class DBObject implements iDisplay } return true; } - - // check attributes together + + /** + * check attributes together + * + * @return bool + * @api + */ public function CheckConsistency() { return true; @@ -1558,12 +1596,15 @@ abstract class DBObject implements iDisplay } /** - * check integrity rules (before inserting or updating the object) - * a displayable error is returned + * Check integrity rules (before inserting or updating the object) + * + * Errors should be inserted in {@link $m_aCheckIssues} and {@link $m_aCheckWarnings} arrays * * @throws \ArchivedObjectException * @throws \CoreException * @throws \OQLException + * + * @api */ public function DoCheckToWrite() { @@ -1628,6 +1669,8 @@ abstract class DBObject implements iDisplay * @throws \ArchivedObjectException * @throws \CoreException * @throws \OQLException + * + * @internal do not overwrite ! Use {@link DoCheckToWrite} instead */ final public function CheckToWrite() { @@ -1657,6 +1700,10 @@ abstract class DBObject implements iDisplay // check if it is allowed to delete the existing object from the database // a displayable error is returned /** + * check if it is allowed to delete the existing object from the database + * + * a displayable error is added in {@link $m_aDeleteIssues} + * * @param \DeletionPlan $oDeletionPlan * * @throws \CoreException @@ -1778,10 +1825,14 @@ abstract class DBObject implements iDisplay } } return $aDelta; - } + } - // List the attributes that have been changed - // Returns an array of attname => currentvalue + /** + * List the attributes that have been changed + * + * @return array attname => currentvalue + * @internal + */ public function ListChanges() { if ($this->m_bIsInDB) @@ -1841,13 +1892,21 @@ abstract class DBObject implements iDisplay return true; } - // used only by insert + /** + * Used only by insert, Meant to be overloaded + * + * @api + */ protected function OnObjectKeyReady() { - // Meant to be overloaded } - // used both by insert/update + /** + * used both by insert/update + * + * @throws \CoreException + * @internal + */ private function DBWriteLinks() { foreach(MetaModel::ListAttributeDefs(get_class($this)) as $sAttCode => $oAttDef) @@ -1856,12 +1915,18 @@ abstract class DBObject implements iDisplay if (!array_key_exists($sAttCode, $this->m_aTouchedAtt)) continue; if (array_key_exists($sAttCode, $this->m_aModifiedAtt) && ($this->m_aModifiedAtt[$sAttCode] == false)) continue; + /** @var \ormLinkSet $oLinkSet */ $oLinkSet = $this->m_aCurrValues[$sAttCode]; $oLinkSet->DBWrite($this); } } - // used both by insert/update + /** + * Used both by insert/update + * + * @throws \CoreException + * @internal + */ private function WriteExternalAttributes() { foreach (MetaModel::ListAttributeDefs(get_class($this)) as $sAttCode => $oAttDef) @@ -1902,8 +1967,18 @@ abstract class DBObject implements iDisplay self::$m_aBulkInsertItems = array(); self::$m_aBulkInsertCols = array(); self::$m_bBulkInsert = false; - } + } + /** + * Persists new object in the DB + * + * @param $sTableClass + * + * @return bool|int false if nothing to persist (no change), new key value otherwise + * @throws \CoreException + * @throws \MySQLException + * @internal + */ private function DBInsertSingleTable($sTableClass) { $sTable = MetaModel::DBGetTable($sTableClass); @@ -1986,7 +2061,7 @@ abstract class DBObject implements iDisplay } /** - * Insert of record for the new object into the database + * Persists object to new records in the DB * * @return int key of the newly created object * @throws \ArchivedObjectException @@ -1996,6 +2071,8 @@ abstract class DBObject implements iDisplay * @throws \CoreWarning * @throws \MySQLException * @throws \OQLException + * + * @internal */ public function DBInsertNoReload() { @@ -2044,6 +2121,7 @@ abstract class DBObject implements iDisplay if (in_array($sState, $oAttDef->GetStates())) { // Start the stop watch and compute the deadlines + /** @var \ormStopWatch $oSW */ $oSW = $this->Get($sAttCode); $oSW->Start($this, $oAttDef); $oSW->ComputeDeadlines($this, $oAttDef); @@ -2199,6 +2277,17 @@ abstract class DBObject implements iDisplay } } + /** + * @return int|null inserted object key + * @throws \ArchivedObjectException + * @throws \CoreCannotSaveObjectException + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \CoreWarning + * @throws \MySQLException + * @throws \OQLException + * @internal + */ public function DBInsert() { $this->DBInsertNoReload(); @@ -3014,32 +3103,56 @@ abstract class DBObject implements iDisplay self::$aPortalToURLMaker[$sPortalId] = $sUrlMakerClass; } - // To be optionaly overloaded + /** + * Can be overloaded + * + * @api + */ protected function OnInsert() { } - - // To be optionaly overloaded + + /** + * Can be overloaded + * + * @api + */ protected function AfterInsert() { } - // To be optionaly overloaded + /** + * Can be overloaded + * + * @api + */ protected function OnUpdate() { } - // To be optionaly overloaded + /** + * Can be overloaded + * + * @api + */ protected function AfterUpdate() { } - // To be optionaly overloaded + /** + * Can be overloaded + * + * @api + */ protected function OnDelete() { } - // To be optionaly overloaded + /** + * Can be overloaded + * + * @api + */ protected function AfterDelete() { } @@ -3121,8 +3234,10 @@ abstract class DBObject implements iDisplay } /** - * This object has been created/deleted, record that as a change in link sets pointing to this (if any) - */ + * This object has been created/deleted, record that as a change in link sets pointing to this (if any) + * + * @internal + */ private function RecordLinkSetListChange($bAdd = true) { foreach(MetaModel::GetTrackForwardExternalKeys(get_class($this)) as $sExtKeyAttCode => $oLinkSet) @@ -3147,6 +3262,9 @@ abstract class DBObject implements iDisplay } } + /** + * @internal + */ protected function RecordObjCreation() { $this->RecordLinkSetListChange(true); @@ -3520,6 +3638,15 @@ abstract class DBObject implements iDisplay return $iFlags; } + /** + * @return bool true if this object is used in a data synchro + * @throws \CoreException + * @throws \CoreUnexpectedValue + * @throws \MySQLException + * @throws \OQLException + * @internal + * @see \SynchroDataSource + */ public function InSyncScope() { //