locomotivemtl / charcoal-property
Charcoal Property defines an object (provides metadata)
Installs: 22 638
Dependents: 5
Suggesters: 0
Security: 0
Stars: 0
Watchers: 13
Forks: 0
Open Issues: 2
Requires
- php: >=5.6.0 || >=7.0
- ext-fileinfo: *
- ext-pdo: *
- ext-simplexml: *
- locomotivemtl/charcoal-config: ~0.9
- locomotivemtl/charcoal-core: ~0.6
- locomotivemtl/charcoal-factory: ~0.4
- locomotivemtl/charcoal-image: ~0.4
- locomotivemtl/charcoal-translator: ~0.3
- psr/cache: ^1.0
- psr/log: ^1.0
Requires (Dev)
- cache/void-adapter: ^0.3.0
- mustache/mustache: ^2.11
- php-coveralls/php-coveralls: ^2.0
- phpunit/phpunit: ^5.7 || ^6.5
- pimple/pimple: ^3.0
- squizlabs/php_codesniffer: ^3.0
- tedivm/stash: ~0.14
- dev-master / 0.11.x-dev
- 0.11.1.4
- 0.11.1.3
- 0.11.1.2
- 0.11.1.1
- 0.11.1
- 0.11.0.1
- 0.11.0
- 0.10.5
- 0.10.4.2
- 0.10.4.1
- 0.10.4
- 0.10.3
- 0.10.2
- 0.10.1
- 0.10.0
- 0.9.0
- 0.8.4
- 0.8.3
- 0.8.2
- 0.8.1
- 0.8.0
- 0.7.x-dev
- 0.7.4.3
- 0.7.4.2
- 0.7.4.1
- 0.7.4.0
- 0.7.3.1
- 0.7.3
- 0.7.2
- 0.7.1.1
- 0.7.1
- 0.7.0.5
- 0.7.0.4
- 0.7.0.3
- 0.7.0.2
- 0.7.0.1
- 0.7.0
- 0.6.7
- 0.6.6.2
- 0.6.6.1
- 0.6.6
- 0.6.5
- 0.6.4
- 0.6.3
- 0.6.2
- 0.6.1
- 0.6
- 0.5.3
- 0.5.2
- 0.5.1.1
- 0.5.1
- 0.5.0.3
- 0.5.0.2
- 0.5.0.1
- 0.5
- 0.4.6
- 0.4.5.1
- 0.4.5
- 0.4.4
- 0.4.3.1
- 0.4.3
- 0.4.2
- 0.4.1
- 0.4
- 0.3.3
- 0.3.2
- 0.3.1
- 0.3
- 0.2
- 0.1
- dev-dev/joel/image-compression
- dev-joel/feat/query
- dev-mducharme-camelcase
- dev-mcaskill-callable-choices
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
. Theproperties()
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:
(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 havefoo()
as a getter andsetFoo()
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 tosqlType()
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
DayMonthTimeYear
- File
- Lang
- Number
FloatInteger
- Object
- Id
- IP
- String
Structure
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). CallingsetMultiple(true)
on aboolean
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). CallingsetMultiple(true)
on adate-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'suniqid()
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). CallingsetMultiple(true)
on anid
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 like192.168.1.1
.int
stores the IP as a signed long integer.
⚠ Ip properties can not be multiple. (
multiple()
will always return false). CallingsetMultiple(true)
on anip
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()
andsetMimetype()
filesize()
andsetFilesize()
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 theSelectablePropertyInterface
, but hardcode itschoices()
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
- 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
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 withcomposer 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.