README

Object包提供了构建用户界面网站所需的抽象对象、行为和工具。

安装

composer require charcoal/object

概述

该包提供了一系列基本类、辅助工具以及对象行为（接口+特质）。

基本类

所有木炭项目对象类应该扩展以下两个基类之一，\Charcoal\Object\Content，用于由管理员创建和管理的数据，或\Charcoal\Object\UserData，用于从客户端/用户创建的数据。

内容

内容 基类应用于所有可“管理”的对象。通常由管理员通过 charcoal/admin 包进行管理。它为对象添加了“活动”标志以及创建和修改信息。

API

• setActive($active)
• active()
• setPosition($position)
• position()
• setCreated($created)
• created()
• setCreatedBy($createdBy)
• createdBy()
• setLastModified($lastModified)
• lastModified()
• setLastModifiedBy($lastModifiedBy)
• lastModifiedBy()

Content 类扩展了来自 charcoal/core 模块的 \Charcoal\Model\AbstractModel，这意味着它还继承了其 API 以及 DescribableInterface（metadata()、setMetadata() 和 loadMetadata() 等）和 StorableInterface（id()、key()、save()、update()、delete()、load()、loadFrom()、loadFromQuery()、source() 和 setSource() 等）。

AbstractModel 类扩展了 \Charcoal\Config\AbstractEntity，它还定义了基本数据访问方法（setData()、data()、keys()、has()、get()、set() 以及 ArrayAccess、JsonSerializable 和 Serializable 接口）。

属性（元数据）

[1] 在 save() 时自动生成
[2] 在 update() 时自动生成

默认元数据定义在 metadata/charcoal/object/content.json

用户数据

用户数据 类应用于所有预期从项目的“客户端”或“最终用户”输入的对象。

API

• setIp($ip)
• ip()
• setTs($ts)
• ts()
• setLang($lang)
• lang()

Content 类扩展了来自 charcoal/core 模块的 \Charcoal\Model\AbstractModel，这意味着它还继承了其 API 以及 DescribableInterface（metadata()、setMetadata() 和 loadMetadata() 等）和 StorableInterface（id()、key()、save()、update()、delete()、load()、loadFrom()、loadFromQuery()、source() 和 setSource() 等）。

AbstractModel 类扩展了 \Charcoal\Config\AbstractEntity，它还定义了基本数据访问方法（setData()、data()、keys()、has()、get()、set() 以及 ArrayAccess、JsonSerializable 和 Serializable 接口）。

属性（元数据）

[1] 在 save() 和 update() 时自动生成

默认元数据定义在 metadata/charcoal/object/user-data.json

对象行为

• 存档
• 可分类
• 分类
• 分层
• 可发布
• 可修订
• 可路由

存档

存档行为尚未文档化。它仍在积极开发中。

可分类

API

• setCategory($category)
• category()
• setCategoryType($type)
• categoryType()

属性（元数据）

[1] 实现的元数据中必须显式设置 obj_type 分类

默认元数据定义在 metadata/charcoal/object/catgorizable-interface.json

分类

API

• setCategoryItemType($type)
• categoryItemType()
• numCategoryItems()
• hasCategoryItems()
• categoryItems()

属性（元数据）

默认元数据定义在 metadata/charcoal/object/catgory-interface.json

分层

API

• hasMaster()
• isTopLevel()
• isLastLevel()
• hierarchyLevel()
• master()
• toplevelMaster()
• hierarchy()
• invertedHierarchy()
• isMasterOf($child)
• recursiveIsMasterOf($child)
• hasChildren()
• numChildren()
• recursiveNumChildren()
• children()
• isChildOf($master)
• recursiveIsChildOf($master)
• hasSiblings()
• numSiblings()
• siblings()
• isSiblingOf($sibling)

属性（元数据）

默认元数据定义在 metadata/charcoal/object/hierarchical-interface.json。

可发布

• setPublishDate($publishDate)
• publishDate()
• setExpiryDate($expiryDate)
• expiryDate()
• setPublishStatus($status)
• publishStatus()
• isPublished()

属性（元数据）

默认元数据定义在 metadata/charcoal/object/publishable-interface.json。

可修订

可修订对象实现 \Charcoal\Object\Revision\RevisionableInterface，可以通过使用 \Charcoal\Object\Revision\RevisionableTrait 简单实现。

可修订对象创建 修订，记录对象版本之间的更改，作为 差异。

API

• setRevisionEnabled(bool$enabled)
• revisionEnabled()
• revisionObject()
• generateRevision()
• latestRevision()
• revisionNum(integer $revNum)
• allRevisions(callable $callback = null)
• revertToRevision(integer $revNum)

属性（元数据）

可修订行为不实现任何属性，因为所有逻辑和数据都包含在修订中。

可路由

路由行为尚未文档化。它仍在积极开发中。

辅助工具

ObjectDraft

…

ObjectRevision

每次在 存储 中进行 update 操作时，可修订对象都会创建一个新的 修订（一个 \Charcoal\Object\ObjectRevision 实例），记录对象版本之间的更改（差异）。

修订属性

修订方法

• createFromObject(RevisionableInterface $obj)
• createDiff(array $dataPrev, array $dataObj)
• lastObjectRevision(RevisionableInterface $obj)
• objectRevisionNum(RevisionableInterface $obj, integer $revNum)

ObjetSchedule

可以从（通常是 charcoal 管理后端），创建 计划（一个 \Charcaol\Object\ObjectSchedule 实例），将一系列更改自动应用到对象上。

计划属性

计划方法（API）

• process([callable $callback, callable $successCallback,callable $failureCallback])

计划操作应通过及时的计划任务运行。charcoal/admin 模块包含一个自动运行计划的脚本。

./vendor/bin/charcoal admin/object/process-schedules`

资源

• 贡献
• 报告问题 和 发送拉取请求 在 主 Charcoal 仓库