locomotivemtl/charcoal-property

Charcoal Property defines an object (provides metadata)

Maintainers

Details

github.com/locomotivemtl/charcoal-property

Homepage

Source

Issues

Installs: 22 629

Dependents: 5

Suggesters: 0

Security: 0

Stars: 0

Watchers: 13

Forks: 0

Open Issues: 2

0.11.1.4 2023-09-28 21:35 UTC

Requires

Requires (Dev)

MIT 5df2d23b72f60f96faf8e2e45a85e19848c6d3c4

  • Mathieu Ducharme <mat.woop@locomotive.ca>
  • Locomotive

charcoal

This package is auto-updated.

Last update: 2024-10-29 00:12:51 UTC

README

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:

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

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

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

(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

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

Development dependencies

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

Continuous Integration

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.