locomotivemtl/charcoal-property

Charcoal Property定义了一个对象（提供元数据）

维护者

详细信息

github.com/locomotivemtl/charcoal-property

主页

源代码

问题

安装数: 22,582

依赖者: 5

建议者: 0

安全: 0

星标: 0

关注者: 13

分支: 0

开放问题: 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-08-28 23:51:02 UTC

README

属性定义了对象的元数据。它们提供了模型定义的构建块。

属性在其metadata中全局定义对象（charcoal模型）。它们提供属性定义、存储定义和验证定义。

在\Charcoal\Model\DescribableInterface中定义了metadata()方法。在\Charcoal\Property\DescribablePropertyInterface中定义了properties()方法。

如何安装

安装charcoal-property的首选（也是唯一支持的）方式是使用composer

★ composer require locomotivemtl/charcoal-property

对于完整、现成的项目，从样板开始

★ composer create-project locomotivemtl/charcoal-project-boilerplate:@dev --prefer-source

依赖

属性选项

基本属性接口（API）需要/提供以下成员

(V)表示用于验证的选项

所有这些方法都可以通过setData()方法或标准PSR-1/PSR-2的getter/setter访问。（foo将具有foo()作为getter和setFoo()作为setter）。

数据检索

  • 要获取一个规范值，请使用parseVal($val)方法。
  • 要获取一个字符串安全的、可显示的值，请使用displayVal($val)。
  • 要获取存储格式的值，请使用storageVal($val)。

可以在每个属性中进一步定义自定义数据检索方法。（例如，格式化的日期或自定义颜色格式）。

默认验证

验证通过来自charcoal-core的Validator对象提供。

  • required
  • unique
  • allow_null

验证正在通过新的charcoal-validator包进行重建。

源和存储方法

属性需要4个方法才能与SQL源集成

  • sqlEncoding() 字符串 SQL列编码和校对（例如：utf8mb4）
  • sqlExtra() 字符串 将附加的原始SQL字符串
  • sqlType() 字符串 SQL列类型（例如：VARCHAR(16)）
  • sqlPdoType() 整数 PDO列类型（例如：PDO::PARAM_STR）

这些方法是抽象的，因此必须在实际属性中实现。

属性类型

检索

布尔属性

布尔属性是最简单的一种：它仅保留布尔值（true / false）。

布尔属性选项

布尔属性将以下概念添加到基本属性选项

(V)表示用于验证的选项

⚠ 布尔属性不能是多个。(multiple() 总是返回 false)。在布尔属性上调用 setMultiple(true) 将抛出异常。

颜色属性

颜色属性存储颜色。如果不支持 alpha，则存储为十六进制值（例如：#5590BA）。如果支持 alpha，则存储为 rgba() 字符串值（例如：rgb(85, 144, 186, 0.5)）。

颜色属性选项

布尔属性将以下概念添加到基本属性选项

(V)表示用于验证的选项

日期时间属性

日期时间属性存储日期和时间值。

日期时间属性选项

日期时间属性将以下概念添加到基本属性选项

(V)表示用于验证的选项

⚠ 日期时间属性不能是多个。(multiple() 总是返回 false)。在日期时间属性上调用 setMultiple(true) 将抛出异常。

ID 属性

ID 属性持有 ID，通常是主要对象标识符（唯一索引键）。

ID 值可以由许多 模式 生成

  • auto-increment 是默认模式。它使用存储引擎（mysql）的自动递增功能来保持自动递增的整数索引。
  • uniqid 使用 PHP 的 uniqid() 函数创建一个 13 个字符的字符串。
  • uuid 创建一个 36 个字符的字符串（一个 RFC-4122 v4 全局唯一标识符，uuidv4）。

ID 属性选项

ID 属性将以下概念添加到基本属性选项

⚠ ID 属性不能是多个。(multiple() 总是返回 false)。在 ID 属性上调用 setMultiple(true) 将抛出异常。

ID 属性自定义保存

在 save($val) 上，如果其模式是 uniqid 或 uuid，ID 属性将自动生成 ID。

