iTopCN – 编写自己的扩展

Docs: CRUD 事件

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍 iTop 中通过事件实现 CRUD（创建、更新、删除）扩展性的机制，包括各事件的触发时机、可用数据和 API。更多详细内容请参考 iTop 官方文档。

概述

CRUD 扩展性指在对象被创建、更新或删除时实现特定行为。这需要通过多种方式注入 PHP 代码。

对比：Events、iApplicationObjectExtension 与 DBObject 方法
如何用事件替换旧方案

事件监听器

为不同的 CRUD 事件注册监听器，可以在 ORM 操作期间添加功能。

事件	说明	创建/更新	删除
计算值	对象修改时计算字段值（可在 CRUD 外调用）	EVENT_DB_COMPUTE_VALUES	n/a
写入前	操作开始前调用一次	EVENT_DB_BEFORE_WRITE	3.1.2 新增 EVENT_DB_ABOUT_TO_DELETE
写入检查	检查请求的操作对该对象是否有效	EVENT_DB_CHECK_TO_WRITE	EVENT_DB_CHECK_TO_DELETE
写入后	数据库操作已完成（状态 OK）	EVENT_DB_AFTER_WRITE	EVENT_DB_AFTER_DELETE
链接修改	创建/更新/删除 n-n 链接时，通知该链接指向的所有对象	EVENT_DB_LINKS_CHANGED	n/a

注册事件可以通过多种方式完成：如何添加事件并监听以做出响应。

类上的事件

要查找给定类上可用的完整事件列表，请进入 iTop 的数据模型，打开类并转到 “events” 选项卡。

示例

教程：使用事件实现 CheckToWrite

各事件详解

计算值（Compute Values）

对象修改时计算字段值（可在 CRUD 外调用）。

事件：EVENT_DB_COMPUTE_VALUES
修改对象：可以修改当前对象，无需调用 DBWrite() 保存修改，因为对象即将写入数据库
事件数据：
- 'object'：当前对象
事件源：当前对象的所有父类（直到 cmdbAbstractObject）
可用 API：
- 当前更改可通过 DBObject::ListChanges() 获取

写入前（Before Write）

在请求的操作开始前。在此阶段，可以修改当前对象。

事件：
- EVENT_DB_BEFORE_WRITE
- EVENT_DB_ABOUT_TO_DELETE
修改对象：
- 对于创建和更新：可以修改对象值
- 对于删除：对象保证会从数据库中删除。它仍然可用，但只读
事件数据：
- 'is_new'：如果对象正在创建
- 'object'：当前对象
事件源：当前对象的所有父类（直到 cmdbAbstractObject）

写入检查（Check to Write）

检查请求的操作对该对象是否有效。这可以在 CRUD 之外由控制台调用以检查唯一性规则。

事件：
- EVENT_DB_CHECK_TO_WRITE
- EVENT_DB_CHECK_TO_DELETE
修改对象：
- 此时不得修改对象
- 尝试对任何对象字段调用 Set() 将抛出 CoreException
事件数据：
- 'object'：当前对象
- 'is_new'：如果对象正在创建
- 'deletion_plan'：当前 DeletionPlan，用于 EVENT_DB_CHECK_TO_DELETE
事件源：当前对象的所有父类（直到 cmdbAbstractObject）
可用 API：
- 当前更改可通过 DBObject::ListChanges() 获取
- 可以使用 DBObject::AddCheckIssue() 或 DBObject::AddDeleteIssue() 报告问题，这将阻止对象写入或从数据库删除
- 可以使用 DBObject::AddCheckWarning() 报告警告，这不会阻止对象写入或从数据库删除

写入后（After Write）

请求的操作已在数据库中完成。在此阶段，可以将修改传播到其他对象。

事件：
- EVENT_DB_AFTER_WRITE
- EVENT_DB_AFTER_DELETE
修改对象：
- 对于创建和更新：可以再次修改对象值，无需调用 DBWrite() 保存修改，因为如果在此阶段修改了对象，将调用延迟的 DBUpdate()。在这种情况下，将重新运行完整的更新过程（包括所有事件）
事件数据：
- 'changes'：本次更新期间所做的更改数组（用于更新）
- 'is_new'：如果对象正在创建
- 'object'：当前对象
事件源：当前对象的所有父类（直到 cmdbAbstractObject）
可用 API：
- 对于更新，当前更改也可通过 ListPreviousValuesForUpdatedAttributes() 获取

链接修改（Link Modified）

当创建、更新或删除 n-n 链接时，所有链接的对象（以及修改情况下之前链接的对象）都会收到事件通知。

事件：EVENT_DB_LINKS_CHANGED
修改对象：
- 此时可以修改对象，需要调用 DBUpdate() 来持久化修改
事件数据：
- 'object'：链接的对象
事件源：链接对象的所有父类（直到 cmdbAbstractObject）

ApplyStimulus 相关事件

事件

3.1.2 新增

管理允许的转换。仅允许减少当前对象状态中允许的转换。

事件：EVENT_ENUM_TRANSITIONS
事件数据：
- 'object'：刺激目标的对象
- 'allowed_stimuli'：当前状态中可用的刺激列表
事件源：当前对象的所有父类（直到 cmdbAbstractObject），具有生命周期
可用 API：
- 唯一可能的操作是使用 DBObject::DenyTransition() 拒绝转换

原文：https://www.itophub.io/wiki/page?id=3_2_0:extensibility:events_crud

版本：3_2_0/extensibility/events_crud.txt · Last modified: 2025/05/19 16:06 by 127.0.0.1

Docs: CRUD 序列

Fri, 27 Jun 2025 00:00:00 +0000

本文档详细描述 iTop ORM 中 CRUD 操作（创建、更新、删除）的方法调用序列。更多详细内容请参考 iTop 官方文档。

概述

这是 iTop ORM CRUD 栈（创建、更新、删除操作）中方法调用的映射。要了解更多关于扩展性的信息，请参阅扩展性 API。

对象层次结构

iTop 核心中有 3 个类可以扩展用于新的 iTop 对象：

DBObject：数据库中的持久化对象
CMDBObject：添加历史跟踪
cmdbAbstractObject：可编辑对象

所有默认数据模型对象都是 cmdbAbstractObject 的子类。

栈修改历史

2.7.0：事务（参见：N°679, N°2456）
3.1.0：事件（N°4756, N°5906）

图例说明

粗体：可覆盖的回调（在代码中标记为 overwritable-hook PHPDoc 标签）
红色：直接对数据库执行的操作
蓝色：父方法
绿色：事件
紫色：对象访问修改

DBInsert（创建对象）

从 DBObject::DBInsert 开始：

cmdbAbstractObject::DBInsert
DBObject::DBInsertNoReload
DBObject::DoComputeValues
cmdbAbstractObject::FireEventComputeValues - EventService::FireEvent(EVENT_DB_COMPUTE_VALUES)（自 3.1.0 N°4756）
DBObject::ComputeValues
DBObject::OnInsert
cmdbAbstractObject::FireEventBeforeWrite - EventService::FireEvent(EVENT_DB_BEFORE_WRITE, ['is_new' => true])（自 3.1.0 N°6324）
DBObject::CheckToWrite
如果 MetaModel::SkipCheckToWrite 则返回
DBObject::SetReadOnly：从此处起不允许 DBObject::Set（自 3.1.0 N°4756）
cmdbAbstractObject::FireEventCheckToWrite - EventService::FireEvent(EVENT_DB_CHECK_TO_WRITE, ['is_new' => true])（自 3.1.0 N°4756）
DBObject::SetReadWrite：从此处起允许 DBObject::Set（自 3.1.0 N°4756）
cmdbAbstractObject::DoCheckToWrite
如果 CheckToWrite 返回 false，则抛出 CoreCannotSaveObjectException
DBObject::GetState
遍历 MetaModel::ListAttributeDefs，如果 $oAttDef instanceof AttributeStopWatch
- ormStopWatch::Start
- ormStopWatch::ComputeDeadlines
DBObject::Set：设置具有修改值的属性
CMDBSource::Query('START TRANSACTION')（自 2.7.0 N°679）
DBObject::DBInsertSingleTable($sRootClass)
DBObject::DBInsertSingleTable($sClass)：在叶类上调用插入
遍历 MetaModel::EnumParentClasses
- DBObject::DBInsertSingleTable($sParentClass)：在类层次结构上调用插入
cmdbAbstractObject::OnObjectKeyReady
InlineImage::FinalizeInlineImages
DBObject::DBWriteLinks
- 遍历每个修改的 linkset
- ormLinkSet::DBWrite
DBObject::WriteExternalAttributes
- \AttributeCustomFields::WriteExternalValues
CMDBObject::RecordObjCreation
- 删除删除记录
- 删除 2.0.3 之前遗留的任何其他更改跟踪信息
- DBObject::RecordObjCreation
- DBObject::RecordLinkSetListChange
- 创建新的 CMDBChangeOpCreate
CMDBSource::Query('COMMIT')（异常时 ROLLBACK）
重置元信息：m_bIsInDB = true，m_bDirty = false，设置 m_aOrigValues[$sAttCode]
MetaModel::StartReentranceProtection()（自 3.1.0 N°4756）
cmdbAbstractObject::PostInsertActions
- DBObject::PostInsertActions
- cmdbAbstractObject::FireEventAfterWrite
- \cmdbAbstractObject::NotifyAttachedObjectsOnLinkClassModification（自 3.1.0 N°5906）
- \cmdbAbstractObject::FireEventDbLinksChangedForCurrentObject - EVENT_DB_LINKS_CHANGED（自 3.1.0 N°5906）
- EventService::FireEvent(EVENT_DB_AFTER_WRITE, ['changes' => [], 'is_new' => true])（自 3.1.0 N°6324）
- DBObject::AfterInsert
搜索触发器：
- $sClassList = MetaModel::EnumParentClasses
- SELECT TriggerOnObjectCreate AS t WHERE t.target_class IN ('$sClassList')
- 遍历查询结果：Trigger::DoActivate
DBObject::ActivateOnMentionTriggers
遍历 iApplicationObjectExtension（在 cmdbAbstractObject::DBInsert 中）
- iApplicationObjectExtension::OnDBInsert
MetaModel::StopReentranceProtection(REENTRANCE_TYPE_UPDATE)（自 3.1.0 N°4756）
如果对象被修改：DBObject::DBUpdate（自 3.1.0 N°4756）
finally：如果 static::IsCrudStackEmpty()
- \cmdbAbstractObject::FireEventDbLinksChangedForAllObjects - EVENT_DB_LINKS_CHANGED（自 3.1.0 N°5906）
返回 DBObject::$m_iKey

DBUpdate（更新对象）

