Skip to content

Latest commit

 

History

History
468 lines (310 loc) · 19.8 KB

README.md

File metadata and controls

468 lines (310 loc) · 19.8 KB
Raw

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

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

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 relative1 file path should be stored in the database.

1 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

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

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

Development dependencies

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

Continuous Integration

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

Coding Style

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

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Authors

License

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