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

• How to install
  • Dependencies
• The Charcoal Object
  • Basic classes
    • Content
    • UserData
  • Object behaviors
    • Archivable
    • Categorizable
    • Category
    • Hierarchical
    • Publishable
    • Revisionable
    • Routable
  • Helpers
    • ObjectDraft
    • ObjectRevision
    • ObjectSchedule
• Development
  • Development dependencies
  • Continuous Integration
  • Coding Style
  • Authors
  • Changelog

The preferred (and only supported) way of installing charcoal-object is with composer:

★ composer require locomotivemtl/charcoal-object

• PHP 5.6+
  • This is the last supported version of PHP.
  • PHP 7 is also supported (meaning green on travis…).

The \Charcoal\Object namespace provides a bunch of basic classes, helpers as well as object behaviors (interfaces + traits).

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.

The Content base class should be used for all objects which can be "managed". Typically by an administrator, via the charcoal-admin module. 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 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)

[1] Auto-generated upon save()
[2] Auto-generated upon update()

Default metadata is defined in metadata/charcoal/object/content.json

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

[1] Auto-generated upon save() and update()

Default metadata is defined in metadata/charcoal/object/user-data.json

• Archivable
• Categorizable
• Category
• Hierarchical
• Publishable
• Revisionable
• Routable

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

API

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

Properties (metadata)

[1] The category obj_type must be explicitely set in implementation's metadata.

Default metadata is defined in metadata/charcoal/object/catgorizable-interface.json

API

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

Properties (metadata)

Default metadata is defined in 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)

Properties (metadata)

Default metadata is defined in metadata/charcoal/object/hierarchical-interface.json.

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

Properties (metadata)

Default metadata is defined in metadata/charcoal/object/publishable-interface.json.

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.

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

…

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

Revision methods

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

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

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`

To install the development environment:

★ composer install --prefer-source

To run the scripts (phplint, phpcs and phpunit):

★ composer test

• The auto-generated phpDocumentor API documentation is available at https://locomotivemtl.github.io/charcoal-object/docs/master/
• The auto-generated apigen API documentation is available at https://codedoc.pub/locomotivemtl/charcoal-object/master/

• phpunit/phpunit
• squizlabs/php_codesniffer
• satooshi/php-coveralls

Service	Badge	Description
Travis		Runs code sniff check and unit tests. Auto-generates API documentation.
Scrutinizer		Code quality checker. Also validates API documentation quality.
Coveralls		Unit Tests code coverage.
Sensiolabs		Another code quality checker, focused on PHP.

The charcoal-object module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• Read the phpcs.xml file for all the details on code style.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

• Mathieu Ducharme, [email protected]
• Chauncey McAskill
• Locomotive Inc.

Charcoal is licensed under the MIT license. See LICENSE for details.