cmdbAbstractObject::DBUpdate
如果没有更改则返回
DBObject::DBUpdate
MetaModel::StartReentranceProtection（已在更新中则退出）（自 3.1.0 N°4756）
DBObject::DoComputeValues
cmdbAbstractObject::FireEventComputeValues - EventService::FireEvent(EVENT_DB_COMPUTE_VALUES)（自 3.1.0 N°4756）
DBObject::ComputeValues
DBObject::GetState
如果 $sState != ''，遍历 MetaModel::ListAttributeDefs
- 如果 $oAttDef instanceof AttributeStopWatch：ormStopWatch::ComputeDeadlines
DBObject::OnUpdate
cmdbAbstractObject::FireEventBeforeWrite - EventService::FireEvent(EVENT_DB_BEFORE_WRITE, ['is_new' => false])（自 3.1.0 N°6324）
DBObject::InitPreviousValuesForUpdatedAttributes（自 2.7.0 N°2293）
将 $this->ListChanges() 保存到 $aChanges
冻结更改
如果 count($this->ListChanges()) == 0
- MetaModel::StopReentranceProtection(REENTRANCE_TYPE_UPDATE)（自 3.1.0 N°4756）
- 返回 DBObject::$m_iKey
DBObject::CheckToWrite
如果 MetaModel::SkipCheckToWrite 则返回
DBObject::SetReadOnly：从此处起不允许 DBObject::Set（自 3.1.0 N°4756）
cmdbAbstractObject::FireEventCheckToWrite - EventService::FireEvent(EVENT_DB_CHECK_TO_WRITE, ['is_new' => false])（自 3.1.0 N°4756）
DBObject::SetReadWrite：从此处起允许 DBObject::Set（自 3.1.0 N°4756）
cmdbAbstractObject::DoCheckToWrite
如果返回 false，则抛出 CoreCannotSaveObjectException
保存原始值：DBObject::$m_aOrigValues 到 $aOriginalValues 变量
从 $aChanges 中为 \AttributeDefinition::IsBasedOnDBColumns == true 的字段设置 $aDBChanges
CMDBSource::Query('START TRANSACTION')（自 2.7.0 N°679）
如果 !MetaModel::DBIsReadOnly()
- 更新每个层次键的左右索引
- 更新标量属性
- 使用当前类名和 id 创建新的 DBObjectSearch，并 AllowAllData()
- DBObjectSearch::MakeUpdateQuery 使用 $aDBChanges
- \CMDBSource::Query 执行更新查询
DBObject::DBWriteLinks
DBObject::WriteExternalAttributes
- \AttributeCustomFields::WriteExternalValues
属性重置：m_bDirty（设为 false），m_aTouchedAtt，m_aModifiedAtt => 这导致 ListChanges() 返回空数组
DBObject::RecordAttChanges 使用 $aChanges
CMDBSource::Query('COMMIT')（异常时 ROLLBACK）
cmdbAbstractObject::PostUpdateActions
- DBObject::PostUpdateActions
- cmdbAbstractObject::FireEventAfterWrite
- \cmdbAbstractObject::NotifyAttachedObjectsOnLinkClassModification（自 3.1.0 N°5906）
- \cmdbAbstractObject::FireEventDbLinksChangedForCurrentObject - EVENT_DB_LINKS_CHANGED（自 3.1.0 N°5906）
- EventService::FireEvent(EVENT_DB_AFTER_WRITE, ['changes' => $aChanges, 'is_new' => false])（自 3.1.0 N°6324）
- DBObject::AfterUpdate（自 2.7.0 N°2293，更改可使用 DBObject::ListPreviousValuesForUpdatedAttributes 访问）
重置 DBObject::$m_aOrigValues
TriggerOnObjectUpdate：遍历使用当前类或其父类的所有触发器
- TriggerOnObjectUpdate::DoActivate（自 3.0.0 N°3245 和 3.0.2 N°5389，TriggerOnObjectUpdate 移至数据库更新之后）
重入调用（N°1073）：unset(DBObject.aUpdateReentrance[$sKey])
DBObject::ActivateOnMentionTriggers
搜索 iApplicationObjectExtension 实现
- iApplicationObjectExtension::OnDBUpdate（自 2.7.0 N°2293，更改可使用 DBObject::ListPreviousValuesForUpdatedAttributes 访问）
MetaModel::StopReentranceProtection()（自 3.1.0 N°4756）
如果对象被修改且不是无限循环（自 3.1.0）：DBObject::DBUpdate（自 3.1.0 N°4756）
返回 $this->m_iKey
$this->SetWarningsAsSessionMessages('update')
finally：如果 static::IsCrudStackEmpty()
- \cmdbAbstractObject::FireEventDbLinksChangedForAllObjects - EVENT_DB_LINKS_CHANGED（自 3.1.0 N°5906）
返回 $res

DBDelete（删除对象）

cmdbAbstractObject::DBDelete
cmdbAbstractObject::DBDeleteTracked_Internal
搜索 iApplicationObjectExtension 实现
- iApplicationObjectExtension::OnDBDelete
CMDBObject::DBDeleteTracked_Internal
DBObject::DBDelete
DBObject::MakeDeletionPlan
DeletionPlan::AddToDelete：将当前对象添加到待删除列表
EventService::FireEvent(EVENT_DB_CHECK_TO_DELETE, ['deletion_plan' => $oDeletionPlan])（自 3.1.0 N°4756）
cmdbAbstractObject::DoCheckToDelete
DBObject::DoCheckToDelete（@internal，但具有 DeletionPlan 参数）
如果 $this->InSyncScope() 则执行某些操作
iApplicationObjectExtension::OnCheckToDelete（可覆盖的钩子，但无法访问 DeletionPlan 实例）
UserRights::IsActionAllowed
DeletionPlan::SetDeletionIssues
DBObject::GetReferencingObjects
遍历 $aDependentObjects
- DeletionPlan::AddToUpdate：如果 ext key 有 is_null_allowed=true 参数
- DBObject::MakeDeletionPlan：否则
DeletionPlan::ComputeResults
如果 $oDeletionPlan->FoundStopper()：抛出 DeleteException
遍历 $oDeletionPlan->ListDeletes()
- DBObject::DBDeleteSingleObject
DBObject::SetReadOnly：从此处起不允许 DBObject::Set（自 3.1.2 N°7118）
EventService::FireEvent(EVENT_DB_ABOUT_TO_DELETE)（自 3.1.2 N°7118）
DBObject::OnDelete
$aParams = array('class_list' => MetaModel::EnumParentClasses($sClass, ENUM_PARENT_CLASSES_ALL))
SELECT TriggerOnObjectDelete AS t WHERE t.target_class IN (:class_list)
- 遍历查询结果：Trigger::DoActivate
CMDBObject::RecordObjDeletion
- 删除 CMDBChangeOp 对象
- DBObject::RecordObjDeletion
- \DBObject::RecordLinkSetListChange
- 创建并持久化新的 CMDBChangeOpDelete
遍历 MetaModel::ListAttributeDefs(get_class($this))
- 如果 $oAttDef->IsHierarchicalKey()：更新每个层次键的左右索引
- 否则如果 !$oAttDef->LoadFromDB()：AttributeCustomFields::DeleteValue
- TemplateFieldsHandler::DeleteValues
DBObject::DBDelete
CMDBSource::Query('START TRANSACTION')（自 2.7.0 N°679）
遍历 MetaModel::EnumParentClasses(get_class($this), ENUM_PARENT_CLASSES_ALL)
- DBObject::DBDeleteSingleTable
CMDBSource::Query('COMMIT')（异常时 ROLLBACK）
cmdbAbstractObject::FireEventAfterDelete
- \cmdbAbstractObject::NotifyAttachedObjectsOnLinkClassModification（自 3.1.0 N°5906）
- EventService::FireEvent(EVENT_DB_AFTER_DELETE)（自 3.1.0 N°6324）
DBObject::AfterDelete
遍历 $oDeletionPlan->ListUpdates()
- DBObject::Set：重置 ext key
- DBObject::DBUpdate
finally：如果 static::IsCrudStackEmpty()
- \cmdbAbstractObject::FireEventDbLinksChangedForAllObjects - EVENT_DB_LINKS_CHANGED（自 3.1.0 N°5906）

ApplyStimulus（应用刺激）

没有重载，起始点在 DBObject 中。

DBObject::ApplyStimulus
DBObject::EnumTransitions()
EventService::FireEvent(EVENT_ENUM_TRANSITIONS)（自 3.1.2）
如果刺激在当前状态无效果：返回 true
DBObject::Set：设置新状态
遍历 $aTransitionDef['actions']
- 如果 is_string($actionHandler)：call_user_func($aActionCallSpec, $sStimulusCode)（pref 2.1.0 模块：直接调用方法）
- 否则遍历 $aActionHandler['params']
  - 根据参数类型设置 $value
  - $bRet = call_user_func_array($aCallSpec, $aParams)
  - 如果 $bRet === false：IssueLog::Info + $bSuccess = false
如果 $bSuccess
- 秒表：启动或停止
- 如果 !$bDoNotWrite：DBObject::DBWrite
  - 如果 $this->m_bIsInDB：DBObject::DBUpdate
  - 否则：DBObject::DBInsert
搜索当前类及其父类的所有 TriggerOnStateLeave
- Trigger::DoActivate
搜索当前类及其父类的所有 TriggerOnStateEnter
- Trigger::DoActivate
返回 $bSuccess

DoCheckToWrite

cmdbAbstractObject::DoCheckToWrite：警告不为空，覆盖时不要忘记调用父类！
\DBObject::DoCheckToWrite
DBObject::DoComputeValues
设置未初始化的 “null-not-allowed” 日期时间（和日期）
DBObject::ComputeValues
DBObject::DoCheckUniqueness（参见专门章节）
DBObject::ListChanges
遍历 $aChanges
- DBObject::CheckValue
- DBObject::CheckConsistency
如果 DBObject::$m_bIsInDB && DBObject::InSyncScope && (count($aChanges) > 0)
- 为每个因 datasynchro 锁定（OPT_ATT_SLAVE）的属性在 DBObject::$m_aCheckIssues 中添加错误
遍历 iApplicationObjectExtension
- iApplicationObjectExtension::OnCheckToWrite
如果 !$this->bAllowWrite
- UserRights::IsActionAllowedOnAttribute：检查每个更改是否允许（如果不允许，将错误添加到 DBObject::$m_aCheckIssues）

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:sequence_crud

2025/01/13 13:29 by127.0.0.1

版本：3_2_0/customization/sequence_crud.txt · Last modified: 2025/01/13 13:29 by 127.0.0.1

Docs: Events API

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍 iTop 3.1 引入的 Events API，这是一种通过事件机制扩展 iTop 功能的全新方式。更多详细内容请参考 iTop 官方文档。

概述

Events 服务是 iTop 3.1 中的新功能，属于扩展性 API 的一部分。

该服务通过事件提供扩展性。主要行为是事件提供者注册他们要触发的事件，事件监听器注册当事件触发时要调用的回调函数。

示例

事件发布者

注册

提供者必须在 PHP 中触发事件之前，先在 XML 中注册事件。注册需要：

event：大致上是一个唯一的名称
event_data：与事件一起提供的参数
sources：监听器可用的过滤条件，可选且特定于事件

事件 ID

