charcoal / object
Object (Content and UserData) definition and object behaviors and tools.
Requires
- php: ^7.4 || ^8.0
- charcoal/config: ^5.0
- charcoal/core: ^5.0
- charcoal/factory: ^5.0
- charcoal/translator: ^5.0
- psr/log: ^1.0
Requires (Dev)
- ext-json: *
- php-coveralls/php-coveralls: ^2.2
- phpunit/phpunit: ^9.5
- pimple/pimple: ^3.0
- seld/jsonlint: ^1.9
- squizlabs/php_codesniffer: ^3.5
- tedivm/stash: ~0.16
Replaces
- dev-main / 5.x-dev
- v5.0.0
- v4.1.0
- v4.0.8
- v4.0.7
- v4.0.6
- v4.0.5
- v4.0.4
- v4.0.2
- v4.0.1
- v4.0.0
- v3.1.8
- v3.1.7
- v3.1.6
- v3.1.5
- v3.1.4
- v3.1.3
- v3.1.2
- v3.1.1
- v3.1.0
- v2.2.3
- v2.2.2
- v2.2.1
- v2.2.0
- v2.1.2
- 0.8.0.1
- 0.8.0
- 0.7.4.1
- 0.7.4
- 0.7.3.1
- 0.7.3
- 0.7.2
- 0.7.1.5
- 0.7.1.4
- 0.7.1.3
- 0.7.1.2
- 0.7.1.1
- 0.7.1
- 0.7.0
- 0.6.2.1
- 0.6.2
- 0.6.1
- 0.6.0
- 0.5.1
- 0.5.0
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4
- 0.3.0.1
- 0.3
- 0.2.6
- 0.2.5
- 0.2.4
- 0.2.3
- 0.2.2
- 0.2.1.1
- 0.2.1
- 0.2
- 0.1.3.1
- 0.1.3
- 0.1.2
- 0.1.1
- 0.1
- dev-feature/camelizePropertiesAndUseArrayAccess
- dev-mducharme-camelcase
- dev-mcaskill-feature-softdeletable
This package is auto-updated.
Last update: 2024-04-13 15:28:46 UTC
README
The Object package provides abstract objects, behaviours, and tools for building user-facing Web sites.
Installation
composer require charcoal/object
Overview
The package provides a bunch of basic classes, helpers as well as object behaviors (interfaces + traits).
Basic classes
All charcoal project object classes should extend one of the 2 base classes, \Charcoal\Object\Content, for data created and managed by administrators or \Charcoal\Object\UserData, for data created from clients / users.
Content
The Content base class should be used for all objects which can be "managed". Typically by an administrator, via the charcoal/admin package. It adds the "active" flag to objects as well as creation and modification informations.
API
setActive($active)active()setPosition($position)position()setCreated($created)created()setCreatedBy($createdBy)createdBy()setLastModified($lastModified)lastModified()setLastModifiedBy($lastModifiedBy)lastModifiedBy()
The
Contentclass extends\Charcoal\Model\AbstractModelfrom the charcoal/core module, which means that it also inherits its API as well as theDescribableInterface(metadata(),setMetadata()andloadMetadata(), amongst others) and theStorableInterface(id(),key(),save(),update(),delete(),load(),loadFrom(),loadFromQuery(),source()andsetSource(), amongst others).The
AbstractModelclass extends\Charcoal\Config\AbstractEntitywhich also defines basic data-access methods (setData(),data(),keys(),has(),get(),set(), plus theArrayAccess,JsonSerializableandSerializableinterfaces).
Properties (metadata)
| Property | Type | Default | Description |
|---|---|---|---|
| active | boolean |
true |
… |
| position | number |
null |
… |
| created | date-time |
null [1] |
… |
| created_by | string |
'' [1] |
… |
| last_modified | date-time |
null [2] |
… |
| last_modified_by | string |
'' [2] |
… |
[1] Auto-generated upon save()
[2] Auto-generated upon update()
Default metadata is defined in
metadata/charcoal/object/content.json
UserData
The UserData class should be used for all objects that are expected to be entered from the project's "client" or "end user".
API
setIp($ip)ip()setTs($ts)ts()setLang($lang)lang()
The
Contentclass extends\Charcoal\Model\AbstractModelfrom the charcoal/core module, which means that it also inherits its API as well as theDescribableInterface(metadata(),setMetadata()andloadMetadata(), amongst others) and theStorableInterface(id(),key(),save(),update(),delete(),load(),loadFrom(),loadFromQuery(),source()andsetSource(), amongst others).The
AbstractModelclass extends\Charcoal\Config\AbstractEntitywhich also defines basic data-access methods (setData(),data(),keys(),has(),get(),set(), plus theArrayAccess,JsonSerializableandSerializableinterfaces).
Properties (metadata)
| Property | Type | Default | Description |
|---|---|---|---|
| ip | ip |
null [1] |
… |
| ts | date-time |
null [1] |
… |
| lang | lang |
null [1] |
… |
[1] Auto-generated upon save() and update()
Default metadata is defined in
metadata/charcoal/object/user-data.json
Object behaviors
Archivable
The archivable behavior is not yet documented. It is still under heavy development.
Categorizable
API
setCategory($category)category()setCategoryType($type)categoryType()
Properties (metadata)
| Property | Type | Default | Description |
|---|---|---|---|
| category | object |
null |
The object's category.[1] |
[1] The category obj_type must be explicitely set in implementation's metadata.
Default metadata is defined in
metadata/charcoal/object/catgorizable-interface.json
Category
API
setCategoryItemType($type)categoryItemType()numCategoryItems()hasCategoryItems()categoryItems()
Properties (metadata)
| Property | Type | Default | Description |
|---|---|---|---|
| category_item | string |
null |
… |
Default metadata is defined in
metadata/charcoal/object/catgory-interface.json
Hierarchical
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)
Properties (metadata)
| Property | Type | Default | Description |
|---|---|---|---|
| master | object |
null |
The master object (parent in hierarchy). |
Default metadata is defined in
metadata/charcoal/object/hierarchical-interface.json.
Publishable
setPublishDate($publishDate)publishDate()setExpiryDate($expiryDate)expiryDate()setPublishStatus($status)publishStatus()isPublished()
Properties (metadata)
| Property | Type | Default | Description |
|---|---|---|---|
| publishDate | date-time |
null |
… |
| expiryDate | date-time |
null |
… |
| publishStatus | string [1] |
'draft' |
… |
Default metadata is defined in
metadata/charcoal/object/publishable-interface.json.
Revisionable
Revisionable objects implement \Charcoal\Object\Revision\RevisionableInterface, which can be easily implemented by using \Charcoal\Object\Revision\RevisionableTrait.
Revisionable objects create revisions which logs the changes between an object's versions, as diffs.
API
setRevisionEnabled(bool$enabled)revisionEnabled()revisionObject()generateRevision()latestRevision()revisionNum(integer $revNum)allRevisions(callable $callback = null)revertToRevision(integer $revNum)
Properties (metadata)
The revisionable behavior does not implement any properties as all logic & data is self-contained in the revisions.
Routable
The routable behavior is not yet documented. It is still under heavy development.
Helpers
ObjectDraft
…
ObjectRevision
Upon every update in storage, a revisionable object creates a new revision (a \Charcoal\Object\ObjectRevision instance) which holds logs the changes (diff) between versions of an object:
Revision properties
| Property | Type | Default | Description |
|---|---|---|---|
| target_type | string |
null |
The object type of the target object. |
| target_id | string |
null |
The object idenfiier of the target object. |
| rev_num | integer |
null |
Revision number, (auto-generated). |
| ref_ts | date-time |
||
| rev_user | string |
null |
|
| data_prev | structure |
||
| data_obj | structure |
||
| data_diff | structure |
Revision methods
createFromObject(RevisionableInterface $obj)createDiff(array $dataPrev, array $dataObj)lastObjectRevision(RevisionableInterface $obj)objectRevisionNum(RevisionableInterface $obj, integer $revNum)
ObjetSchedule
It is possible, (typically from the charcoal admin backend), to create schedule (a \Charcaol\Object\ObjectSchedule instance) which associate a set of changes to be applied automatically to an object:
Schedule properties
| Property | Type | Default | Description |
|---|---|---|---|
| target_type | string |
null |
The object type of the target object. |
| target_id | string |
null |
The object idenfiier of the target object. |
| scheduled_date | date-time |
null |
|
| data_diff | structure |
[] |
|
| processed | boolean |
false |
|
| processed_date |
Schedule methods (API)
process([callable $callback, callable $successCallback,callable $failureCallback])
Scheduled actions should be run with a timely cron job. The charcoal/admin module contains a script to run schedules automatically:
./vendor/bin/charcoal admin/object/process-schedules`