PHPackages charcoal/property - 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/property ActiveLibrary charcoal/property ================= Charcoal Property defines an object (provides metadata) v5.0.0(2y ago)0843MITPHPPHP ^7.4 || ^8.0 Since Sep 14Pushed 2y ago2 watchersCompare [ Source](https://github.com/charcoalphp/property)[ Packagist](https://packagist.org/packages/charcoal/property)[ Docs](https://charcoal.locomotive.ca)[ RSS](/packages/charcoal-property/feed)WikiDiscussions main Synced 1mo ago READMEChangelogDependencies (14)Versions (98)Used By (3) Charcoal Property ================= [](#charcoal-property) The Property package provides abstract tools for defining object metadata. Installation ------------ [](#installation) ``` composer require charcoal/property ``` Overview -------- [](#overview) Properties are defined globally for objects (*Charcoal models*) in its `metadata`. They provide properties definition, storage definition and validation definition. > The `metadata()` method is defined in `\Charcoal\Model\DescribableInterface`. The `properties()` method is defined in `\Charcoal\Property\DescribablePropertyInterface`. ### Property options [](#property-options) The basic property interface (API) requires / provides the following members: Name\[†\]TypeDescription**ident***string*The property idenfifier (typically, its containing object matching property name).**label***Translation*...**l10n***bool*If true, then the data should be stored in a l10n-aware structure (be translatable).s**hidden***bool***multiple***bool*Multiple values can be held and stored, if true.**required**✓*bool***unique**✓*bool***storable***bool***active***bool*Notes: - \[†\] Indicates options used in validation. > 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). ### Data retrieval [](#data-retrieval) - To get a normalized value, use the `parseVal($val)` method. - To get a string-safe, displaybale value, use `displayVal($val)`. - To get the storage-ready format, use `storageVal($val)`. > Custom data retrieval methods can be further defined in each properties. (For example, formatted date or custom color formats). ### Default validation [](#default-validation) Validation is provided with a `Validator` object, from [charcoal/core](https://github.com/charcoalphp/core). - `required` - `unique` - `allow_null` > Validation is being rebuilt in a new charcoal/validator package. ### Source and storage methods [](#source-and-storage-methods) Properties need 4 method to integrate with a SQL source: - `sqlEncoding()` *string* The SQL column encoding & collation (ex: `utf8mb4`) - `sqlExtra()` *string* Raw SQL string that will be appended to - `sqlType()` *string* The SQL column type (ex: `VARCHAR(16)`) - `sqlPdoType()` *integer* The PDO column type (ex: `PDO::PARAM_STR`) > Those methods are *abstract* and therefore must be implemented in actual properties. Types of properties ------------------- [](#types-of-properties) - [Boolean](#boolean-property) - [Color](#color-property) - Date - [DateTime](#datetime-property) - Day - Month - Time - Year - [File](#file-property) - [Audio](#file-audio-property) - [Image](#image-property) - Video - [Lang](#lang-property) - [Number](#number-property) - Float - Integer - [Object](#object-property) - [Id](#id-property) - [IP](#ip-property) - [String](#string-property) - [Html](#html-string-property) - [Password](#password-string-property) - [Phone](#phone-string-property) - [Text](#text-string-propery) - Structure - [MapStructure](#map-structure-property) - [ModelStructure](#model-structure-property) Retrieve ### Boolean Property [](#boolean-property) The boolean property is one of the simplest possible: it simply holds boolean (`true` / `false`) values. #### Boolean Property options [](#boolean-property-options) The boolean property adds the following concepts to the [basic property options](#basic-property-options): Name\[†\]TypeDescription**false\_label**-*Translation*Label, for "true" value.**true\_label**-*Translation*Label, for "false" value.Notes: - \[†\] Indicates options used in validation. > ⚠ Boolean properties can not be multiple. (`multiple()` will always return false). Calling `setMultiple(true)` on a `boolean` property will throw an exception. ### Color Property [](#color-property) The 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)`). #### Color Property options [](#color-property-options) The boolean property adds the following concepts to the [basic property options](#basic-property-options): Name\[†\]TypeDescription**support\_alpha**✓*boolean*...Notes: - \[†\] Indicates options used in validation. ### DateTime Property [](#datetime-property) The datetime property store a date (and time) value. #### DateTime Property options [](#datetime-property-options) The datetime property adds the following concepts to the [basic property options](#basic-property-options): Name\[†\]TypeDescription**min**✓*DateTime*Minimum date value. If 0, empty or null, then there is no minimal constraint.**max**✓*DateTime*Maximum date value. If 0, empty or null, then there is no maximal constraint.**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".Notes: - \[†\] Indicates options used in validation. > ⚠ DateTime properties can not be multiple. (`multiple()` will always return false). Calling `setMultiple(true)` on a `date-time` property will throw an exception. ### ID Property [](#id-property) The ID property holds an ID, typically the main object identifier (unique index key). The ID value can be generated by many **mode**: - `auto-increment` is the default mode. It uses the storage engine (*mysql*) auto-increment feature to keep an auto-incrementing integer index. - `uniqid` creates a 13-char string with PHP's `uniqid()` function. - `uuid` creates a 36-char string (a *RFC-4122 v4* Universally-Unique Identifier, `uuidv4`). #### ID Property options [](#id-property-options) The ID property adds the following concepts to the [basic property options](#basic-property-options): Name\[†\]TypeDescription**mode***string*The ID generation mode. Can be `auto-increment`, `uniqid` or `uuid`.> ⚠ Id properties can not be multiple. (`multiple()` will always return false). Calling `setMultiple(true)` on an `id` property will throw an exception. #### ID Property custom save [](#id-property-custom-save) Upon `save($val)`, the ID property auto-generates and ID if its mode is `uniqid` or `uuid`. > Note: The `auto-increment` mode does not do anything on save; it relies on the storage engine / driver to implement auto-incrementation. ### IP Property [](#ip-property) The IP property holds an IP address. Only *IPv4* addresses are supported for now. There is 2 different storage modes for IP: - `string` is the default mode. It stores the IP address like `192.168.1.1`. - `int` stores the IP as a *signed long integer*. > ⚠ Ip properties can not be multiple. (`multiple()` will always return false). Calling `setMultiple(true)` on an `ip` property will throw an exception. ### File Property [](#file-property) File property holds an uploadable file. #### Values [](#values) Note that only a *relative*1 file path should be stored in the database. 1 Relative to project's `ROOT` + the property's `upload_path`. #### File Property options [](#file-property-options) The file property adds the following concepts to the [basic property options](#basic-property-options): Name\[†\]TypeDescription**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.**upload\_path***string*The default upload path, relative to `base_url`, where the uploaded files will be stored.**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).**accepted\_mimeypes**✓*string\[\]*List of accepted mimetypes. Leave empty to accept all types (no mimetype constraint).**max\_filesize**✓*integer*Maximum allowed file size, in bytes. If 0, null or empty, then there are no size constraint.Notes: - \[†\] Indicates options used in validation. #### Additional file methods [](#additional-file-methods) - `mimetype()` and `setMimetype()` - `filesize()` and `setFilesize()` - `dataUpload()` - `fileUpload()` #### File Property Custom Save [](#file-property-custom-save) Upon `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. #### Specialized File properties [](#specialized-file-properties) - [`AudioProperty`](#audio-file-property) - [`ImageProperty`](#image-file-property) - VideoProperty ### Audio File Property [](#audio-file-property) Audio property are specialized [file property](#file-property) thay may only contain audio data. #### Accepted mimetypes [](#accepted-mimetypes) The `AudioProperty` extends `FileProperty` therefore provides "accepted mimetypes". Default accepted mimetypes are: - `audio/mp3` - `audio/mpeg` - `audio/wav` - `audio/x-wav`. #### Audio file Property options [](#audio-file-property-options) The audio property adds the following concepts to the [file property options](#file-property-options): Name\[†\]TypeDescription**min\_length**✓*DateTime*Minimum audio length, in seconds. If 0, null or empty, then there is no minimal constraint.**max\_length**✓*DateTime*Maximum audio length, in seconds. If 0, null or empty, then there is no maximal constraint.Notes: - \[†\] Indicates options used in validation. ### Image File Property [](#image-file-property) Image property are specialized [file property](#file-property) thay may only contain image data. #### Accepted mimetypes [](#accepted-mimetypes-1) The `ImageProperty` extends `FileProperty` therefore provides "accepted mimetypes". Default accepted mimetypes are: - `image/gif` - `image/jpg` - `image/jpeg` - `image/pjpeg` - `image/png` - `image/svg+xml` - `image/webp` #### Image file Property options [](#image-file-property-options) The audio property adds the following concepts to the [file property options](#file-property-options): Name\[†\]TypeDescription**effects**✓*array*Array of [charcoal/image](https://github.com/charcoalphp/image) effects options.Notes: - \[†\] Indicates options used in validation. ### Lang Property [](#lang-property) Language properties hold a language value. > The `LangProperty` implements the `SelectablePropertyInterface`, but hardcode its `choices()` method to return the active language (from [charcoal/translator](https://github.com/charcoalphp/translator)). ### Number Property [](#number-property) Number properties hold any kind of numeric data. ### Object Property [](#object-property) Object properties hold a reference to an external object of a certain type. #### Values [](#values-1) The 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. #### Object Property options [](#object-property-options) The object property adds the following concepts to the [basic property options](#basic-property-options): Name\[†\]TypeDescription**obj-type**✓*string*The target object's type. In a string format that can be fetched with a `ModelFactory`.**pattern***string*The rendering pattern, used to display the object(s) when necessary.Notes: - \[†\] Indicates options used in validation. ### String Property [](#string-property) #### String Property options [](#string-property-options) The string property adds the following concepts to the basic property options: Name\[†\]TypeDescription**max\_length**✓*integer*Maximum allowed length, in (*multibytes*) characters.**min\_length**✓*integer*Minimum allowed length, in (*multibytes*) characters.**regexp**✓*string*A validation regular expression that must be matched exactly.**allow\_empty**✓*bool*If empty strings are allowed.Notes: - \[†\] Indicates options used in validation. #### String default data [](#string-default-data) By default, the `string` property is targetted at small string (a maximum length) of `255` characters #### Specialized String properties [](#specialized-string-properties) - [`HtmlProperty`](#html-string-property) - [`PasswordProperty`](#password-string-property) - [`PhoneProperty`](#phone-string-property) - [`TextProperty`](#text-string-property) ### Html String Property [](#html-string-property) HTML properties are specialized [string property](#string-property) that may only contain HTML strings (instead of plain string). ### Password String Property [](#password-string-property) Password properties are specialized [string property](#string-property) that holds (encrypted) password data. Encryption is performed with PHP's `password_hash` function. #### Password Property Custom Save [](#password-property-custom-save) Upon `save($val)`, the Password property hashes (or rehashes) the password to be stored safely (encrypted). ### Phone String Property [](#phone-string-property) Phone properties are specialized [string property](#string-property) that holds a phone number. Right now, only "north-american" phone number styles are supported. ### Text String Property [](#text-string-property) Text properties are specialized [string property](#string-property) thay typically holds longer text strings. ### Map Structure Property [](#map-structure-property) Map structure properties hold complex map structure data, which can be points (markers), lines and / or polygons. ### Properties table summary, for developers [](#properties-table-summary-for-developers) NameData typeMultipleCustom SaveCustom ParseAudiomixedBooleanbool**No**Colorstring**Yes**DateTimeDateTime**No****Yes**Filemixed**Yes**HtmlstringIdmixed**No****Yes**ImagemixedIpmixed**No**LangstringMapStructuremixedNumbernumericObjectmixed**Yes**Passwordstring**Yes**PhonestringStringstringStructuremixed**Yes**TextstringUrlstringResources --------- [](#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 Community22 Small or concentrated contributor base Maturity84 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 ~29 days Recently: every ~15 days Total 93 Last Release 795d ago Major Versions 0.11.1.3 → 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.5.0 0.3.2PHP >=5.6.0 0.6.7PHP >=5.6.0 || >=7.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 [![mcaskill](https://avatars.githubusercontent.com/u/29353?v=4)](https://github.com/mcaskill "mcaskill (182 commits)")[![mducharme](https://avatars.githubusercontent.com/u/12157?v=4)](https://github.com/mducharme "mducharme (164 commits)")[![JoelAlphonso](https://avatars.githubusercontent.com/u/10762266?v=4)](https://github.com/JoelAlphonso "JoelAlphonso (21 commits)")[![actions-user](https://avatars.githubusercontent.com/u/65916846?v=4)](https://github.com/actions-user "actions-user (18 commits)")[![BeneRoch](https://avatars.githubusercontent.com/u/3017380?v=4)](https://github.com/BeneRoch "BeneRoch (15 commits)")[![veve40](https://avatars.githubusercontent.com/u/7537381?v=4)](https://github.com/veve40 "veve40 (9 commits)")[![dominiclord](https://avatars.githubusercontent.com/u/1775204?v=4)](https://github.com/dominiclord "dominiclord (8 commits)") --- Tags charcoaljsonmetadatamodelphppropertiesread-only-repositorycharcoal ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/charcoal-property/health.svg) ``` [![Health](https://phpackages.com/badges/charcoal-property/health.svg)](https://phpackages.com/packages/charcoal-property) ``` ### Alternatives [symfony/cache Provides extended PSR-6, PSR-16 (and tags) implementations 4.2k348.9M2.5k](/packages/symfony-cache)[api-platform/metadata API Resource-oriented metadata attributes and factories 223.5M96](/packages/api-platform-metadata)[shopware/core Shopware platform is the core for all Shopware ecommerce products. 595.2M386](/packages/shopware-core)[neos/flow Flow Application Framework 862.0M451](/packages/neos-flow)[locomotivemtl/charcoal-admin The Charcoal Administration Dashboard 1110.8k8](/packages/locomotivemtl-charcoal-admin) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)