事件 ID 应遵循常量命名规范（即全大写，仅使用下划线字符），并建议事件名称包含 ‘EVENT’。

当然，它在 iTop 和所有扩展中必须是唯一的
在以下示例中，我们将事件命名为 EVENT_DOWNLOAD_DOCUMENT
将自动创建一个与名称相同的字符串常量

const EVENT_DOWNLOAD_DOCUMENT = 'EVENT_DOWNLOAD_DOCUMENT';

事件数据

事件数据由事件提供者在事件触发时提供给所有监听器。它是与事件一起提供的信息，以便监听器可以在有足够信息的情况下采取行动。

数据特定于提供者，由扁平的值列表组成
值可以是任何 PHP 值，如对象或数组，必须在声明中指定
事件数据及其类型在提供者事件注册中声明
它们特定于每个事件

在以下示例中，声明了 5 个 event_datum：

object：DBObject
document：ormDocument
att_code 和 content_disposition：字符串
debug_info：字符串，在 Combodo 创建的事件中始终存在

事件源

事件源是一种根据事件来源过滤事件的方式。

例如，对于数据模型对象上的事件，对象的类是监听器可以使用的源。实际上，所有父类都被添加到事件源中，因此监听器可以在类树的任何级别过滤事件。监听器可以指定监听 “Ticket” 事件。在继承自 Ticket 的对象上触发的所有事件都将发送给此监听器。

XML 结果

 <events>
 <event id="EVENT_DOWNLOAD_DOCUMENT" _delta="define">
 <description>A document has been downloaded from the GUI</description>
 <sources>
 <source id="Document">Document</source>
 </sources>
 <event_data>
 <event_datum id="object">
 <description>The object containing the document</description>
 <type>DBObject</type>
 </event_datum>
 <event_datum id="document">
 <description>The document downloaded</description>
 <type>ormDocument</type>
 </event_datum>
 <event_datum id="att_code">
 <description>Attribute code of the object, containing the document</description>
 <type>string</type>
 </event_datum>
 <event_datum id="content_disposition">
 <description>To differentiate if the document was displayed in preview or truly downloaded</description>
 <type>string</type>
 </event_datum>
 <event_datum id="debug_info">
 <description>Debug string</description>
 <type>string</type>
 </event_datum>
 </event_data>
 </event>
 </events>

所有 iTop 事件

所有 iTop 核心事件声明可以在 <itop>/code/datamodel.application.xml 中找到
当然，这不包括由 iTop 扩展带来的事件

事件触发

此部分用 PHP 编写。由事件提供者在适合触发事件时执行。必须提供：

与注册中声明的 id 和 type 一致的事件数据
适用的事件源

public static function DownloadDocument(WebPage $oPage, $sClass, $id, $sAttCode, $sContentDisposition = 'attachment', $sSecretField = null, $sSecretValue = null)
{
 // ...
 $aEventData = array(
 'debug_info' => $oDocument->GetFileName(),
 'object' => $oObj,
 'document' => $oDocument,
 'att_code' => $sAttCode,
 'content_disposition' => $sContentDisposition,
 );
 $aEventSources = [];
 foreach (MetaModel::EnumParentClasses(get_class($this), ENUM_PARENT_CLASSES_ALL, false) as $sClass) {
 $aEventSources[] = $sClass;
 }

 Combodo\iTop\Service\Events\EventService::FireEvent(
 new Combodo\iTop\Service\Events\EventData(EVENT_DOWNLOAD_DOCUMENT, $aEventSources , $aEventData)
 );
 // ...
}

事件监听器

监听器将指定，如果特定事件在其指定的过滤器匹配的源上触发，则执行特定的 PHP 代码。

event：事件的字符串名称
callback：匹配过滤条件的事件发生时执行的代码
filter：一组字符串。如果事件的 $aEventSources 中有任何一个过滤字符串，则执行回调代码。对于许多触发器，这些字符串对应于类名。此参数可选。
rank：如果您不是唯一响应该事件的扩展，可以指定一个 rank，以确保在另一个您知道其 rank 的扩展之前或之后执行

注册可以通过多种方式完成。

在类中的 XML 方式

您可以在 UserRequest 类中定义一个监听器，为此指定：

event_listener id：给它任何您喜欢的名称，在类中必须唯一
event：在 XML 标签 event 下，如 EVENT_DB_AFTER_WRITE
callback：在 XML 标签 callback 下，提供此类中方法的名称
rank：在 XML 标签 rank 下
filter：在集合 filters/filter 下，但在类中声明时是隐式的

 <class id="UserRequest" _created_in="itop-request-mgmt" _delta="must_exist">
 <event_listeners>
 <event_listener id="OnUserRequestUpdateDone" _delta="define">
 <event>EVENT_DB_AFTER_WRITE</event>
 <callback>OnUserRequestUpdateDone</callback>
 <rank>0</rank>
 </event_listener>
 </event_listeners>

类似于重写 UserRequest::OnUpdate，但没有被另一个定制覆盖的风险，因为事件的所有监听器按顺序调用执行各自的工作
类似于实现 iObjectApplicationExtension OnDBUpdate()，但对于许多事件，等效的接口方法不存在，而且使用接口无法控制执行顺序

在 XML 中使用直接代码

此处 XML 声明在任何类之外，在 itop_design XML 树的根级别。

注意：

需要 XML filter 标签来声明适用的类
如果 event 对 filter 中的类不适用，不会失败，不会显示警告，只是回调永远不会被调用
方法没有名称
您无法访问 $this，当前 $oObject 由事件提供（$oEventData->Get('object')）

 <event_listeners>
 <event_listener id="OnAttachmentDownloadActivateTriggers" _delta="define">
 <event>EVENT_DOWNLOAD_DOCUMENT</event>
 <filters>
 <filter>Attachment</filter>
 </filters>
 <rank>0</rank>
 <code><![CDATA[
 function(Combodo\iTop\Service\Events\EventData $oEventData)
 {
 if ($oEventData->Get('content_disposition') !== ormDocument::ENUM_CONTENT_DISPOSITION_ATTACHMENT) {
 return;
 }
 $oObject = $oEventData->Get('object');
 $sAttCode = $oEventData->Get('att_code');
 $oDocument = $oEventData->Get('document');
 ...
 }
]]></code>
 </event_listener>
 </event_listeners>

回调

如果您在 XML 中的类里注册了监听器，则在类上创建回调作为 PHP 方法。

public function OnUserRequestUpdateDone(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $sEvent = $oEventData->GetEvent();
 $aChange = $oEventData->Get('changes');
 // 执行您的处理
}

在回调代码中：

您可以通过 $oEventData->Get('xx') 获取事件发布者注册的事件数据（其中 ‘xx’ 是 XML 标签中 ’event_datum’ 的 ‘id’）
在某些事件中，对象上可以使用标准方法，如 DBObject::AddCheckIssue()、DBObject::ListChanges() 等
当事件和回调方法在类本身上声明时，可以使用 $this 代替 $oEventData->Get('object')

示例：人员变更时

在标准 iTop 中，我们通过此事件机制防止门户用户在人员组织变更时失去访问权限。

PHP 中的监听器

如果您在 PHP 中进行注册和回调，最简单的方式是声明一个实现 iEventServiceSetup 的新类。在一个地方执行 RegisterEventsAndListeners() 中的注册，并指定回调代码。

监听器可以指定它们要监听的源。

class AttributeBlobEventListener implements iEventServiceSetup
{
 public function RegisterEventsAndListeners()
 {
 EventService::RegisterListener(
 EVENT_DOWNLOAD_DOCUMENT,
 [$this, 'OnAttributeBlobDownloadActivateTrigger']
 );
 }

 public function OnAttributeBlobDownloadActivateTrigger(Combodo\iTop\Service\Events\EventData $oEventData): void
 {
 // 回调代码
 ...
 }
}

class EventListener implements iEventServiceSetup
{
 public function RegisterEventsAndListeners()
 {
 EventService::RegisterListener(
 EVENT_DOWNLOAD_DOCUMENT,
 [$this, 'OnAttachmentDownloadActivateTriggers'],
 'Attachment'
 );
 }

 public function OnAttachmentDownloadActivateTriggers(Combodo\iTop\Service\Events\EventData $oEventData): void
 {
 if ($oEventData->Get('content_disposition') !== ormDocument::ENUM_CONTENT_DISPOSITION_ATTACHMENT) {
 return;
 }
 $oObject = $oEventData->Get('object');
 $sAttCode = $oEventData->Get('att_code');
 $oDocument = $oEventData->Get('document');
 ...
 }
}

现有事件

要获取更多关于 CRUD 事件的详细信息：

它们的名称和用法
它们的数据
回调代码中可调用的 DBObject 方法

查找与数据模型类关联的事件

在数据模型页面中，可以查看为特定类注册的所有事件和监听器。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:events_api

版本：3_2_0/customization/events_api.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: Interfaces API

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍 iTop 的扩展性接口，这是定制 iTop 行为的一种方式。更多详细内容请参考 iTop 官方文档。

概述

扩展性接口是定制 iTop 行为的一种方式。要了解其他方式，请查看扩展性 API。

接口参考文档

有多个接口可用于扩展 iTop。每个接口对应一种特定类型的扩展。以下是一些示例：

接口	说明
`iApplicationUIExtension`	实现此接口以更改某些对象的 GUI 行为（显示详情或编辑对象时）
`iApplicationObjectExtension`	在 CRUD 期间对对象执行特定操作的旧接口，已被事件处理取代
`iPageUIBlockExtension`	实现此接口以向任何 iTopWebPage 添加内容
`iPortalUIExtension`	实现此接口以向任何门户页面添加内容
`iPopupMenuExtension`	在控制台和门户中的 iTop 对象和列表上添加菜单项
`iRestServiceProvider`	向 REST API 添加动词

这些接口和抽象类定义在 application/applicationextension.inc.php 文件中。

参考文档：扩展的 API 参考

iPopupMenuExtension 示例

假设我们有一个基于 Web 的应用程序，提供关于服务器可用性的高级报告。我们希望提供一个超链接，以便最终用户可以快速从 iTop 中的服务器详情跳转到监控应用程序中的相应报告。

一种可能的解决方案是在所有服务器的 “Actions” 弹出菜单中显示指向监控应用程序的超链接。

实现方式是实现 iPopupMenuExtension 接口：

class MyPopupExtension implements iPopupMenuExtension
{
 public static function EnumItems($iMenuId, $param)
 {
 if ($iMenuId == self::MENU_OBJDETAILS_ACTIONS)
 {
 $oObject = $param;
 if ($oObject instanceof Server)
 {
 $sUID = 'MyPopupExtension-Monitoring';
 // 确保每个菜单项都有唯一的 "ID"
 $sLabel = 'Monthly report';
 $sURL = 'http://myapp/show_report?server_fqdn='.$oObject->Get('name');
 $sTarget = '_blank';
 $oMenuItem = new URLPopupMenuItem($sUID, $sLabel, $sURL, $sTarget);
 return array($oMenuItem);
 }
 }
 return array();
 }
}

