https://github.com/locomotivemtl/charcoal-property
Properties define model metadata.
https://github.com/locomotivemtl/charcoal-property
charcoal json metadata model php properties
Last synced: 5 months ago
JSON representation
Properties define model metadata.
- Host: GitHub
- URL: https://github.com/locomotivemtl/charcoal-property
- Owner: locomotivemtl
- License: mit
- Created: 2016-01-20T19:34:45.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2023-09-28T21:37:38.000Z (almost 3 years ago)
- Last Synced: 2025-10-03T12:54:46.810Z (9 months ago)
- Topics: charcoal, json, metadata, model, php, properties
- Language: PHP
- Homepage:
- Size: 9.32 MB
- Stars: 0
- Watchers: 12
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
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**:
```shell
★ composer require locomotivemtl/charcoal-property
```
For a complete, ready-to-use project, start from the [`boilerplate`](https://github.com/locomotivemtl/charcoal-project-boilerplate):
```shell
★ composer create-project locomotivemtl/charcoal-project-boilerplate:@dev --prefer-source
```
## Dependencies
- [`PHP 5.6+`](http:///php.net)
- PHP 7 is recommended for security & performance reasons.
- [`psr/log`](http://www.php-fig.org/psr/psr-3/)
- A PSR-3 compliant logger should be provided to the various services / classes.
- [`locomotivemtl/charcoal-config`](https://github.com/locomotivemtl/charcoal-config)
- Properties configuration and metadata.
- [`locomotivemtl/charcoal-core`](https://github.com/locomotivemtl/charcoal-core)
- Also required for validator, model and more.
- [`locomotivemtl/charcoal-factory`](https://github.com/locomotivemtl/charcoal-fatory)
- Dynamic object creation is provided with charcoal factories.
- [`locomotivemtl/charcoal-image`](https://github.com/locomotivemtl/charcoal-image)
- For image manipulation.
- [`locomotivemtl/charcoal-translator`](https://github.com/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](#boolean-property)
- [Color](#color-property)
- ~~Date~~
- [DateTime](#datetime-property)
- ~~Day~~
- ~~Month~~
- ~~Time~~
- ~~Year~~
- [File](#file-property)
- [Audio](#file-audio-property)
- [Image](#image-property)
- ~~Video~~
- [Lang](#lang-property)
- [Number](#number-property)
- ~~Float~~
- ~~Integer~~
- [Object](#object-property)
- [Id](#id-property)
- [IP](#ip-property)
- [String](#string-property)
- [Html](#html-string-property)
- [Password](#password-string-property)
- [Phone](#phone-string-property)
- [Text](#text-string-propery)
- ~~Structure~~
- [MapStructure](#map-structure-property)
- [ModelStructure](#model-structure-property)
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](#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](#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](#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](#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_1 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](#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`](#audio-file-property)
- [`ImageProperty`](#image-file-property)
- ~~VideoProperty~~
## Audio File Property
Audio property are specialized [file property](#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](#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](#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](#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](#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`](#html-string-property)
- [`PasswordProperty`](#password-string-property)
- [`PhoneProperty`](#phone-string-property)
- [`TextProperty`](#text-string-property)
## Html String Property
HTML properties are specialized [string property](#string-property) that may only contain HTML strings (instead of plain string).
## Password String Property
Password properties are specialized [string property](#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](#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](#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:
```shell
★ composer install --prefer-source
```
Run the code checkers and unit tests with:
```shell
★ composer test
```
## API documentation
- The auto-generated `phpDocumentor` API documentation is available at [https://locomotivemtl.github.io/charcoal-property/docs/master/](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/](https://locomotivemtl.github.io/charcoal-property/apigen/master/)
## Development dependencies
- `phpunit/phpunit`
- `squizlabs/php_codesniffer`
- `satooshi/php-coveralls`
## Continuous Integration
| Service | Badge | Description |
| ------- | ----- | ----------- |
| [Travis](https://travis-ci.org/locomotivemtl/charcoal-property) | [](https://travis-ci.org/locomotivemtl/charcoal-property) | Runs code sniff check and unit tests. Auto-generates API documentaation. |
| [Scrutinizer](https://scrutinizer-ci.com/g/locomotivemtl/charcoal-property/) | [](https://scrutinizer-ci.com/g/locomotivemtl/charcoal-property/?branch=master) | Code quality checker. Also validates API documentation quality. |
| [Coveralls](https://coveralls.io/github/locomotivemtl/charcoal-property) | [](https://coveralls.io/github/locomotivemtl/charcoal-property?branch=master) | Unit Tests code coverage. |
| [Sensiolabs](https://insight.sensiolabs.com/projects/f3bdff38-c300-4207-8342-da002e64a6e1) | [](https://insight.sensiolabs.com/projects/f3bdff38-c300-4207-8342-da002e64a6e1) | Another code quality checker, focused on PHP. |
## Coding Style
The Charcoal-Property module follows the Charcoal coding-style:
- [_PSR-1_](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-1-basic-coding-standard.md)
- [_PSR-2_](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
- [_PSR-4_](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-4-autoloader.md), autoloading is therefore provided by _Composer_.
- [_phpDocumentor_](http://phpdoc.org/) comments.
- Read the [phpcs.xml](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
- Chauncey McAskill
- Benjamin Roch
- Dominic Lord
- Joel Alphonso
# License
Charcoal is licensed under the MIT license. See [LICENSE](LICENSE) for details.