注意：auto-increment 模式在保存时不会执行任何操作；它依赖于存储引擎/驱动程序来实现自动递增。

IP 属性

IP 属性持有 IP 地址。目前仅支持 IPv4 地址。

IP 有两种不同的存储模式

  • string 是默认模式。它将 IP 地址存储为 192.168.1.1。
  • int 将 IP 存储为 有符号长整数。

⚠ IP 属性不能是多个。(multiple() 总是返回 false)。在 IP 属性上调用 setMultiple(true) 将抛出异常。

文件属性

文件属性持有可上传的文件。

值

请注意，数据库中应仅存储 相对1 文件路径。

1 相对于项目的 ROOT + 属性的 upload_path。

文件属性选项

文件属性将以下概念添加到基本属性选项

(V)表示用于验证的选项

额外的文件方法

  • mimetype() 和 setMimetype()
  • filesize() 和 setFilesize()
  • dataUpload()
  • fileUpload()

文件属性自定义保存

在 save($val) 上，如果需要，文件属性将尝试上传文件或从数据创建文件。返回上传文件的路径（相对）。

专用文件属性

音频文件属性

音频属性是专门的 文件属性，可能仅包含音频数据。

接受的 MIME 类型

AudioProperty 扩展 FileProperty 因此提供了 "接受的 MIME 类型"。

默认接受的 MIME 类型是

  • audio/mp3
  • 音频/mpeg
  • 音频/wav
  • 音频/x-wav.

音频文件属性选项

音频属性向文件属性选项中添加以下概念：

(V)表示用于验证的选项

图像文件属性

图像属性是专门的文件属性，可能只包含图像数据。

接受的 MIME 类型

ImageProperty 扩展了 FileProperty，因此提供了“接受的MIME类型”。

默认接受的 MIME 类型是

  • image/gif
  • image/jpg
  • image/jpeg
  • image/pjpeg
  • image/png
  • image/svg+xml
  • image/webp

图像文件属性选项

音频属性向文件属性选项中添加以下概念：

(V)表示用于验证的选项

语言属性

语言属性包含一个语言值。

LangProperty 实现了 SelectablePropertyInterface，但其 choices() 方法被硬编码为返回活动语言（来自 [charcoal-translator](https://github.com/locomotivemtl/charcoal-translator)）。

数字属性

数字属性包含任何类型的数值数据。

对象属性

对象属性包含对特定类型外部对象的引用。

值

目标对象的 identifier（由其 obj-type 的 key 确定，通常是 "id"）是唯一存储在值/数据库中的内容。当显示时（使用 displayVal()），应渲染对象的字符串表示形式。

对象属性选项

对象属性向以下基本属性选项添加以下概念：

字符串属性

字符串属性选项

字符串属性向基本属性选项添加以下概念：

字符串默认数据

默认情况下，string 属性针对的是长度为 255 的短字符串（最大长度）。

专门的字符串属性

HTML字符串属性

HTML属性是专门的字符串属性，可能只包含HTML字符串（而不是纯字符串）。

密码字符串属性

密码属性是专门的字符串属性，包含（加密）密码数据。

加密使用PHP的 password_hash 函数执行。

密码属性自定义保存

在 save($val) 时，密码属性会哈希（或重新哈希）要存储的密码以安全（加密）地存储。

电话字符串属性

电话属性是专门的字符串属性，包含电话号码。

目前，仅支持“北美”电话号码格式。

文本字符串属性

文本属性是专门的字符串属性，通常包含较长的文本字符串。

地图结构属性

地图结构属性包含复杂的地图结构数据，可以是点（标记）、线以及/或多边形。

属性表摘要，针对开发者

开发

要安装开发环境

★ composer install --prefer-source

使用以下命令运行代码检查器和单元测试：

★ composer test

API文档

开发依赖

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

持续集成

编码风格

Charcoal-Property模块遵循Charcoal编码风格

可以使用 composer phpcs 执行代码风格验证/强制执行。同时，还提供了自动修复工具 composer phpcbf。

作者

许可证

Charcoal 在 MIT 许可证下发布。有关详细信息，请参阅 LICENSE。