PHPackages locomotivemtl/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. [Utility & Helpers](/categories/utility) 4. / 5. locomotivemtl/charcoal-property ActiveLibrary[Utility & Helpers](/categories/utility) locomotivemtl/charcoal-property =============================== Charcoal Property defines an object (provides metadata) 0.11.1.4(2y ago)023.0k[2 PRs](https://github.com/locomotivemtl/charcoal-property/pulls)4MITPHPPHP >=5.6.0 || >=7.0CI failing Since Sep 14Pushed 2y ago11 watchersCompare [ Source](https://github.com/locomotivemtl/charcoal-property)[ Packagist](https://packagist.org/packages/locomotivemtl/charcoal-property)[ Docs](https://charcoal.locomotive.ca)[ RSS](/packages/locomotivemtl-charcoal-property/feed)WikiDiscussions master Synced 2mo ago READMEChangelog (10)Dependencies (14)Versions (75)Used By (4) Charcoal Property ================= [](#charcoal-property) Properties define object's metadata. They provide the building blocks of the Model's definition. 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`. How to install ============== [](#how-to-install) The preferred (and only suppported) way of installing *charcoal-property* is with **composer**: ``` ★ composer require locomotivemtl/charcoal-property ``` For a complete, ready-to-use project, start from the [`boilerplate`](https://github.com/locomotivemtl/charcoal-project-boilerplate): ``` ★ composer create-project locomotivemtl/charcoal-project-boilerplate:@dev --prefer-source ``` Dependencies ------------ [](#dependencies) - [`PHP 5.6+`](http:///php.net) - PHP 7 is recommended for security & performance reasons. - [`psr/log`](http://www.php-fig.org/psr/psr-3/) - A PSR-3 compliant logger should be provided to the various services / classes. - [`locomotivemtl/charcoal-config`](https://github.com/locomotivemtl/charcoal-config) - Properties configuration and metadata. - [`locomotivemtl/charcoal-core`](https://github.com/locomotivemtl/charcoal-core) - Also required for validator, model and more. - [`locomotivemtl/charcoal-factory`](https://github.com/locomotivemtl/charcoal-fatory) - Dynamic object creation is provided with charcoal factories. - [`locomotivemtl/charcoal-image`](https://github.com/locomotivemtl/charcoal-image) - For image manipulation. - [`locomotivemtl/charcoal-translator`](https://github.com/locomotivemtl/charcoal-translator) - For localization. Property options ================ [](#property-options) The basic property interface (API) requires / provides the following members: Name(V)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*(V) 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. - `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(V)TypeDescription**false\_label**-*Translation*Label, for "true" value.**true\_label**-*Translation*Label, for "false" value.(V) 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(V)TypeDescription**support\_alpha**✓*boolean*...(V) 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(V)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".(V) 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(V)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(V)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.(V) 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(V)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.(V) 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(V)TypeDescription**effects**✓*array*Array of `charcoal-image` effects options.(V) 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/locomotivemtl/charcoal-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(V)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.(V) indicates options used in validationString Property --------------- [](#string-property) ### String Property options [](#string-property-options) The string property adds the following concepts to the basic property options: Name(V)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.(V) 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**TextstringUrlstringDevelopment =========== [](#development) To install the development environment: ``` ★ composer install --prefer-source ``` Run the code checkers and unit tests with: ``` ★ composer test ``` API documentation ----------------- [](#api-documentation) - The auto-generated `phpDocumentor` API documentation is available at - The auto-generated `apigen` API documentation is available at Development dependencies ------------------------ [](#development-dependencies) - `phpunit/phpunit` - `squizlabs/php_codesniffer` - `satooshi/php-coveralls` Continuous Integration ---------------------- [](#continuous-integration) ServiceBadgeDescription[Travis](https://travis-ci.org/locomotivemtl/charcoal-property)[![Build Status](https://camo.githubusercontent.com/3e52417abbc6f41c1eba8ea30e35e2fd7a8fd1185a73ab75d0abd189bfd6e038/68747470733a2f2f7472617669732d63692e6f72672f6c6f636f6d6f746976656d746c2f63686172636f616c2d70726f70657274792e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/locomotivemtl/charcoal-property)Runs code sniff check and unit tests. Auto-generates API documentaation.[Scrutinizer](https://scrutinizer-ci.com/g/locomotivemtl/charcoal-property/)[![Scrutinizer Code Quality](https://camo.githubusercontent.com/52478e12f5d06cf09d44046936e64c3aafc082dd9b2e5263580120639bd33d9b/68747470733a2f2f7363727574696e697a65722d63692e636f6d2f672f6c6f636f6d6f746976656d746c2f63686172636f616c2d70726f70657274792f6261646765732f7175616c6974792d73636f72652e706e673f623d6d6173746572)](https://scrutinizer-ci.com/g/locomotivemtl/charcoal-property/?branch=master)Code quality checker. Also validates API documentation quality.[Coveralls](https://coveralls.io/github/locomotivemtl/charcoal-property)[![Coverage Status](https://camo.githubusercontent.com/bffcc7c2c35fbe2482ed7bfdf4bfa39c72e43018ba1cba65dcf988d0868d67bc/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6769746875622f6c6f636f6d6f746976656d746c2f63686172636f616c2d70726f70657274792f62616467652e7376673f6272616e63683d6d6173746572)](https://coveralls.io/github/locomotivemtl/charcoal-property?branch=master)Unit Tests code coverage.[Sensiolabs](https://insight.sensiolabs.com/projects/f3bdff38-c300-4207-8342-da002e64a6e1)[![SensioLabsInsight](https://camo.githubusercontent.com/6ec8a0a860d97acce1d452703997cf81ab2eb2e5183a34f0235ec67d45fe3fa2/68747470733a2f2f696e73696768742e73656e73696f6c6162732e636f6d2f70726f6a656374732f66336264666633382d633330302d343230372d383334322d6461303032653634613665312f6d696e692e706e67)](https://insight.sensiolabs.com/projects/f3bdff38-c300-4207-8342-da002e64a6e1)Another code quality checker, focused on PHP.Coding Style ------------ [](#coding-style) The Charcoal-Property module follows the Charcoal coding-style: - [*PSR-1*](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md) - [*PSR-2*](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md) - [*PSR-4*](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md), autoloading is therefore provided by *Composer*. - [*phpDocumentor*](http://phpdoc.org/) comments. - Read the [phpcs.xml](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`. Authors ------- [](#authors) - Mathieu Ducharme - Chauncey McAskill - Benjamin Roch - Dominic Lord - Joel Alphonso License ======= [](#license) Charcoal is licensed under the MIT license. See [LICENSE](LICENSE) for details. ### Health Score 34 — LowBetter than 77% of packages Maintenance20 Infrequent updates — may be unmaintained Popularity22 Limited adoption so far Community23 Small or concentrated contributor base Maturity63 Established project with proven stability 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 ~37 days Recently: every ~261 days Total 70 Last Release 963d ago PHP version history (3 changes)0.1PHP >=5.5.0 0.3.2PHP >=5.6.0 0.6.7PHP >=5.6.0 || >=7.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) --- Top Contributors [![mcaskill](https://avatars.githubusercontent.com/u/29353?v=4)](https://github.com/mcaskill "mcaskill (183 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)")[![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 charcoaljsonmetadatamodelphppropertiescharcoal ### Code Quality TestsPHPUnit Code StylePHP\_CodeSniffer ### Embed Badge ![Health badge](/badges/locomotivemtl-charcoal-property/health.svg) ``` [![Health](https://phpackages.com/badges/locomotivemtl-charcoal-property/health.svg)](https://phpackages.com/packages/locomotivemtl-charcoal-property) ``` ### Alternatives [api-platform/metadata API Resource-oriented metadata attributes and factories 243.5M96](/packages/api-platform-metadata)[locomotivemtl/charcoal-app Charcoal application, based on Slim 3 1320.3k12](/packages/locomotivemtl-charcoal-app)[locomotivemtl/charcoal-cms Charcoal CMS (Content Management System) Module 529.0k3](/packages/locomotivemtl-charcoal-cms)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 245.2k](/packages/aedart-athenaeum)[locomotivemtl/charcoal-admin The Charcoal Administration Dashboard 1110.8k8](/packages/locomotivemtl-charcoal-admin) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)