EnumItems 方法将在多种情况下被 iTop 调用。显示对象详情时，$params 是目标对象。

由于我们的方法将对任何类型的对象调用，因此必须过滤掉不相关的对象类。

如您所见，同一个扩展可以处理多种类型的对象和多种类型的菜单（取决于 $iMenuId 和 $param）。

此插件的结果是在任何服务器的详情页面上添加一个额外的菜单条目。

其他示例

以下教程使用 iTop 接口 API：

iPopupMenuExtension：在"其他操作"弹出菜单中添加条目
iPopupMenuExtension：在列表上添加操作
iBackofficeStyleExtension：从活动面板中隐藏历史记录

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:extensions_api:interfaces

版本：3_2_0/customization/extensions_api/interfaces.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: iTop 编码标准

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍 Combodo 的 iTop 编码规范（主要针对 PHP）。这些规范与 PSR-12 标准有很多共通之处，但也存在一些显著差异，请注意区分。更多详细内容请参考 iTop 官方文档。

文件编码

源代码文件使用 UTF-8 编码（文件开头不含 BOM）。
换行符必须为 LF。
PHP 文件必须使用长标签 <?php 开头，但不能包含 PHP 结束标签。这可以防止在文件末尾意外添加空白字符。

空白与缩进

缩进方式：

PHP 文件：使用制表符（配置编辑器将制表符显示为 4 个字符宽度）
SCSS：2 个空格
Twig：4 个空格

if/else、try/catch、while、switch、匿名类的开括号必须位于行尾，闭括号必须位于主体后的下一行。类和函数的开括号保持在下一行。

示例：

class NiceWebPage extends WebPage
{
 ...

 public function SetContentType($sContentType)
 {
 if ($sContentType == '') {
 // Do something
 } else {
 // Do something different
 }
 }
}

函数调用时，参数紧跟在函数名后的括号内：函数名与参数列表之间没有空格。每个参数列表中的逗号后跟一个空格。

示例：

$sValue = Utils::ReadParam('param1', 'default_value');

二元运算符（==、+、&&）两侧有空格。

例外：连接运算符 . 两侧没有空格，因为这样可以保持代码更紧凑，且在使用等宽字体时不会降低可读性。

示例：

if (isset($aPerson[$this->iPersonId][0]) && ($aPerson[$this->iPersonId][0] != "")) {
 if ($this->sSynchronizeOrganization == 'yes') {
 $sName = $aPerson[$this->iPersonId]['first_name'].' '.$aPerson[$this->iPersonId]['last_name'];
 }
}

字符串分隔符

可以使用任何您喜欢的分隔符，主要目标是保持代码可读性。

使用 heredoc/nowdoc 时，建议使用允许 JetBrains 语言注入的分隔符。

示例：

$sHtml = '<a href="http://www.combodo.com">';

$sFooBarBaz = "{$foo}-{$bar} {$baz}";

$sJs = <<<JS
console.debug("this is some JS code");
console.debug("having the right delimiter keyword will help language injection !");
JS;

变量命名

变量、函数参数和对象属性使用驼峰命名法（即每个单词首字母大写，其余小写），并使用前缀字母作为类型提示：

前缀	类型
`a`	哈希或数组
`i`	整数
`o`	PHP 对象
`s`	字符串
`f`	浮点数
`r` 或 `h`	资源句柄

示例：

$iCount = 1;
$sText = 'This is a text';
$oPage = new WebPage('test');
$fRank = 1.25;
$hDir = opendir('/opt');

没有前缀的变量被认为是混合类型（可以是字符串、数组或对象）。

允许的例外

循环计数器使用的局部变量（如 $i、$j）可以没有前缀。
在涉及大量数值变量的数学计算中，可以省略数值变量的前缀（如 $x、$y、$xMax）。
由于历史原因，WebPage 类（及相关类）以及 MetaModel 内部某些部分使用不同的约定：变量全部小写，用下划线分隔单词。对象属性使用 m_ 前缀。

数组键命名

数组键使用蛇形命名法（snake_case）。

示例：

$aMyArray = [
 'value_raw' => $sMyValue,
 'input_id' => $iInputId,
];

请使用适当的 PHPDoc 语法记录键（见下文）。

配置参数命名

使用小写，单词之间用下划线分隔。

当多个配置参数与同一主题相关时，可以使用以点号结尾的前缀进行分组。

例如：email_transport_smtp.host

函数命名（PHP、JS）

函数和对象方法使用驼峰命名法。即使 PHP 对函数名不区分大小写，这也有助于区分项目中的函数和 PHP 内置函数（通常为小写）。函数名通常基于表示正在执行的动作的动词。

示例：

function DisplayWelcomePopup(WebPage $oP)
{
 // Code goes here
}

类型提示

自 iTop 3.0.0 起（最低 PHP 7.1.3），可以使用 PHP 类型提示（在方法签名中添加类型），但：

仅在新代码中使用 PHP 类型提示，不要修改现有方法。
注意遵循最低 PHP 版本的能力（例如，联合类型仅在 PHP 8.0.0 起可用）。
在流式方法上，不要添加返回类型，否则会导致继承问题。

比较（== vs ===）

自 2022/12/22 起，严格比较（===）成为所有新开发的标准规则。

例外：

如果不确定比较数据的类型，则优先使用严格比较（===）并添加显式转换。
如果这不可能，软比较（==）可以被容忍，但前提是必须同时包含抑制 PHPStorm 警告的注释和解释为什么软比较是唯一方式的注释。

应避免的模式

使用 empty() 检查字符串是否为空

检查字符串是否为空时，不要使用 empty()，而应使用 strlen() > 0（或更好的 \utils::IsNullOrEmptyString()，如果您的代码面向 iTop 3.0.2+），因为在某些情况下变量可能包含 "0"，而 empty("0") 会将其评估为 true。

$sFoo = '';

// 不要这样做
if (empty($sFoo)) {
 // Some stuff
}

// 应该这样做
// - iTop 2.7+
if (strlen($sFoo) === 0) {
 // Some stuff
}
// - iTop 3.0.2+
if (\utils::IsNullOrEmptyString($sFoo)) {
 // Some stuff
}

PhpDoc

编写 PhpDoc 的规则在仓库本身中有描述：参见 /.doc/README.md。

@since

我们还使用 @since 标签来指示类/属性/方法的引入或修改。这在所有类、API 上都是强制性的。

示例：

/**
 * ...
 *
 * @since 2.5.2 2.6.0 new 'transaction_id' filter
 * @since 2.7.0 new 'element_identifier' filter
 * @since 3.0.0 new utils::ENUM_SANITIZATION_* const
 * @since 2.7.7, 3.0.2, 3.1.0 N°4899 - new 'url' filter
 */
protected static function Sanitize_Internal($value, $sSanitizationFilter)

Bool VS boolean

请在 PHPDoc 中使用 bool，因为：

bool 和 boolean 在 PHPDoc 中都有效。
只有 bool 在 PHP 中有效，boolean 会导致问题。

数组：psalm/phpstan 语法

示例：

/**
 * ...
 * @return array<string, \CheckResult> full path as key, CheckResult error as value
 */

带命名键的数组：array Shapes

示例：

 /**
 * @param array{
 * languageCode: string,
 * entries: array{
 * code: string,
 * value: string
 * }
 * } $aDictData
 */
 public static $aDictData;

字典条目

这是一个独立的主题，请参阅专门的 wiki 页面：如何翻译。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:coding_standards

版本：3_2_0/customization/coding_standards.txt · Last modified: 2026/01/28 10:40 by 127.0.0.1

Docs: iTop 定制机制

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍 iTop 的定制机制，包括数据模型扩展、模块与扩展的概念、开发工作流以及工具包的使用。更多详细内容请参考 iTop 官方文档。

概述

iTop 构建在 ORM（对象关系映射）抽象层之上，该层依赖于"元数据模型"的定义，由 PHP 类组成。从 iTop 2.0 开始，元数据模型可以用 XML 描述，然后在应用程序安装过程中"编译"成 PHP 类。

iTop 架构中可定制的部分（橙色框）包括：

定制类型	方式	文档	目标受众
扩展或修改数据模型并调整控制台行为	XML 文件	XML 参考	iTop 顾问、ITIL 专家
通过插件扩展通用用户界面	PHP 文件	扩展性 API	PHP 开发人员
通过插件扩展数据模型行为	XML 和 PHP 文件	Events API	PHP 开发人员
创建新的用户界面页面以实现新的 Web 服务、专用导出或特定任务导向的用户界面	PHP 文件	ORM API	PHP 开发人员
创建自己的安全方案	PHP 文件	用户权限 API	PHP 开发人员
更改客户门户或开发新门户	XML 文件	定制客户门户	iTop 顾问、ITIL 专家、Web 设计师、PHP 开发人员

iTop 文件结构

iTop 文件和文件夹的布局如下：

特殊文件夹

文件夹	说明
`conf`	包含配置文件，每个环境一个子文件夹
`data`	包含应用程序生成的数据，如对象生命周期图像（如果系统上可用 graphviz）
`datamodels`	包含元数据模型定义，每个 iTop 主要版本一个子文件夹
`env-xxxx`	这些文件夹（每个环境一个）包含"编译后的"数据模型。`env-production` 文件夹在每次重新安装或升级时完全重新创建
`extensions`	放置不属于 iTop 标准分发的扩展模块
`log`	包含应用程序的日志文件：`setup.log` 和 `error.log`

所有其他文件夹应被视为应用程序源代码的一部分，通常不应修改。应用程序永远不会写入这些文件夹，它们可以标记为对 Web 服务器进程只读。

环境

iTop 2.0 引入的新概念是"环境"。环境是运行相同代码库但可能具有自己的数据模型和配置文件的 iTop 实例。一个环境由以下部分组成：

存储在 conf/name_of_the_environment/config-itop.php 的配置文件
存储在 env-name_of_the_environment 的数据模型运行时

工具包会自动创建一个单独的环境（名为 toolkit），以便在不影响"生产"环境的情况下编译 XML 数据模型并测试其一致性。当更改确认无误后，可以指示工具包将验证后的更改应用到"生产"环境。

扩展与模块

模块

iTop 中数据模型定义的基本单元称为模块。iTop 的安装过程将每个模块视为一个整体。

模块将交付给定功能所需的所有文件组合在一起：XML 中的数据模型定义、PHP 类、Javascript 和 CSS 文件、PHP 页面、图像等。一个模块至少包含一个文件：模块定义文件，始终命名为 module.name_of_the_module.php。

虽然您始终可以修补源代码，但定制 iTop 的最佳方式是编写自己的模块。这样可以创建整洁的定制包，并便于部署或升级时重新安装。

扩展

扩展的概念随 iTop 2.4 引入。扩展是一个或多个模块的集合。安装期间向最终用户提出的安装选项基于在 iTop 的"extensions"文件夹中找到的扩展；为了向后兼容，如果在扩展之外找到模块，则该模块将直接列为安装选项。

