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

The preferred (and only suppported) way of installing charcoal-property is with composer:

★ composer require charcoal/property

For a complete, ready-to-use project, start from the boilerplate:

★ composer create-project charcoal/project-boilerplate:@dev --prefer-source

Dependencies

• PHP 5.6+
  • PHP 7 is recommended for security & performance reasons.
• psr/log
  • A PSR-3 compliant logger should be provided to the various services / classes.
• charcoal/config
  • Properties configuration and metadata.
• charcoal/core
  • Also required for validator, model and more.
• charcoal/factory
  • Dynamic object creation is provided with charcoal factories.
• charcoal/image
  • For image manipulation.
• charcoal/translator
  • For localization.

Property options

The basic property interface (API) requires / provides the following members:

(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

• 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

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

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

• Boolean
• Color
• Date
  • DateTime
  • Day
  • Month
  • Time
  • Year
• File
  • Audio
  • Image
  • Video
• Lang
• Number
  • Float
  • Integer
• Object
• Id
• IP
• String
  • Html
  • Password
  • Phone
  • Text
• Structure
  • MapStructure
  • ModelStructure

Retrieve

Boolean Property

The boolean property is one of the simplest possible: it simply holds boolean (true / false) values.

Boolean Property options

The boolean property adds the following concepts to the basic property options:

(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

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

The boolean property adds the following concepts to the basic property options:

(V) indicates options used in validation

DateTime Property

The datetime property store a date (and time) value.

DateTime Property options

The datetime property adds the following concepts to the basic property options:

(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

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

The ID property adds the following concepts to the basic property options:

⚠ 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

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

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 holds an uploadable file.

Values

Note that only a relative¹ file path should be stored in the database.

¹ Relative to project's ROOT + the property's upload_path.

File Property options

The file property adds the following concepts to the basic property options:

(V) indicates options used in validation

Additional file methods

• mimetype() and setMimetype()
• filesize() and setFilesize()
• dataUpload()
• fileUpload()

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

• AudioProperty
• ImageProperty
• VideoProperty

Audio File Property

Audio property are specialized file property thay may only contain audio data.

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

The audio property adds the following concepts to the file property options:

(V) indicates options used in validation

Image File Property

Image property are specialized file property thay may only contain image data.

Accepted mimetypes

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

The audio property adds the following concepts to the file property options:

(V) indicates options used in validation

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 properties hold any kind of numeric data.

Object Property

Object properties hold a reference to an external object of a certain type.

Values

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

The object property adds the following concepts to the basic property options:

String Property

String Property options

The string property adds the following concepts to the basic property options:

String default data

By default, the string property is targetted at small string (a maximum length) of 255 characters

Specialized String properties

• HtmlProperty
• PasswordProperty
• PhoneProperty
• TextProperty

Html String Property

HTML properties are specialized string property that may only contain HTML strings (instead of plain string).

Password String Property

Password properties are specialized string property that holds (encrypted) password data.

Encryption is performed with PHP's password_hash function.

Password Property Custom Save

Upon save($val), the Password property hashes (or rehashes) the password to be stored safely (encrypted).

Phone String Property

Phone properties are specialized string property that holds a phone number.

Right now, only "north-american" phone number styles are supported.

Text String Property

Text properties are specialized string property thay typically holds longer text strings.

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

Development

To install the development environment:

★ composer install --prefer-source

Run the code checkers and unit tests with:

★ composer test

API documentation

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

Development dependencies

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

Continuous Integration

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

Coding Style

The Charcoal-Property module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• Read the phpcs.xml.dist 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

• Mathieu Ducharme [email protected]
• Chauncey McAskill [email protected]
• Benjamin Roch [email protected]
• Dominic Lord [email protected]
• Joel Alphonso [email protected]

License

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

Report Issues

In case you are experiencing a bug or want to request a new feature head over to the Charcoal monorepo issue tracker

Contribute

The sources of this package are contained in the Charcoal monorepo. We welcome contributions for this package on charcoalphp/charcoal.