PHPackages                             charcoal/object - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. charcoal/object

ActiveLibrary

charcoal/object
===============

Object (Content and UserData) definition and object behaviors and tools.

v5.0.0(2y ago)0706MITPHPPHP ^7.4 || ^8.0

Since Jan 19Pushed 2y ago2 watchersCompare

[ Source](https://github.com/charcoalphp/object)[ Packagist](https://packagist.org/packages/charcoal/object)[ RSS](/packages/charcoal-object/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (11)Versions (67)Used By (6)

Charcoal Object
===============

[](#charcoal-object)

The Object package provides abstract objects, behaviours, and tools for building user-facing Web sites.

Installation
------------

[](#installation)

```
composer require charcoal/object
```

Overview
--------

[](#overview)

The package provides a bunch of basic classes, helpers as well as object behaviors (interfaces + traits).

### Basic classes

[](#basic-classes)

All charcoal project object classes should extend one of the 2 base classes, [`\Charcoal\Object\Content`](#content), for data created and managed by administrators or [`\Charcoal\Object\UserData`](#userdata), for data created from clients / users.

#### Content

[](#content)

The **Content** base class should be used for all objects which can be "managed". Typically by an administrator, via the [charcoal/admin](https://github.com/charcoalphp/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 `Content` class extends `\Charcoal\Model\AbstractModel` from the [charcoal/core](https://github.com/charcoalphp/core) module, which means that it also inherits its API as well as the `DescribableInterface` (`metadata()`, `setMetadata()` and `loadMetadata()`, amongst others) and the `StorableInterface` (`id()`, `key()`, `save()`, `update()`, `delete()`, `load()`, `loadFrom()`, `loadFromQuery()`, `source()` and `setSource()`, amongst others).
>
> The `AbstractModel` class extends `\Charcoal\Config\AbstractEntity` which also defines basic data-access methods (`setData()`, `data()`, `keys()`, `has()`, `get()`, `set()`, plus the `ArrayAccess`, `JsonSerializable` and `Serializable` interfaces).

**Properties (metadata)**

PropertyTypeDefaultDescription**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

[](#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 `Content` class extends `\Charcoal\Model\AbstractModel` from the [charcoal/core](https://github.com/charcoalphp/core) module, which means that it also inherits its API as well as the `DescribableInterface` (`metadata()`, `setMetadata()` and `loadMetadata()`, amongst others) and the `StorableInterface` (`id()`, `key()`, `save()`, `update()`, `delete()`, `load()`, `loadFrom()`, `loadFromQuery()`, `source()` and `setSource()`, amongst others).
>
> The `AbstractModel` class extends `\Charcoal\Config\AbstractEntity` which also defines basic data-access methods (`setData()`, `data()`, `keys()`, `has()`, `get()`, `set()`, plus the `ArrayAccess`, `JsonSerializable` and `Serializable` interfaces).

**Properties (metadata)**

PropertyTypeDefaultDescription**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

[](#object-behaviors)

- [Archivable](#archivable)
- [Categorizable](#categorizable)
- [Category](#category)
- [Hierarchical](#hierarchical)
- [Publishable](#publishable)
- [Revisionable](#revisionable)
- [Routable](#routable)

#### Archivable

[](#archivable)

*The archivable behavior is not yet documented. It is still under heavy development.*

#### Categorizable

[](#categorizable)

**API**

- `setCategory($category)`
- `category()`
- `setCategoryType($type)`
- `categoryType()`

**Properties (metadata)**

PropertyTypeDefaultDescription**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

[](#category)

**API**

- `setCategoryItemType($type)`
- `categoryItemType()`
- `numCategoryItems()`
- `hasCategoryItems()`
- `categoryItems()`

**Properties (metadata)**

PropertyTypeDefaultDescription**category\_item**`string``null`…> Default metadata is defined in `metadata/charcoal/object/catgory-interface.json`

#### Hierarchical

[](#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)**

PropertyTypeDefaultDescription**master**`object``null`The master object (parent in hierarchy).> Default metadata is defined in `metadata/charcoal/object/hierarchical-interface.json`.

#### Publishable

[](#publishable)

- `setPublishDate($publishDate)`
- `publishDate()`
- `setExpiryDate($expiryDate)`
- `expiryDate()`
- `setPublishStatus($status)`
- `publishStatus()`
- `isPublished()`

**Properties (metadata)**

PropertyTypeDefaultDescription**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)

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

[](#routable)

*The routable behavior is not yet documented. It is still under heavy development.*

### Helpers

[](#helpers)

#### ObjectDraft

[](#objectdraft)

…

#### ObjectRevision

[](#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**

PropertyTypeDefaultDescription**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

[](#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**

PropertyTypeDefaultDescription**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](https://github.com/charcoalphp/admin) module contains a script to run schedules automatically:
>
> ```
> ./vendor/bin/charcoal admin/object/process-schedules`
> ```

Resources
---------

[](#resources)

- [Contributing](https://github.com/charcoalphp/.github/blob/main/CONTRIBUTING.md)
- [Report issues](https://github.com/charcoalphp/charcoal/issues) and [send pull requests](https://github.com/charcoalphp/charcoal/pulls)in the [main Charcoal repository](https://github.com/charcoalphp/charcoal)

###  Health Score

36

—

LowBetter than 82% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity9

Limited adoption so far

Community25

Small or concentrated contributor base

Maturity83

Battle-tested with a long release history

 Bus Factor2

2 contributors hold 50%+ of commits

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~42 days

Recently: every ~15 days

Total

63

Last Release

796d ago

Major Versions

0.8.0.1 → v2.1.22022-06-21

v2.2.3 → v3.1.02022-08-08

v3.1.8 → v4.0.02022-09-21

v4.1.0 → v5.0.02024-03-13

PHP version history (4 changes)0.1PHP >=5.6.0

0.5.1PHP >=5.6.0 || >=7.0

0.8.0PHP ^7.3 || ^8.0

v2.1.2PHP ^7.4 || ^8.0

### Community

Maintainers

![](https://www.gravatar.com/avatar/cfb071c0ff7ce9500c528a003a2c53124248debc3e5bf367c17f89f5e6136125?d=identicon)[mducharme](/maintainers/mducharme)

![](https://www.gravatar.com/avatar/0a4f39523b4b2837562ba0848a0327b8d340118d1ba87cb0f5d59b1d5cb6beba?d=identicon)[mcaskill](/maintainers/mcaskill)

![](https://www.gravatar.com/avatar/f3f29e38395113e2400bdd7e51bea982b17f120d4d5a53d4473b53118ee46f8d?d=identicon)[JoelAlphonso](/maintainers/JoelAlphonso)

![](https://www.gravatar.com/avatar/4229f19eecd12c2b651b6502dcc5adfba48c5770db3d2dbea55fc92c7a246b2b?d=identicon)[BeneRoch](/maintainers/BeneRoch)

---

Top Contributors

[![mducharme](https://avatars.githubusercontent.com/u/12157?v=4)](https://github.com/mducharme "mducharme (41 commits)")[![mcaskill](https://avatars.githubusercontent.com/u/29353?v=4)](https://github.com/mcaskill "mcaskill (40 commits)")[![JoelAlphonso](https://avatars.githubusercontent.com/u/10762266?v=4)](https://github.com/JoelAlphonso "JoelAlphonso (19 commits)")[![actions-user](https://avatars.githubusercontent.com/u/65916846?v=4)](https://github.com/actions-user "actions-user (18 commits)")[![dominiclord](https://avatars.githubusercontent.com/u/1775204?v=4)](https://github.com/dominiclord "dominiclord (8 commits)")[![veve40](https://avatars.githubusercontent.com/u/7537381?v=4)](https://github.com/veve40 "veve40 (5 commits)")[![BeneRoch](https://avatars.githubusercontent.com/u/3017380?v=4)](https://github.com/BeneRoch "BeneRoch (4 commits)")[![losted](https://avatars.githubusercontent.com/u/165665?v=4)](https://github.com/losted "losted (2 commits)")

---

Tags

charcoalcontentmodelobjectphpread-only-repositoryrevisionrouteuserdata

###  Code Quality

TestsPHPUnit

Code StylePHP\_CodeSniffer

### Embed Badge

![Health badge](/badges/charcoal-object/health.svg)

```
[![Health](https://phpackages.com/badges/charcoal-object/health.svg)](https://phpackages.com/packages/charcoal-object)
```

###  Alternatives

[api-platform/metadata

API Resource-oriented metadata attributes and factories

223.5M96](/packages/api-platform-metadata)[phpro/http-tools

HTTP tools for developing more consistent HTTP implementations.

28137.8k](/packages/phpro-http-tools)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

245.2k](/packages/aedart-athenaeum)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)