扩展通过每个扩展根文件夹中的 extension.xml 文件来标识。

当扩展由单个模块组成时，预期的结构是一个单独的文件夹，所有文件（extension.xml、module.xxxx.php、datamodel.xxxx.xml 等）在同一级别。

当扩展由多个模块组成时，预期的结构是一个根文件夹，只包含 extension.xml 文件，每个模块一个子文件夹（包含 module.xxxx.php、datamodel.xxxx.xml 等）。

如果多个扩展包含相同的模块（通过其代码标识），安装过程将只安装一个模块副本：版本最高的那个。

PHP 与 XML 数据模型定义

在 iTop 1.x 版本中，数据模型定义被编写为普通 PHP 类。iTop 2.0 支持 PHP 和 XML 两种数据模型定义。

XML 定义相比 PHP 定义有一个主要优势：一个模块中的 XML 定义可以修改另一个模块中定义的数据模型。例如，可以创建一个扩展模块，在安装时向标准类"Server"添加一个属性，而无需替换整个 “itop-config-management” 模块。

模块内容

如果 my-module 是您的模块名称，模块文件夹将包含以下文件：

文件名	说明
`extension.xml`	iTop 2.4 新增：XML 定义文件，用于 iTop 2.4 及以上版本。如果模块位于已包含 `extension.xml` 文件的文件夹中，则此文件的内容被忽略
`module.my-module.php`	模块定义文件。必需。包含模块的描述（名称、版本、对其他模块的依赖等）及其组件
`datamodel.my-module.xml`	XML 数据模型。安装时"编译"将基于 XML 定义生成 `model.xxxxx.php` 文件。XML 文件可以包含类、菜单和角色的定义
`model.my-module.php`	如果选择直接用 PHP 定义数据模型，则在此文件中放置此类定义
`main.my-module.php`	PHP 代码和工具。对于包含大量 PHP 代码的模块，将代码提取到此单独文件中比将代码嵌入 XML 更容易
`images`	将图像（类图标等）存储在各自的子文件夹中是一个好习惯
`en.dict.my-module.php`	字典文件，如果需要一些本地化字符串

处理本地化

所有字符串都应包含在字典文件中。请参阅专门的 wiki 页面：如何翻译。

创建自己的扩展

填写以下表单并点击"生成"以生成一个空扩展，作为定制的起点。

字段	说明
公司名称	必需，仅使用字母字符，无空格。用于 Composer 和 PHP 命名空间
扩展名称	仅使用小写字母字符和短横线（-），必须唯一。以 “itop-” 和 “combodo-” 开头的名称保留给 Combodo 使用
扩展标签	安装期间显示
版本	格式：x.y.z
依赖项	模块名称/版本的逗号分隔列表

查找依赖项

当您的模块修改另一个模块定义的类时，该模块必须在安装和工具包 XML 编译中先存在并处理，以执行 PHP 代码生成。

XML 数据模型树是逐步构建的，一个接一个地添加模块，因此带有 _delta="redefine" 指令的 XML 标签如果该标签尚未存在于树中，则会失败。

首先在 <my-itop>/datamodels/2.x/ 下的模块中搜索您要修改或嫁接的标签。您的模块将依赖于这些找到的模块。
然后检索您依赖的模块的名称和版本，在 module.xxxx.php 文件中查找。对于属于 iTop Community 的模块，模块版本遵循 iTop 主要版本。

安装工具包

下载工具包 zip 文件：https://github.com/Combodo/itop-toolkit-community/releases
解压 zip 文件内容，在开发 iTop 实例的根目录下创建 “toolkit” 目录
在浏览器中访问 http://<your_itop>/toolkit

开发工作流

创建一个空模块
安装 iTop 开发实例，将您的空模块放在 “extensions” 文件夹中
在开发实例上安装工具包
编辑您的扩展模块，并使用工具包验证它
将扩展模块的更改应用到"生产"环境
使用一些示例数据测试您的模块。如有问题，回到第 4 步迭代修复

当扩展完成后，可以通过以下方式部署到生产系统：

将包含扩展模块的文件夹复制到生产系统的 “extensions” 文件夹
将配置文件标记为读/写
再次运行安装程序，在交互式安装末尾的"扩展"列表中选择您的模块

使用工具包

工具包安装后，在浏览器中访问：http://<your_itop>/toolkit。

第一个选项卡执行一些基本的一致性检查并验证数据模型定义。每次数据模型定义更改后，可以使用"刷新"按钮重新执行验证。此选项卡中的检查在特定的"toolkit"环境上工作，因此不会影响使用"生产"环境的实际 iTop 实例。

如果收到如下错误：

XML datamodel loader: could not find node for class/XXXX

这很可能意味着您的模块缺少对定义类 XXXX 的模块的依赖。

当第一个选项卡没有显示任何错误时，可以转到第二个选项卡：

检查数据库架构的更改
点击"更新 iTop 代码"将数据库架构和数据模型定义的更改应用到"生产"iTop 环境

工具包的第三个选项卡可用于更新数据同步源（如果有任何受数据模型更改影响的），并检查为层次键维护的内部数据是否存在差异。此选项卡直接在"生产"环境上操作。

生命周期图像

iTop 的"数据模型"页面（“生命周期"选项卡）中显示对象生命周期的图形表示。如果修改了对象的生命周期，则需要在 Web 服务器上安装 Graphviz 才能重新计算这些图像。有关安装 Graphviz 的更多信息，请参阅安装 iTop。

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:datamodel

Last modified: 2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/datamodel.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: Wiki / 插入 XML 语法

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍教程中使用的简化 XML 语法，以及如何将其扩展为符合 iTop XML 树结构的完整格式。更多详细内容请参考 iTop 官方文档。

概述

本文档解释如何扩展教程中提供的 XML 代码片段，使其符合 iTop XML 树结构。

添加 XML 代码

简化语法

为了提高教程的可读性并突出需要更改的 XML 节点，周围的 XML 结构以简化的路径语法提供。

每个层级用 / 分隔
itop_design 是唯一可能的顶层标签，有时在 wiki 语法中可能省略，但在 XML 文件中不要省略
末尾带 s 的标签通常是集合
在集合下，通常可以找到不带 s 的相同标签，并用 id 来区分节点
brick@toto 表示 <brick id="toto">

以下是最短的可能语法示例，其中只需修改一个节点：

 <default _delta="redefine">tree</default>

我们不会在 XML 标签中逐个打开和关闭每个层级，而是只提供一个表示树结构的字符串，并将其放在代码块的标题中。

通常为了可读性会压缩得更少：

 <brick id="services">
 <browse_modes>
 <default _delta="redefine">tree</default>
 </browse_modes>
 </brick>

完整 XML 结构

以下是将上述代码块扩展为 iTop 所需的完整 XML 结构的方式：

<?xml version="1.0" encoding="UTF-8"?>
<itop_design version="1.6">
 <module_designs>
 <module_design id="itop-portal">
 <bricks>
 <brick id="services">
 <browse_modes>
 <!-- 在此处插入代码块内容 -->
 </browse_modes>
 </brick>
 </bricks>
 </module_design>
 </module_designs>
</itop_design>

此外，这两行必须放在 XML 文件顶部：

<?xml version="1.0" encoding="UTF-8"?>
<itop_design version="1.6">

version="1.6" 对应扩展所需的最低 iTop XML 版本。XML 版本自 iTop 2.0 起可用，至少到 iTop 2.6，可以从 iTop 版本猜测，将第一个数字减 1。

例如：所有 iTop 2.6.x 版本使用 XML 版本 1.6
如果您使用 iTop 2.5 中添加的 XML 标签，则 XML 版本不要低于 1.5

测试

将简化的 XML 扩展为完整结构后，将其复制到扩展的 datamodel.my-extension.xml 文件中（my-extension 是您的真实扩展名称），然后运行安装程序或工具包查看结果。

添加 PHP 代码

插入方法只能在 2 个位置进行：类中或模块中。

对于类，我们只在代码块标题中提供需要声明方法的类：class:UserRequest
对于模块，没有特定的语法

在现有类上的方法

这部分解释如何在类上定义/覆盖 PHP 方法。

多个教程会告诉您在类上编写 PHP 方法以实现 iTop 中的新行为
它们甚至可能提供确切的 PHP 代码片段
但它们不会解释如何将 PHP 代码插入 iTop XML 结构
这种技术独立于方法本身，正是我们要解释的
为了不那么抽象，我们使用一个真实的示例

简化语法

在代码块标题中，您会找到需要声明方法的类。例如：class:UserRequest

public function IncrementCounter($sAttCode, $iIncrement=1)
{
 // 防御性编程，确保字段代码在当前类上有效
 if (MetaModel::IsValidAttCode(get_class($this), $sAttCode))
 {
 $iNew = $this->Get($sAttCode) + $iIncrement;
 $this->Set($sAttCode, $iNew);
 }
 return true;
}

PHP 代码必须先扩展，然后才能粘贴到 datamodel.my-extension.xml 文件中。

完整 XML 代码

以下是其扩展方式：

<?xml version="1.0" encoding="UTF-8"?>
<itop_design version="1.3">
 <classes>
 <!-- 类名在简化语法框的标题中 -->
 <class id="UserRequest" _delta="must_exist">
 <methods>
 <!-- 任何 'id' 都可以，但如果与函数名相同则更容易记住 -->
 <method id="IncrementCounter" _delta="define">
 <static>false</static>
 <access>public</access>
 <!-- comment 是可选的 -->
 <comment><![CDATA[
/**
 * $sAttCode 应该是 UserRequest 类中 Integer 或 Decimal 类型的有效字段代码
 * $iIncrement 必须是整数
 */
 ]]></comment>
 <code><![CDATA[
public function IncrementCounter($sAttCode, $iIncrement=1)
{
 // 防御性编程，确保字段代码在当前类上有效
 if (MetaModel::IsValidAttCode(get_class($this), $sAttCode))
 {
 $iNew = $this->Get($sAttCode) + $iIncrement;
 $this->Set($sAttCode, $iNew);
 }
 return true;
}
 ]]></code>
 </method>
 </methods>
 </class>
 </classes>
</itop_design>

解码方式的详细信息：

源	应翻译为…
`public function IncrementCounter()`	`<access>public</access>`
`protected function ...`	`<access>protected</access>`
`public function ...`	`<static>false</static>`
`public static function ...`	`<static>true</static>`
`public function IncrementCounter(`	`<method id="IncrementCounter">`

风险

当您定义某个 DBObject 可覆盖方法之一时，请注意它可能已经在标准 iTop 数据模型中完成。如果是这种情况，在安装/工具包编译时，由于您使用 _delta="define" 添加方法，如果它已经存在则会失败。在这种情况下，您可以执行 “redefine”，但随后需要镜像现有代码，否则将破坏 iTop 的当前行为。

ITSM Designer 特定要求

如果满足以下条件，则需要 arguments 标签：

