{"id":19250266,"url":"https://github.com/charcoalphp/property","last_synced_at":"2026-05-18T19:33:49.172Z","repository":{"id":37806344,"uuid":"505904443","full_name":"charcoalphp/property","owner":"charcoalphp","description":"[READ-ONLY] Properties define model metadata.","archived":false,"fork":false,"pushed_at":"2024-03-13T15:05:16.000Z","size":4705,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-08-10T17:25:57.597Z","etag":null,"topics":["charcoal","json","metadata","model","php","properties","read-only-repository"],"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,"publiccode":null,"codemeta":null}},"created_at":"2022-06-21T15:39:27.000Z","updated_at":"2022-06-21T19:32:34.000Z","dependencies_parsed_at":"2024-01-13T04:49:51.169Z","dependency_job_id":"46e1202e-f1e1-4282-ba0e-b7ea51cafbac","html_url":"https://github.com/charcoalphp/property","commit_stats":{"total_commits":404,"total_committers":13,"mean_commits":"31.076923076923077","dds":0.6188118811881188,"last_synced_commit":"7e879d141b14c7ce64ad9a25c459e59943dcf3ea"},"previous_names":[],"tags_count":92,"template":false,"template_full_name":null,"purl":"pkg:github/charcoalphp/property","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fproperty","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fproperty/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fproperty/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fproperty/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/charcoalphp","download_url":"https://codeload.github.com/charcoalphp/property/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/charcoalphp%2Fproperty/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274209176,"owners_count":25241782,"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","status":"online","status_checked_at":"2025-09-08T02:00:09.813Z","response_time":121,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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","json","metadata","model","php","properties","read-only-repository"],"created_at":"2024-11-09T18:16:40.575Z","updated_at":"2026-05-18T19:33:44.126Z","avatar_url":"https://github.com/charcoalphp.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"Charcoal Property\n=================\n\nThe Property package provides abstract tools for defining object metadata.\n\n## Installation\n\n```shell\ncomposer require charcoal/property\n```\n\n## Overview\n\nProperties are defined globally for objects (_Charcoal models_) in its `metadata`. They provide properties definition, storage definition and validation definition.\n\n\u003e The `metadata()` method is defined in `\\Charcoal\\Model\\DescribableInterface`.\n\u003e The `properties()` method is defined in `\\Charcoal\\Property\\DescribablePropertyInterface`.\n\n### Property options\n\nThe basic property interface (API) requires / provides the following members:\n\n| Name           | [†] | Type                | Description\n| -------------- | :-: | ------------------- | -----------\n| **ident**      |     | _string_            | The property idenfifier (typically, its containing object matching property name).\n| **label**      |     | _Translation_       | ...\n| **l10n**       |     | _bool_              | If true, then the data should be stored in a l10n-aware structure (be translatable).s\n| **hidden**     |     | _bool_              |\n| **multiple**   |     | _bool_              | Multiple values can be held and stored, if true.\n| **required**   |  ✓  | _bool_              |\n| **unique**     |  ✓  | _bool_              |\n| **storable**   |     | _bool_              |\n| **active**     |     | _bool_              |\n\nNotes:\n\n* \u003csup\u003e[†]\u003c/sup\u003e Indicates options used in validation.\n\n\u003e All those methods can be accessed either via the `setData()` method or with a standard PSR-1/PSR-2 getter / setter. (`foo` would have `foo()` as a getter and `setFoo()` as a setter).\n\n### Data retrieval\n\n* To get a normalized value, use the `parseVal($val)` method.\n* To get a string-safe, displaybale value, use `displayVal($val)`.\n* To get the storage-ready format, use `storageVal($val)`.\n\n\u003e Custom data retrieval methods can be further defined in each properties. (For example, formatted date or custom color formats).\n\n### Default validation\n\nValidation is provided with a `Validator` object, from [charcoal/core].\n\n* `required`\n* `unique`\n* `allow_null`\n\n\u003e Validation is being rebuilt in a new charcoal/validator package.\n\n### Source and storage methods\n\nProperties need 4 method to integrate with a SQL source:\n\n* `sqlEncoding()` _string_ The SQL column encoding \u0026 collation (ex: `utf8mb4`)\n* `sqlExtra()` _string_ Raw SQL string that will be appended to\n* `sqlType()` _string_ The SQL column type (ex: `VARCHAR(16)`)\n* `sqlPdoType()` _integer_ The PDO column type (ex: `PDO::PARAM_STR`)\n\n\u003e Those methods are _abstract_ and therefore must be implemented in actual properties.\n\n## Types of properties\n\n* [Boolean](#boolean-property)\n* [Color](#color-property)\n* ~~Date~~\n  * [DateTime](#datetime-property)\n  * ~~Day~~\n  * ~~Month~~\n  * ~~Time~~\n  * ~~Year~~\n* [File](#file-property)\n  * [Audio](#file-audio-property)\n  * [Image](#image-property)\n  * ~~Video~~\n* [Lang](#lang-property)\n* [Number](#number-property)\n  * ~~Float~~\n  * ~~Integer~~\n* [Object](#object-property)\n* [Id](#id-property)\n* [IP](#ip-property)\n* [String](#string-property)\n  * [Html](#html-string-property)\n  * [Password](#password-string-property)\n  * [Phone](#phone-string-property)\n  * [Text](#text-string-propery)\n* ~~Structure~~\n  * [MapStructure](#map-structure-property)\n  * [ModelStructure](#model-structure-property)\n\nRetrieve\n\n### Boolean Property\n\nThe boolean property is one of the simplest possible: it simply holds boolean (`true` / `false`) values.\n\n#### Boolean Property options\n\nThe boolean property adds the following concepts to the [basic property options](#basic-property-options):\n\n| Name            | [†] | Type                | Description\n| --------------- | :-: | ------------------- | -----------\n| **false_label** |  -  | _Translation_       | Label, for \"true\" value.\n| **true_label**  |  -  | _Translation_       | Label, for \"false\" value.\n\n\nNotes:\n\n* \u003csup\u003e[†]\u003c/sup\u003e Indicates options used in validation.\n\n\u003e ⚠ Boolean properties can not be multiple. (`multiple()` will always return false). Calling `setMultiple(true)` on a `boolean` property will throw an exception.\n\n### Color Property\n\nThe color property stores a color. If alpha is not supported, it is stored as an hexadecimal value (ex: `#5590BA`). If alpha is supported, it is stored as a rgba() string value (ex: `rgb(85, 144, 186, 0.5)`).\n\n#### Color Property options\n\nThe boolean property adds the following concepts to the [basic property options](#basic-property-options):\n\n| Name               | [†] | Type                | Description\n| ------------------ | :-: | ------------------- | -----------\n| **support_alpha**  |  ✓  | _boolean_           | ...\n\nNotes:\n\n* \u003csup\u003e[†]\u003c/sup\u003e Indicates options used in validation.\n\n\n### DateTime Property\n\nThe datetime property store a date (and time) value.\n\n#### DateTime Property options\n\nThe datetime property adds the following concepts to the [basic property options](#basic-property-options):\n\n| Name            | [†] | Type                | Description\n| --------------- | :-: | ------------------- | -----------\n| **min**         |  ✓  | _DateTime_          | Minimum date value. If 0, empty or null, then there is no minimal constraint.\n| **max**         |  ✓  | _DateTime_          | Maximum date value. If 0, empty or null, then there is no maximal constraint.\n| **format**      |     | _string_            | The date format is a string (in PHP's DateTime `format()`) that manages how to format the date value for display. Defaults to \\\"Y-m-d H:i:s\\\".\n\nNotes:\n\n* \u003csup\u003e[†]\u003c/sup\u003e Indicates options used in validation.\n\n\u003e ⚠ DateTime properties can not be multiple. (`multiple()` will always return false). Calling `setMultiple(true)` on a `date-time` property will throw an exception.\n\n### ID Property\n\nThe ID property holds an ID, typically the main object identifier (unique index key).\n\nThe ID value can be generated by many **mode**:\n\n* `auto-increment` is the default mode. It uses the storage engine (_mysql_) auto-increment feature to keep an auto-incrementing integer index.\n* `uniqid` creates a 13-char string with PHP's `uniqid()` function.\n* `uuid` creates a 36-char string (a _RFC-4122 v4_ Universally-Unique Identifier, `uuidv4`).\n\n#### ID Property options\n\nThe ID property adds the following concepts to the [basic property options](#basic-property-options):\n\n| Name            | [†] | Type                | Description\n| --------------- | :-: | ------------------- | -----------\n| **mode**        |     | _string_            | The ID generation mode. Can be `auto-increment`, `uniqid` or `uuid`. |\n\n\u003e ⚠ Id properties can not be multiple. (`multiple()` will always return false). Calling `setMultiple(true)` on an `id` property will throw an exception.\n\n#### ID Property custom save\n\nUpon `save($val)`, the ID property auto-generates and ID if its mode is `uniqid` or `uuid`.\n\n\u003e Note: The `auto-increment` mode does not do anything on save; it relies on the storage engine / driver to implement auto-incrementation.\n\n### IP Property\n\nThe IP property holds an IP address. Only _IPv4_ addresses are supported for now.\n\nThere is 2 different storage modes for IP:\n\n* `string` is the default mode. It stores the IP address like `192.168.1.1`.\n* `int` stores the IP as a _signed long integer_.\n\n\u003e ⚠ Ip properties can not be multiple. (`multiple()` will always return false). Calling `setMultiple(true)` on an `ip` property will throw an exception.\n\n### File Property\n\nFile property holds an uploadable file.\n\n#### Values\n\nNote that only a _relative_\u003csup\u003e1\u003c/sup\u003e file path should be stored in the database.\n\n\u003csup\u003e1\u003c/sup\u003e Relative to project's `ROOT` + the property's `upload_path`.\n\n#### File Property options\n\nThe file property adds the following concepts to the [basic property options](#basic-property-options):\n\n| Name                  | [†] | Type        | Description\n| --------------------- | :-: | ----------- | -----------\n| **public_access**     |     | _bool_      | If the public access is true (default) then the file will be stored in a public filesystem. If not, then it will be stored in a private (non-web-accessible) filesystem.\n| **upload_path**       |     | _string_    | The default upload path, relative to `base_url`, where the uploaded files will be stored.\n| **overwrite**         |     | _bool_      | If true, when a target file already exists on the filesystem  it will be overwritten. If false, a new unique name will be generated (with a suffix).\n| **accepted_mimeypes** |  ✓  | _string[]_  | List of accepted mimetypes. Leave empty to accept all types (no mimetype constraint).\n| **max_filesize**      |  ✓  | _integer_   | Maximum allowed file size, in bytes. If 0, null or empty, then there are no size constraint.\n\nNotes:\n\n* \u003csup\u003e[†]\u003c/sup\u003e Indicates options used in validation.\n\n#### Additional file methods\n\n* `mimetype()` and `setMimetype()`\n* `filesize()` and `setFilesize()`\n* `dataUpload()`\n* `fileUpload()`\n\n#### File Property Custom Save\n\nUpon `save($val)`, the File property attempts to upload the file or create a file from data, if necessary. The uploaded file's path (_relative_) is returned.\n\n#### Specialized File properties\n\n* [`AudioProperty`](#audio-file-property)\n* [`ImageProperty`](#image-file-property)\n* ~~VideoProperty~~\n\n### Audio File Property\n\nAudio property are specialized [file property](#file-property) thay may only contain audio data.\n\n#### Accepted mimetypes\n\nThe `AudioProperty` extends `FileProperty` therefore provides \"accepted mimetypes\".\n\nDefault accepted mimetypes are:\n\n* `audio/mp3`\n* `audio/mpeg`\n* `audio/wav`\n* `audio/x-wav`.\n\n#### Audio file Property options\n\nThe audio property adds the following concepts to the [file property options](#file-property-options):\n\n| Name            | [†] | Type                | Description\n| --------------- | :-: | ------------------- | -----------\n| **min_length**  |  ✓  | _DateTime_          | Minimum audio length, in seconds. If 0, null or empty, then there is no minimal constraint.\n| **max_length**  |  ✓  | _DateTime_          | Maximum audio length, in seconds. If 0, null or empty, then there is no maximal constraint.\n\nNotes:\n\n* \u003csup\u003e[†]\u003c/sup\u003e Indicates options used in validation.\n\n### Image File Property\n\nImage property are specialized [file property](#file-property) thay may only contain image data.\n\n#### Accepted mimetypes\n\nThe `ImageProperty` extends `FileProperty` therefore provides \"accepted mimetypes\".\n\nDefault accepted mimetypes are:\n\n* `image/gif`\n* `image/jpg`\n* `image/jpeg`\n* `image/pjpeg`\n* `image/png`\n* `image/svg+xml`\n* `image/webp`\n\n#### Image file Property options\n\nThe audio property adds the following concepts to the [file property options](#file-property-options):\n\n| Name            | [†] | Type                | Description\n| --------------- | :-: | ------------------- | -----------\n| **effects**     |  ✓  | _array_             | Array of [charcoal/image] effects options.\n\nNotes:\n\n* \u003csup\u003e[†]\u003c/sup\u003e Indicates options used in validation.\n\n\n### Lang Property\n\nLanguage properties hold a language value.\n\n\u003e The `LangProperty` implements the `SelectablePropertyInterface`, but hardcode its `choices()` method to return the active language (from [charcoal/translator]).\n\n### Number Property\n\nNumber properties hold any kind of numeric data.\n\n### Object Property\n\nObject properties hold a reference to an external object of a certain type.\n\n#### Values\n\nThe target's `identifer` (determined by its _obj-type_'s `key`, which is typically \"id\") is the only thing held in the value / stored in the database. When displayed (with `displayVal()`), a string representation of the object should be rendered.\n\n#### Object Property options\n\nThe object property adds the following concepts to the [basic property options](#basic-property-options):\n\n| Name            | [†] | Type                | Description\n| --------------- | :-: | ------------------- | -----------\n| **obj-type**    |  ✓  | _string_            | The target object's type. In a string format that can be fetched with a `ModelFactory`. |\n| **pattern**     |     | _string_            | The rendering pattern, used to display the object(s) when necessary.\n\nNotes:\n\n* \u003csup\u003e[†]\u003c/sup\u003e Indicates options used in validation.\n\n### String Property\n\n#### String Property options\n\nThe string property adds the following concepts to the basic property options:\n\n| Name            | [†] | Type                | Description\n| --------------- | :-: | ------------------- | -----------\n| **max_length**  |  ✓  | _integer_           | Maximum allowed length, in (_multibytes_) characters. |\n| **min_length**  |  ✓  | _integer_           | Minimum allowed length, in (_multibytes_) characters. |\n| **regexp**      |  ✓  | _string_            | A validation regular expression that must be matched exactly. |\n| **allow_empty** |  ✓  | _bool_              | If empty strings are allowed.\n\nNotes:\n\n* \u003csup\u003e[†]\u003c/sup\u003e Indicates options used in validation.\n\n#### String default data\n\nBy default, the `string` property is targetted at small string (a maximum length) of `255` characters\n\n#### Specialized String properties\n\n* [`HtmlProperty`](#html-string-property)\n* [`PasswordProperty`](#password-string-property)\n* [`PhoneProperty`](#phone-string-property)\n* [`TextProperty`](#text-string-property)\n\n### Html String Property\n\nHTML properties are specialized [string property](#string-property) that may only contain HTML strings (instead of plain string).\n\n### Password String Property\n\nPassword properties are specialized [string property](#string-property) that holds (encrypted) password data.\n\nEncryption is performed with PHP's `password_hash` function.\n\n#### Password Property Custom Save\n\nUpon `save($val)`, the Password property hashes (or rehashes) the password to be stored safely (encrypted).\n\n### Phone String Property\n\nPhone properties are specialized [string property](#string-property) that holds a phone number.\n\nRight now, only \"north-american\" phone number styles are supported.\n\n### Text String Property\n\nText properties are specialized [string property](#string-property) thay typically holds longer text strings.\n\n### Map Structure Property\n\nMap structure properties hold complex map structure data, which can be points (markers), lines and / or polygons.\n\n### Properties table summary, for developers\n\n| Name         | Data type | Multiple | Custom Save | Custom Parse |\n| ------------ | :-------: | :------: | :---------: | :----------: |\n| Audio        | mixed     |          |             |              |\n| Boolean      | bool      | **No**   |             |              |\n| Color        | string    |          |             | **Yes**      |\n| DateTime     | DateTime  | **No**   |             | **Yes**      |\n| File         | mixed     |          | **Yes**     |              |\n| Html         | string    |          |             |              |\n| Id           | mixed     | **No**   | **Yes**     |              |\n| Image        | mixed     |          |             |              |\n| Ip           | mixed     | **No**   |             |              |\n| Lang         | string    |          |             |              |\n| MapStructure | mixed     |          |             |              |\n| Number       | numeric   |          |             |              |\n| Object       | mixed     |          |             | **Yes**      |\n| Password     | string    |          | **Yes**     |              |\n| Phone        | string    |          |             |              |\n| String       | string    |          |             |              |\n| Structure    | mixed     |          |             | **Yes**      |\n| Text         | string    |          |             |              |\n| Url          | string    |          |             |              |\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/core]:       https://github.com/charcoalphp/core\n[charcoal/image]:      https://github.com/charcoalphp/image\n[charcoal/translator]: https://github.com/charcoalphp/translator\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Fproperty","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcharcoalphp%2Fproperty","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcharcoalphp%2Fproperty/lists"}