{"id":19250255,"url":"https://github.com/charcoalphp/object","last_synced_at":"2025-02-23T16:27:37.313Z","repository":{"id":37491962,"uuid":"505906373","full_name":"charcoalphp/object","owner":"charcoalphp","description":"[READ-ONLY] Object definition (Content and UserData), behaviors and tools.","archived":false,"fork":false,"pushed_at":"2024-03-13T15:05:15.000Z","size":212,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-05T09:48:52.089Z","etag":null,"topics":["charcoal","content","model","object","php","read-only-repository","revision","route","userdata"],"latest_commit_sha":null,"homepage":"https://github.com/charcoalphp/charcoal","language":"PHP","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/charcoalphp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-06-21T15:44:41.000Z","updated_at":"2022-06-21T16:57:26.000Z","dependencies_parsed_at":"2024-01-13T04:49:51.820Z","dependency_job_id":"cfa8ccf2-ed08-4e43-939a-4070cd35dfdb","html_url":"https://github.com/charcoalphp/object","commit_stats":{"total_commits":127,"total_committers":11,"mean_commits":"11.545454545454545","dds":0.7007874015748031,"last_synced_commit":"1297ba9025b791ff029a2823ee0517ed24641820"},"previous_names":[],"tags_count":63,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fobject","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fobject/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fobject/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fobject/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charcoalphp","download_url":"https://codeload.github.com/charcoalphp/object/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240342717,"owners_count":19786565,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["charcoal","content","model","object","php","read-only-repository","revision","route","userdata"],"created_at":"2024-11-09T18:16:38.167Z","updated_at":"2025-02-23T16:27:37.282Z","avatar_url":"https://github.com/charcoalphp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Charcoal Object\n===============\n\nThe Object package provides abstract objects, behaviours, and tools for building user-facing Web sites.\n\n## Installation\n\n```shell\ncomposer require charcoal/object\n```\n\n## Overview\n\nThe package provides a bunch of basic classes, helpers as well as object behaviors (interfaces + traits).\n\n### Basic classes\n\nAll 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.\n\n#### Content\n\nThe **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.\n\n**API**\n\n* ` setActive($active)`\n* `active()`\n* `setPosition($position)`\n* `position()`\n* `setCreated($created)`\n* `created()`\n* `setCreatedBy($createdBy)`\n* `createdBy()`\n* `setLastModified($lastModified)`\n* `lastModified()`\n* `setLastModifiedBy($lastModifiedBy)`\n* `lastModifiedBy()`\n\n\u003e 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).\n\u003e\n\u003e 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).\n\n**Properties (metadata)**\n\n| Property               | Type        | Default     | Description |\n| ---------------------- | ----------- | ----------- | ----------- |\n| **active**             | `boolean`   | `true`      | …           |\n| **position**           | `number`    | `null`      | …           |\n| **created**            | `date-time` | `null` [1]  | …           |\n| **created_by**         | `string`    | `''` [1]    | …           |\n| **last_modified**      | `date-time` | `null` [2]  | …           |\n| **last\\_modified\\_by** | `string`    | `''` [2]    | …           |\n\n\u003csmall\u003e[1] Auto-generated upon `save()`\u003c/small\u003e\u003cbr\u003e\n\u003csmall\u003e[2] Auto-generated upon `update()`\u003c/small\u003e\u003cbr\u003e\n\n\u003e Default metadata is defined in `metadata/charcoal/object/content.json`\n\n#### UserData\n\nThe **UserData** class should be used for all objects that are expected to be entered from the project's \"client\" or \"end user\".\n\n**API**\n\n* `setIp($ip)`\n* `ip()`\n* `setTs($ts)`\n* `ts()`\n* `setLang($lang)`\n* `lang()`\n\n\u003e 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).\n\u003e\n\u003e 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).\n\n**Properties (metadata)**\n\n| Property  | Type        | Default     | Description |\n| --------- | ----------- | ----------- | ----------- |\n| **ip**    | `ip`        | `null` [1]  | …           |\n| **ts**    | `date-time` | `null` [1]  | …           |\n| **lang**  | `lang`      | `null` [1]  | …           |\n\n\u003csmall\u003e[1] Auto-generated upon `save()` and `update()`\u003c/small\u003e\u003cbr\u003e\n\n\u003e Default metadata is defined in `metadata/charcoal/object/user-data.json`\n\n### Object behaviors\n\n* [Archivable](#archivable)\n* [Categorizable](#categorizable)\n* [Category](#category)\n* [Hierarchical](#hierarchical)\n* [Publishable](#publishable)\n* [Revisionable](#revisionable)\n* [Routable](#routable)\n\n#### Archivable\n\n_The archivable behavior is not yet documented. It is still under heavy development._\n\n#### Categorizable\n\n**API**\n\n* `setCategory($category)`\n* `category()`\n* `setCategoryType($type)`\n* `categoryType()`\n\n**Properties (metadata)**\n\n| Property        | Type       | Default     | Description |\n| --------------- | ---------- | ----------- | ----------- |\n| **category**    | `object`   | `null`      | The object's category.[1] |\n\n\u003csmall\u003e[1] The category `obj_type` must be explicitely set in implementation's metadata.\u003c/small\u003e\n\n\u003e Default metadata is defined in `metadata/charcoal/object/catgorizable-interface.json`\n\n#### Category\n\n**API**\n\n* `setCategoryItemType($type)`\n* `categoryItemType()`\n* `numCategoryItems()`\n* `hasCategoryItems()`\n* `categoryItems()`\n\n**Properties (metadata)**\n\n| Property          | Type       | Default     | Description |\n| ----------------- | ---------- | ----------- | ----------- |\n| **category_item** | `string`   | `null`      | …           |\n\n\u003e Default metadata is defined in `metadata/charcoal/object/catgory-interface.json`\n\n#### Hierarchical\n\n**API**\n\n* `hasMaster()`\n* `isTopLevel()`\n* `isLastLevel()`\n* `hierarchyLevel()`\n* `master()`\n* `toplevelMaster()`\n* `hierarchy()`\n* `invertedHierarchy()`\n* `isMasterOf($child)`\n* `recursiveIsMasterOf($child)`\n* `hasChildren()`\n* `numChildren()`\n* `recursiveNumChildren()`\n* `children()`\n* `isChildOf($master)`\n* `recursiveIsChildOf($master)`\n* `hasSiblings()`\n* `numSiblings()`\n* `siblings()`\n* `isSiblingOf($sibling)`\n\n**Properties (metadata)**\n\n| Property      | Type       | Default     | Description |\n| ------------- | ---------- | ----------- | ----------- |\n| **master**    | `object`   | `null`      | The master object (parent in hierarchy). |\n\n\u003e Default metadata is defined in `metadata/charcoal/object/hierarchical-interface.json`.\n\n#### Publishable\n\n* `setPublishDate($publishDate)`\n* `publishDate()`\n* `setExpiryDate($expiryDate)`\n* `expiryDate()`\n* `setPublishStatus($status)`\n* `publishStatus()`\n* `isPublished()`\n\n**Properties (metadata)**\n\n| Property           | Type         | Default    | Description |\n| ------------------ | ------------ | ---------- | ----------- |\n| **publishDate**    | `date-time`  | `null`     | …           |\n| **expiryDate**     | `date-time`  | `null`     | …           |\n| **publishStatus**  | `string` [1] | `'draft'`  | …           |\n\n\u003e Default metadata is defined in `metadata/charcoal/object/publishable-interface.json`.\n\n#### Revisionable\n\nRevisionable objects implement `\\Charcoal\\Object\\Revision\\RevisionableInterface`, which can be easily implemented by using `\\Charcoal\\Object\\Revision\\RevisionableTrait`.\n\nRevisionable objects create _revisions_ which logs the changes between an object's versions, as _diffs_.\n\n**API**\n\n* `setRevisionEnabled(bool$enabled)`\n* `revisionEnabled()`\n* `revisionObject()`\n* `generateRevision()`\n* `latestRevision()`\n* `revisionNum(integer $revNum)`\n* `allRevisions(callable $callback = null)`\n* `revertToRevision(integer $revNum)`\n\n**Properties (metadata)**\n\n_The revisionable behavior does not implement any properties as all logic \u0026 data is self-contained in the revisions._\n\n#### Routable\n\n_The routable behavior is not yet documented. It is still under heavy development._\n\n### Helpers\n\n#### ObjectDraft\n\n…\n\n#### ObjectRevision\n\nUpon 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:\n\n**Revision properties**\n\n| Property           | Type         | Default    | Description |\n| ------------------ | ------------ | ---------- | ----------- |\n| **target_type**    | `string`     | `null`     | The object type of the target object.\n| **target_id**      | `string`     | `null`     | The object idenfiier of the target object.\n| **rev_num**        | `integer`    | `null`     | Revision number, (auto-generated).\n| **ref_ts**         | `date-time`  |            |\n| **rev_user**       | `string`     | `null`     |\n| **data_prev**      | `structure`  |            |\n| **data_obj**       | `structure`  |            |\n| **data_diff**      | `structure`  |            |\n\n**Revision methods**\n\n* `createFromObject(RevisionableInterface $obj)`\n* `createDiff(array $dataPrev, array $dataObj)`\n* `lastObjectRevision(RevisionableInterface $obj)`\n* `objectRevisionNum(RevisionableInterface $obj, integer $revNum)`\n\n#### ObjetSchedule\n\nIt 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:\n\n**Schedule properties**\n\n| Property           | Type         | Default    | Description |\n| ------------------ | ------------ | ---------- | ----------- |\n| **target_type**    | `string`     | `null`     | The object type of the target object.\n| **target_id**      | `string`     | `null`     | The object idenfiier of the target object.\n| **scheduled_date** | `date-time`  | `null`     |\n| **data_diff**      | `structure`  | `[]`       |\n| **processed**      | `boolean`    | `false`    |\n| **processed_date** |              |            |\n\n**Schedule methods (API)**\n\n* `process([callable $callback, callable $successCallback,callable $failureCallback])`\n\n\u003e Scheduled actions should be run with a timely cron job. The [charcoal/admin] module contains a script to run schedules automatically:\n\u003e\n\u003e ```shell\n\u003e ./vendor/bin/charcoal admin/object/process-schedules`\n\u003e ```\n\n## Resources\n\n* [Contributing](https://github.com/charcoalphp/.github/blob/main/CONTRIBUTING.md)\n* [Report issues](https://github.com/charcoalphp/charcoal/issues) and\n  [send pull requests](https://github.com/charcoalphp/charcoal/pulls)\n  in the [main Charcoal repository](https://github.com/charcoalphp/charcoal)\n\n[charcoal/admin]: https://github.com/charcoalphp/admin\n[charcoal/core]:  https://github.com/charcoalphp/core\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Fobject","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharcoalphp%2Fobject","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Fobject/lists"}