您的扩展将加载到 ITSM Designer 中
且方法必须由转换上的操作调用

 <method id="IncrementCounter" _delta="define">
 < ... >
 <arguments>
 <argument id="1">
 <mandatory>true</mandatory>
 <type>attcode</type>
 </argument>
 <argument id="2">
 <mandatory>false</mandatory>
 <type>int</type>
 </argument>
 </arguments>
 </method>

在新 PHP 类中

最简单的方式是将此代码放入扩展的 main.my-extension.php 文件中。

但也可以放在 XML 结构中：

 <snippet id="ScheduledStart" _delta="define">
 <placement>module</placement>
 <module>itop-request-mgmt</module>
 <rank>200</rank>
 <content><![CDATA[
 /* 在此处输入包含类定义和方法的代码 */
 ]]></content>
 </snippet>

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:insert-xml

版本：3_2_0/customization/insert-xml.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: XML 数据模型参考

Fri, 27 Jun 2025 00:00:00 +0000

本文档是 iTop 模块中 datamodel.xxxx.xml 文件所使用的 XML 格式的参考文档。更多详细内容请参考 iTop 官方文档。

概述

XML 数据模型文件可用于定义：

类 - 使用安装程序或工具包"编译"时将生成实际 PHP 类
菜单 - 插入 iTop 页面左侧的应用程序菜单中
角色 - 管理对 iTop 对象的访问权限
品牌标识

要定制用户门户，请参阅门户 XML 参考。

基本原则

XML 数据模型包含初始声明和/或对在其他 XML 文件中做出的声明的更改。

iTop 编译器分两步工作：

加载已安装模块的 XML 数据模型文件。XML 被合并为一个单一的 XML 定义。重要的是要理解，从一个空定义开始，iTop 将逐个合并每个 XML
解释最终的合并定义

默认情况下，给定 XML 的内容被合并到合并定义中。

更改节点内容

您可以使用 _delta 属性定义更改。此属性指定给定节点（包括其子节点）应如何处理。

_delta 可以取以下值：

`_delta`	含义
`merge`（默认）	如果此节点尚不存在，则创建它。然后检查其子节点中的 delta。这主要与结构节点相关
`must_exist`	确保此节点已存在。然后检查其子节点中的 delta
`if_exists`	2.3.0 新增 - 检查此节点是否已存在。如果是，检查其子节点中的 delta。否则忽略此节点。类似于 `must_exist`，但跳过当前节点而不是停止整个过程
`define`	这是此节点的首次定义。其子节点中不应包含任何标志
`define_if_not_exists`	如果节点尚不存在则定义它。否则忽略它
`redefine`	此节点的内容必须被 delta 节点的内容替换
`delete`	删除此节点。如果节点不存在则停止处理。不要在此节点下提供任何子节点
`delete_if_exists`	删除此节点。不要在此节点下提供任何子节点
`force`	2.4.0 新增 - 强制定义此节点，无论它是否存在

节点通过其标签名和 id 属性来标识。如果没有给出 id，则节点被标识为找到的第一个具有相同标签名的节点。

当编译器遇到 define/redefine 时，它认为子树是纯内容定义。因此，该子树中找到的任何 _delta 或 _rename_from 属性都将被忽略。

当单个节点下可以有多个相同标签的节点时，我们称之为集合。

重命名节点

另一个属性是 _rename_from。使用它来指定项目（例如类字段）实际上是从 _rename_from 重命名为 id 的现有项目。

XML 通用结构

标签	用法	说明
`<itop_design xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" version="3.0">`	必需	结构节点。此标签前不允许有注释。与先前版本相比的变化，请参阅 Version_30 的详细信息
`<classes>`	必需	声明的类
`<class id="name">`	零个或多个	类声明
`<parent>cmdbAbstractObject</parent>`	必需	父类。参见类属性继承
`<properties>`	必需	属性
`<is_link>1</is_link>`	可选	区分用于链接其他类的类。对于链接类设置为 1
`<comment>`	必需	添加到编译文件中的 PHP 注释，位于类声明之前
`<category>bizmodel,searchable</category>`	可选	此类的用途。参见类类别
`<abstract>false</abstract>`	必需	抽象类不能被实例化
`<key_type>autoincrement</key_type>`	必需	始终设置为 “autoincrement”
`<db_table>name</db_table>`	必需	此类使用的 MySQL 表名。此处给出的名称将自动添加安装时提供的后缀
`<db_key_field>id</db_key_field>`	必需	将标识符字段始终设置为 “id” 即可
`<db_final_class_field>`	必需	如果类位于类层次结构的顶部，则必须定义哪个 MySQL 列将用于跟踪对象实例的实际类。将其设置为 “finalclass” 即可
`<naming>`	可选	定义用于组成对象友好名称的属性。默认情况下，友好名称将渲染为给定属性的连接，以空格分隔。您可以通过添加字典条目 `Class:<myClass>/Name` 指定任何其他格式。此格式以类 printf 格式表达式给出（仅支持 `$s`。例如 `'%1$s of %2$s'`）。由于此格式位于字典中，它可能被翻译，友好名称将取决于最终用户的语言
`<attributes>`	必需	用于组成友好名称的属性列表。注意顺序很重要
`<attribute id="name">`	至少一个	属性
`<complementary_attributes>`	可选	定义用于补充对象友好名称以区分重复项的属性列表。默认情况下，补充为空。您可以通过添加字典条目 `Class:<myClass>/ComplementaryName` 指定格式
`<fields_semantic>`	可选	定义承载类某些方面的属性（例如图像、状态等）
`<image_attribute>`	可选	承载应代表对象的图像的属性代码（必须声明为 AttributeImage）。如果未定义，则在必要时使用类图标
`<state_attribute>`	可选	承载对象状态的属性代码，如果有生命周期则必需，属性必须是当前类的枚举。如果此处未定义但在父类中定义，则继承
`<order>`	可选	定义类的默认排序顺序，如果省略则按友好名称排序
`<columns>`	必需	列
`<column id=“name” ascending=“true	false”>`	至少一个
`<style>`	可选	指定类的样式（颜色和图标）。自 iTop 3.0 起支持
`<icon>../../images/user-request.png</icon>`	可选	为类指定图标（相对于模块根目录的路径）
`<main_color>#4E79A5</main_color>`	可选	类的主色，可以是任何有效的 CSS 颜色（hexa、rgba、hsla，但不能是变量）或 SCSS 变量
`<complementary_color>#FFFFFF</complementary_color>`	可选	类的互补色，可以是任何有效的 CSS 颜色或 SCSS 变量
`<reconciliation>`	必需	定义数据导入的默认协调方案
`<indexes>`	可选	定义表索引
`<index id="name">`	零个或多个	显式强制创建数据库索引，包含所有指定属性，按声明的顺序
`<archive>`	可选	归档配置
`<enabled>true</enabled>`	必需	仅适用于根类。设置为 true 以使此类及其后代可归档（添加两个魔法属性：archive_flag 和 archive_date）
`<obsolescence>`	可选	过时配置。一旦为类定义了过时，就会添加两个魔法属性（obsolescence_flag 和 obsolescence_date），层次结构中的所有类都有该标志（默认为 “No”）
`<condition><![CDATA[status='closed']]></condition>`	必需	定义对象是否过时的 OQL 表达式。此条件将由子类继承，除非被重新定义
`<uniqueness_rules>`	可选	保存对象时用于检查其唯一性的规则
`<fields>`	必需	属性声明（与从父类继承的属性累积）
`<lifecycle>`	可选	生命周期：状态和转换。在 3.0 中，“lifecycle/attribute” 标签被替换为 “fields_semantic/attribute_state”
`<highlight_scale>`	可选	定义对象显示（列表中的背景颜色和图标）的高亮代码列表
`<presentation>`	必需	展示
`<details>`	必需	定义对象的可视化和编辑表单的展示。可以被生命周期标志 “hidden” 覆盖
`<search>`	必需	搜索屏幕的 “Add new criteria” 菜单的 “Most popular” 部分中显示的属性有序列表
`<default_search>`	可选	搜索屏幕中显示的默认搜索条件有序列表。如果留空或不存在，则继承自父类
`<list>`	必需	默认在结果列表中显示的属性有序列表
`<summary>`	可选	在外部键弹出概述中显示的属性有序列表。自 iTop 3.1 起
`<custom_presentations>`	可选	扩展带来的自定义属性列表。自 iTop 3.1 起
`<menus>`	必需	主 GUI 中显示的菜单声明（左窗格）
`<user_rights>`	必需	用户权限策略的实现：用户将拥有一个或多个角色，授予他们访问权限
`<groups>`	必需	组是类的集合。授权基于此分组 - 参见 “profiles”
`<profiles>`	必需	将在应用程序中列出的角色。用户可拥有一个或多个角色。“administrator” 角色始终存在且不可重新定义
`<files>`	可选	用于在 XML 中嵌入二进制文件（如图标）。自 iTop 2.0.1 起支持
`<dictionaries>`	可选	用于在 XML 中添加本地化。自 iTop 2.0.1 起支持
`<branding>`	可选	GUI 的外观。Logo 定义为 PNG 文件（相对于模块根目录的路径 = env-production），或 fileref 标签
`<main_logo>`	可选	主 GUI 的 Logo（菜单展开时左上角）。尺寸：最大宽度 310px，最大高度 70px
`<main_logo_compact>`	可选	控制台菜单折叠时左上角的 Logo。尺寸：宽度 37px，高度 37px
`<login_logo>`	可选	登录页面的 Logo。尺寸：最大宽度 300px，最大高度 54px
`<portal_logo>`	可选	客户门户的 Logo。尺寸：最大宽度 192px，最大高度 50px
`<main_favicon>`	可选	主 GUI 和默认其他 GUI 使用的 Favicon（浏览器标签中的图标）。自 iTop 3.2.0 起
`<portal_favicon>`	可选	最终用户门户使用的 Favicon。自 iTop 3.2.0 起
`<login_favicon>`	可选	登录页面使用的 Favicon。自 iTop 3.2.0 起
`<themes>`	必需	主题主节点，用于自定义 iTop 外观。自 iTop 2.7.0 起
`<themes_common>`	必需	3.1 新增全局主题规则，与 themes 节点中声明的每个主题一起编译。可以包含与 theme 节点相同的内容
`<constants>`	可选	要编译为 PHP defines 的常量
`<portals>`	可选	用户界面入口点的定义。自 iTop 2.2.0 起支持
`<module_parameters>`	可选	模块特定参数的定义。自 iTop 2.2.0 起支持
`<module_designs>`	可选	模块特定设计数据。自 iTop 2.3.0 起支持
`<snippets>`	可选	要注入 PHP 模型文件中的 PHP 代码片段。自 iTop 2.2.0 起支持
`<meta>`	可选	存储有关 XML 定义的元信息的根节点，编译器忽略
`<events>`	可选	3.1 新增事件定义列表
`<event_listeners>`	可选	3.1 新增全局事件监听器

字段类型

字段（也称为属性）是对象的实际数据成员。一个字段通常对应数据库中一个（或多个）表列。不同类型的字段如下：

