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 locomotivemtl/charcoal-property

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

★ composer create-project locomotivemtl/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.
• locomotivemtl/charcoal-config
  • Properties configuration and metadata.
• locomotivemtl/charcoal-core
  • Also required for validator, model and more.
• locomotivemtl/charcoal-factory
  • Dynamic object creation is provided with charcoal factories.
• locomotivemtl/charcoal-image
  • For image manipulation.
• locomotivemtl/charcoal-translator
  • For localization.

Property options

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

Name	(V)	Type	Description
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

• 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:

Name	(V)	Type	Description
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

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:

Name	(V)	Type	Description
support_alpha	✓	boolean	...

(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:

Name	(V)	Type	Description
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

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:

Name	(V)	Type	Description
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

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:

Name	(V)	Type	Description
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

• 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:

Name	(V)	Type	Description
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 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:

Name	(V)	Type	Description
effects	✓	array	Array of charcoal-image effects 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:

Name	(V)	Type	Description
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 validation

String Property

String Property options

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

Name	(V)	Type	Description
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

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

Name	Data type	Multiple	Custom Save	Custom Parse
Audio	mixed
Boolean	bool	No
Color	string			Yes
DateTime	DateTime	No		Yes
File	mixed		Yes
Html	string
Id	mixed	No	Yes
Image	mixed
Ip	mixed	No
Lang	string
MapStructure	mixed
Number	numeric
Object	mixed			Yes
Password	string		Yes
Phone	string
String	string
Structure	mixed			Yes
Text	string
Url	string

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
• satooshi/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 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 mat@locomotive.ca
• Chauncey McAskill chauncey@locomotive.ca
• Benjamin Roch benjamin@locomotive.ca
• Dominic Lord dom@locomotive.ca
• Joel Alphonso joel@locomotive.ca

License

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