类型	说明
`AttributeBlob`	二进制大对象（最大 4GB）
`AttributeCaseLog`	案例日志，讨论线程。每条消息标有说话者姓名和当前时间
`AttributeCustomFields`	自定义模块处理的自定义字段。自 iTop 2.3.0 起支持
`AttributeDashboard`	仅用于显示信息的仪表板字段。自 iTop 2.6.0 起支持
`AttributeDate`	日期（无时间）
`AttributeDateTime`	日期和时间
`AttributeDecimal`	十进制值
`AttributeDuration`	持续时间，以秒存储，以天/小时/分钟/秒显示
`AttributeEmailAddress`	电子邮件地址
`AttributeEncryptedPassword`	加密存储的密码字符串（最大 65535 字符），在 UI 中不可读。自 3.2.1 起
`AttributeEncryptedString`	加密存储的字符串（最大 255 字符），在 UI 中可读
`AttributeEnum`	固定值集合中的字符串
`AttributeEnumSet`	固定值集合中的字符串集合
`AttributeExternalField`	另一个对象持有的属性的别名（参见 “ExternalKey”）
`AttributeExternalKey`	指向给定类对象的外部键
`AttributeHierarchicalKey`	指向同一类的外部键，用于构建对象层次结构
`AttributeHTML`	HTML 文本（最大 4GB）
`AttributeImage`	图像（最大 4GB）
`AttributeInteger`	正整数值
`AttributeIPAddress`	IP 地址
`AttributeLinkedSet`	指向当前对象的对象集合
`AttributeLinkedSetIndirect`	通过"链接类"与当前对象相关的对象集合
`AttributeMetaEnum`	在其他枚举字段之后计算的字符串，可在子类中定义。自 iTop 2.3.0 起支持
`AttributeObjectKey`	灵活的外部键：指向任何类对象的指针。自 iTop 2.2.0 起实验性支持
`AttributePercentage`	百分比（0 到 100 之间的整数），以条形显示
`AttributePhoneNumber`	电话号码
`AttributeRedundancySettings`	关系冗余设置。自 iTop 2.2.0 起支持
`AttributeStopWatch`	累计在某些状态中花费的时间
`AttributeString`	字符串（限制为 255 字符的一行）
`AttributeSubitem`	秒表中存在的某个状态信息。两者必须在同一类中定义！
`AttributeTagSet`	要与对象关联的标签列表。存储在 255 长度字符串上
`AttributeText`	多行文本（最大 64KB）
`AttributeLongText`	大文本（最大 4GB）
`AttributeURL`	URL（http…）

生命周期

刺激（Stimuli）

每个从一个状态到另一个状态的转换（对于有生命周期的对象）在对象收到刺激时触发。不同类型的刺激如下：

类型	说明
`StimulusUserAction`	最终用户决定的操作。刺激显示在 Actions 菜单中（如果对象处于考虑此刺激的状态）
`StimulusInternal`	可以以编程方式触发的操作

转换上的操作

有关可在 XML 中作为操作调用的现有方法，请参阅转换可用方法。

菜单类型

不同类型的菜单如下：

类型	说明
`MenuGroup`	顶级菜单。此菜单将始终保持可见。它是其他菜单的容器
`DashboardMenuNode`	仪表板。内容可以通过 “export” 功能生成。内容可以在文件（definition_file）中或直接在此处（definition）
`NewObjectMenuNode`	创建新对象的快捷方式
`SearchMenuNode`	搜索对象的快捷方式
`TemplateMenuNode`	用于二级菜单组
`OQLMenuNode`	显示搜索结果的快捷方式，给定 OQL 查询

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:xml_reference

2026/01/23 14:22 by127.0.0.1

版本：3_2_0/customization/xml_reference.txt · Last modified: 2026/01/23 14:22 by 127.0.0.1

Docs: 对象操作 API

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍 iTop 中用于搜索和操作持久化对象的 API 类。更多详细内容请参考 iTop 官方文档。

概述

iTop 提供了一组核心类用于在数据库中搜索和操作对象。这些类构成了 ORM（对象关系映射）层的基础。

核心类

DBObjectSearch

DBObjectSearch 类用于在数据库中搜索对象。它允许您构建 OQL（对象查询语言）查询来检索满足特定条件的对象。

DBObjectSet

DBObjectSet 类表示一组持久化对象。它是执行查询后的结果集，提供了遍历和操作这些对象的方法。

DBUnionSearch

DBUnionSearch 类用于执行多个 DBObjectSearch 的并集操作。当您需要合并来自不同查询的结果时，可以使用此类。

参考

iTop 官方文档 - 对象操作 API

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:api:objects-manipulation:start

Last modified: 2024/09/10 10:25 by127.0.0.1

版本：3_2_0/customization/api/objects-manipulation/start.txt · Last modified: 2024/09/10 10:25 by 127.0.0.1

Docs: 方法与事件

Fri, 27 Jun 2025 00:00:00 +0000

本文档对比 DBObject 方法、iApplicationObjectExtension 接口和 Events API（iTop 3.1+）三种扩展方式，帮助您了解如何从旧机制迁移到基于事件的扩展机制。更多详细内容请参考 iTop 官方文档。

概述

iTop 提供了多种方式来扩展对象的行为。从 iTop 3.1 开始，推荐使用**事件（Events）**机制替代传统的 DBObject 方法重载和 iApplicationObjectExtension 接口。

方法 vs 事件对比

DBObject 方法	iApplicationObjectExtension	事件（iTop 3.1+）
ComputeValues	n/a	EVENT_DB_COMPUTE_VALUES
DoCheckToWrite	OnCheckToWrite	EVENT_DB_CHECK_TO_WRITE
DoCheckToDelete	OnCheckToDelete	EVENT_DB_CHECK_TO_DELETE
GetAttributeFlags	n/a	EVENT_DB_SET_ATTRIBUTES_FLAGS
GetInitialStateAttributeFlags	n/a	EVENT_DB_SET_INITIAL_ATTRIBUTES_FLAGS
n/a	n/a	EVENT_DB_LINKS_CHANGED
n/a	n/a	EVENT_ADD_ATTACHMENT_TO_OBJECT
n/a	n/a	EVENT_REMOVE_ATTACHMENT_FROM_OBJECT
EnumTransitions	n/a	EVENT_ENUM_TRANSITION
OnInsert	n/a	EVENT_DB_BEFORE_WRITE
AfterInsert	OnDBInsert	EVENT_DB_AFTER_WRITE
OnUpdate	n/a	EVENT_DB_BEFORE_WRITE
AfterUpdate	OnDBUpdate	EVENT_DB_AFTER_WRITE
OnDelete	OnDBDelete	EVENT_DB_ABOUT_TO_DELETE
AfterDelete	n/a	EVENT_DB_AFTER_DELETE

不可替换的方法

以下方法无法通过事件替换：

DBObject 方法	iApplicationObjectExtension	事件
PrefillSearchForm	n/a	n/a
PrefillCreationForm	n/a	n/a
PrefillTransitionForm	n/a	n/a
DisplayBareRelations	n/a	n/a

从 DBObject 方法重载迁移到监听器

在类中注册事件监听器，以在回调方法中执行代码：

 <classes>
 <class id="UserRequest">
 <event_listeners>
 <event_listener id="HideTransitionsIfApprovalRule" _delta="define">
 <event>EVENT_ENUM_TRANSITIONS</event>
 <rank>10</rank>
 <callback>HideTransitionsIfApprovalRule</callback>
 </event_listener>
 </event_listeners>
 <methods>
 <method id="HideTransitionsIfApprovalRule" _delta="define">
 <comment>/**
 * If an approval rule could apply to the current object, hide all transitions
 * As the service and service subcategory are not yet set, we can't determine if the approval rule will really apply
 * So we hide all transitions if the object is new and in a state where an approval rule could apply
 */</comment>
 <static>false</static>
 <access>public </access>
 <code><![CDATA[public function HideTransitionsIfApprovalRule(Combodo\iTop\Service\Events\EventData $oEventData)
{
 // PHP code here...
}]]></code>
 </method>
 </methods>

回调方法接收一个事件参数，您可以在签名中允许它为 null，以便重用该方法。

从 iApplicationObjectExtension 迁移到监听器

纯 PHP 方式

首先考虑纯 PHP 方式处理事件。复制粘贴以下模板并根据需要调整：

/**
 * 模板：帮助从 iApplicationObjectExtension 钩子迁移到基于事件的监听器。
 * 作为起点使用：
 * - 必须指定要监听的类列表（或省略参数以监听所有类）
 * - 必须将旧钩子的代码复制/粘贴到适当的方法中
 * - 必须删除不必要的监听器
 * - 建议的事件与旧钩子最接近，但可能不是最合适的
 * - 整个内容可以在 XML 中定义，而不是 PHP，允许在集成时进行更精细的控制（优先级等）
 */
class MyCustomHooks implements iEventServiceSetup
{
 public function RegisterEventsAndListeners() : void
 {
 // TODO: 删除不必要的监听器
 EventService::RegisterListener(EVENT_DB_CHECK_TO_WRITE, [$this, 'OnDBCheckToWrite'], ['Class1', 'Class2']);
 EventService::RegisterListener(EVENT_DB_CHECK_TO_DELETE, [$this, 'OnDBCheckToDelete'], ['Class1', 'Class2']);
 EventService::RegisterListener(EVENT_DB_AFTER_WRITE, [$this, 'OnDBAfterWrite'], ['Class1', 'Class2']);
 EventService::RegisterListener(EVENT_DB_ABOUT_TO_DELETE, [$this, 'OnDBAboutToDelete'], ['Class1', 'Class2']);
 }

 public function OnDBCheckToWrite(Combodo\iTop\Service\Events\EventData $oEventData)
 {
 $oObject = $oEventData->Get('object');
 // TODO: 将之前在 OnCheckToWrite 中实现的代码放在这里，使用 AddCheckIssue 报告问题，而不是将它们作为数组返回
 }
 public function OnDBCheckToDelete(Combodo\iTop\Service\Events\EventData $oEventData)
 {
 $oObject = $oEventData->Get('object');
 // TODO: 将之前在 OnCheckToDelete 中实现的代码放在这里，使用 AddDeleteIssue 报告问题
 }
 public function OnDBAfterWrite(Combodo\iTop\Service\Events\EventData $oEventData)
 {
 $oObject = $oEventData->Get('object');
 if ($oEventData->Get('is_new')) {
 // TODO: 将之前在 OnDBInsert 中实现的代码放在这里
 }
 else {
 // TODO: 将之前在 OnDBUpdate 中实现的代码放在这里
 }
 }
 public function OnDBAboutToDelete(Combodo\iTop\Service\Events\EventData $oEventData)
 {
 $oObject = $oEventData->Get('object');
 // TODO: 将之前在 OnDBDelete 中实现的代码放在这里
 }
}

XML 方式

在类内部或外部注册事件监听器以执行代码：

示例（来自 combodo-autodispatch-ticket，监听器适用于任何类）：

 <event_listeners>
 <event_listener id="HideTransitionsIfAutoDispatchRule" _delta="define">
 <event>EVENT_DB_AFTER_WRITE</event>
 <filters/>
 <rank>0</rank>
 <code><![CDATA[function(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $oObject = $oEventData->Get('object');
 if ($oEventData->Get('is_new')) {
 // TODO: 将之前在 OnDBInsert 中实现的代码放在这里
 }
 else {
 // TODO: 将之前在 OnDBUpdate 中实现的代码放在这里
 }
}
 ]]></code>
 </event_listener>
 </event_listeners>

事件详解

EVENT_DB_COMPUTE_VALUES

注册此事件以在对象修改时计算字段值（基于同一对象其他字段的值）。

public function EvtComputeValues(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $this->Set('vat', 0.2*$this->Get('cost'));
}

您可以通过 $oEventData->Get('stimulus_applied') 判断是否处于特定转换中（null 表示不在转换中）。

在旧版本 iTop 和某些类中，您可能会遇到 ComputeValues() 方法，该方法已弃用，但执行相同的工作。

EVENT_DB_SET_INITIAL_ATTRIBUTES_FLAGS

有两个不同的事件：一个在显示对象的创建表单之前，另一个在显示对象的修改表单时。

public function EvtSetInitialAttributeFlags(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $this->AddInitialAttributeFlags($sAttCode, $iFlags); // 为字段添加标志
 $this->ForceInitialAttributeFlags($sAttCode, $iFlags); // 强制字段标志
}
/* 标志常量值，使用位运算符 | 组合：
 * OPT_ATT_NORMAL
 * OPT_ATT_HIDDEN
 * OPT_ATT_READONLY
 * OPT_ATT_MANDATORY
 * OPT_ATT_MUSTCHANGE
 * OPT_ATT_MUSTPROMPT
 */

EVENT_DB_SET_ATTRIBUTES_FLAGS

public function EvtSetAttributeFlags(Combodo\iTop\Service\Events\EventData $oEventData)
{
 $this->AddAttributeFlags($sAttCode, $iFlags); // 为字段添加标志
 $this->ForceAttributeFlags($sAttCode, $iFlags); // 强制字段标志
}

GetAttributeFlags 和 GetInitialStateAttributeFlags 方法已弃用，不应再使用。

EVENT_DB_CHECK_TO_WRITE

此事件在对象写入数据库之前触发。

允许在特定条件不满足时阻止记录当前对象
也可以简单地警告用户非阻塞性问题
在回调方法中添加 AddCheckIssue 消息将停止对象的创建/修改/转换，并显示错误消息

// 阻塞性问题
$this->AddCheckIssue('Some error message');
// 非阻塞性警告
$this->AddCheckWarning('Some warning message');

您可以通过 $oEventData->Get('stimulus_applied') 判断是否处于特定转换中（空字符串表示不在转换中）

此时修改对象本身已为时过晚。

EVENT_DB_BEFORE_WRITE

如果您想自动修改当前对象，通常正确的答案是 EVENT_DB_COMPUTE_VALUES。

如果此更改仅在对象创建时发生，请使用 EVENT_DB_BEFORE_WRITE 并通过 $oEventData->Get('is_new')==$this->IsNew() 测试是否处于创建状态
如果此更新资源密集且仅在某些字段被设置/修改时才应执行，则在 EVENT_DB_BEFORE_WRITE 中检查正在进行的更改：$this->ListChanges()

EVENT_DB_AFTER_WRITE

如果您想在某个对象被修改时自动修改其他对象，请使用 EVENT_DB_AFTER_WRITE。

在当前对象保存到数据库后触发一次
使用 $oEventData->Get('is_new')===true 测试对象是否刚刚创建
使用 $oEventData->Get('stimulus_applied') 测试是否处于特定转换中
检查已执行的更改：

$aChanges = $oEventData->Get('changes');
$aChanges = $this->ListPreviousValuesForUpdatedAttributes();

EVENT_DISPLAY_OBJECT_DETAILS

此事件在对象显示在用户门户之前触发。

它不是设计用来作用于显示内容的，但允许您统计 FAQ 在用户门户中显示的次数，并可能将此计数存储在 FAQ 对象本身中。

EVENT_DB_LINKS_CHANGED

此事件在对象上触发，在其 LinkedSet（标记为"PHP 计算"）被修改之后。

如果宿主对象本身被修改，不会触发
如果 PHP 代码更新对象的 LinkedSet，不会触发
如果 LinkedSetIndirect 的远程对象被修改（例如 Team.persons_list 中 Person 的状态变更），不会触发
如果 LinkedSet 中的子对象被单独添加、移除或修改，则会触发

在此回调执行期间，您不知道：

什么发生了变化，甚至不知道哪个 LinkedSet
当前对象是否刚刚创建或修改

适用场景：确保一旦链接被创建、修改或删除，您的代码就会执行。可用于存储关系计数或总和、重新排序、查找具有特定值的关系并将其作为 ExternalKey 存储在对象中。

EVENT_ENUM_TRANSITIONS

此事件在对象显示之前触发。

允许在某些条件下移除对象的转换
例如，阻止非当前代理的用户将工单重新分配给其他团队
如果移除不可用的转换，则无效果

$this->DenyTransition($sStimulusCode)

EVENT_ADD_ATTACHMENT_TO_OBJECT

此事件在附件添加到对象之后触发。

允许在案例日志中添加条目或测试附件的约束条件，并在某些条件下自动删除（例如有风险的文件类型）

$oEventData->Get('attachment')

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:event

Last modified: 2025/10/31 12:23 by127.0.0.1

版本：3_2_0/customization/event.txt · Last modified: 2025/10/31 12:23 by 127.0.0.1

Docs: 新扩展文件结构

Fri, 27 Jun 2025 00:00:00 +0000

本文档介绍创建 iTop 扩展的推荐文件结构和编码规范。这些规范不是强制性的，但强烈建议遵循，以便他人理解扩展的工作原理。更多详细内容请参考 iTop 官方文档。

概述

这些是新扩展的推荐指南，绝对不是强制性的，但强烈建议遵循，因为这将帮助其他人理解扩展的工作原理。

文件夹结构

此结构由 Combodo 研发团队于 2019 年 5 月集体设计。

<extension-root>
asset
js
css
img
lib
bin
dictionaries // iTop 3.0+
doc
[legacy]
src
Controller
Helper
Service
<SomeService>
Hook
Model
tests
php-unit-tests
integration-tests
unitary-tests
phpunit.xml
ci_description.ini
templates
vendor
[compatibilitybridge.php]
composer.json
index.php
Jenkinsfile
module.<module>.php
datamodel.<extension>.xml
[extension.xml]
[license.<module>.xml]

文件与文件夹说明

文件夹/文件	必需	说明
`asset`	否	扩展的公共资源（图像、样式表、JS 脚本、库等）
`bin`	否	在 CLI 中运行的脚本/可执行文件
`dictionaries`	否	模块的字典文件（例如 `en.dict.<extension>.php`）。自 iTop 3.0.0 起可用，之前版本文件必须放在根文件夹中
`doc`	否	文档文件。可以是 README.md 的图像、markdown 文件等
`legacy`	否	仅当扩展需要兼容引入破坏性更改的 iTop 版本时
`src`	否	PHP 文件。子文件夹应使用驼峰命名法并遵循文件的命名空间，以便自动加载器正常工作
`src/Controller`	否	使用 MVC 模式时的控制器类
`src/Hook`	否	实现/扩展 iTop API 的 PHP 类
`src/Model`	否	实体 PHP 类（来自数据模型或非数据模型）
`tests`	否	所有类型测试的结构文件夹
`tests/php-unit-tests`	否	所有 PHPUnit 测试的结构文件夹
`tests/php-unit-tests/integration-tests`	否	集成测试文件
`tests/php-unit-tests/unitary-tests`	否	单元测试文件，应与 `/src` 文件夹的结构匹配
`tests/php-unit-tests/phpunit.xml`	否	要运行的测试套件
`tests/ci_description.ini`	否	描述 CI 运行时要使用的参数（默认参数的重载）的文件
`templates`	否	扩展使用的模板（HTML、JS 等）
`vendor`	否	不要在此放置任何内容，它将自动由 composer 构建（第三方库和自动加载器）
`compatibilitybridge.php`	否	仅当扩展需要兼容引入破坏性更改的 iTop 版本时。将在 `module.<extension>.php` 中加载，并负责根据 iTop 版本加载正确的文件
`composer.json`	否	放置扩展类命名空间和/或类映射；放置要包含的第三方库
`index.php`	否	MVC 使用的端点
`Jenkinsfile`	否	在 CI 中启用扩展的文件
`module.<extension>.php`	是	扩展定义文件，包含其代码、版本、依赖项、安装程序等
`datamodel.<extension>.xml`	否	扩展的数据模型 XML 更改（参见下面关于相应 model.php 文件的说明）
`extension.xml`	否	扩展的元数据（作者、兼容性、描述、URL 等。由 Designer、Hub 和 Setup 使用。将在构建期间由 Factory 生成）
`exclude.txt`	否	包含要从扩展构建中排除的文件/文件夹列表。通常是 `doc/` 文件夹和 “README.md” 文件
`README.md`	否	对于非官方扩展，描述其功能、使用方法和与 iTop 的兼容性。当扩展成为官方扩展时将被移除，其文档将移至 wiki
`license.<module>.xml`	否	许可证文件

注意：

添加一个空的 model.<module>.php！
在 module.<module>.php 的 ‘datamodel’ 键中引用此文件

编码规范

PHP

一个 PHP 文件应只包含一个类
PHP 文件应使用 PSR-4 约定命名，即对于 “MyCMDBObject” 类，文件应为 “MyCMDBObject.php” 而不是 “mycmdbobject.class.inc.php”

自动加载器

不必通过在 module.<extension>.php 文件的 ‘datamodels’ 部分包含它们来在每个 iTop 页面中加载 PHP 文件，我们可以使用自动加载器仅在需要时加载它们。

此自动加载器将作为 iTop 基础自动加载器的补充。

编辑 composer.json 文件以放置命名空间（和/或类映射）后，生成自动加载器并将其添加到 ‘datamodels’ 部分：

cd <PATH_OF_THE_EXTENSION>
composer.phar dump-autoload -a

...
 'datamodels' => array(
 // Module's autoloader
 'vendor/autoload.php',
 // Explicitly load APIs classes if any
 'src/Hook/MyConsoleUIExtension.php',
 ),
...

安全性

如果您希望文件可以在没有任何认证的情况下调用（在大多数情况下不推荐），您需要将文件添加到 model.<module>.php 文件的 delegated_authentication_endpoints 中。

...
 'delegated_authentication_endpoints' => [
 'index.php',
 'open_access.php'
 ],
...

原文：https://www.itophub.io/wiki/page?id=3_2_0:customization:new_extension

2026/04/13 17:01 by127.0.0.1

版本：3_2_0/customization/new_extension.txt · Last modified: 2026/04/13 17:01 by 127.0.0.1