README

什么是 Milantex 类型属性类？

此项目提供了一种指定类属性类型的机制。此外，属性类型还有额外的参数，例如字符串的正则表达式模式、整数的最小和最大值等。特殊的设置方法处理类型检查，并且只有当给定的值对于给定的类型及其附加参数有效时，才会设置该值。请参阅文档以获取示例。

安装

使用命令行中的 composer

您可以使用 composer 在项目的源目录中通过以下命令安装该软件包

composer require milantex/tpc

如果需要，请确保更新自动加载器

composer dump-autoload -o

在 composer.json 中将包作为依赖项

请将以下代码添加到您的 composer.json 中。以下是一个包含 milantex/tpc 软件包要求的 composer.json 文件示例

{
    "name": "your-name/your-project",
    "description": "Your project's description",
    "type": "project",
    "license": "MIT",
    "authors": [
        {
            "name": "Your Name",
            "email": "your@mail.tld"
        }
    ],
    "require": {
        "milantex/tpc": "*"
    }
}

请确保运行 composer 命令以安装依赖项

composer install

在项目中使用它

请确保首先要求供应商的自动加载文件。

require_once 'vendor/autoload.php';

之后，为了创建具有类型属性的类，它必须扩展 Milantex\TPC\TypedPropertyClass。

类属性必须标记为受保护的（不是私有的）并且不应将其保留为公共。

要定义类型并添加任何附加类型特定参数，请使用注解注释。

类型类应使用完全限定的路径指定，包括命名空间，并应在 @type 标签中设置。

不同类型提供不同的参数。每个参数都应在注解注释中指定为标签。

要创建设置方法，请使用继承的 setProperty 方法。

查看以下 Student 类的示例，其中包含几个具有不同类型的属性，每个属性指定了附加参数和每个属性的设置方法。

<?php
    namespace Milantex\SampleApp;

    require_once '../../vendor/autoload.php';
    
    use Milantex\TPC\TypedPropertyClass;

    class Student extends TypedPropertyClass {
        /**
         * @type Milantex\TPC\Types\StringType
         * @pattern /^[A-Z][a-z]+(?: [A-Z][a-z]+)*$/
         */
        protected $forename;
        
        /**
         * @type Milantex\TPC\Types\StringType
         * @pattern /^[A-Z][a-z]+(?: [A-Z][a-z]+)*$/
         */
        protected $surname;
        
        /**
         * @type Milantex\TPC\Types\DateType
         * @min 1900-01-01
         */
        protected $birthDay;
        
        /**
         * @type Milantex\TPC\Types\IntType
         * @min 2005000000
         */
        protected $index;
        
        /**
         * @type Milantex\TPC\Types\IntType
         * @min 2005
         */
        protected $yearOfEnrollment;

        public function setForename(string $forename) : Student {
            return $this->setProperty('forename', $forename);
        }

        public function setSurname(string $surname) : Student {
            return $this->setProperty('surname', $surname);
        }

        public function setBirthDay(string $birthDay) : Student {
            return $this->setProperty('birthDay', $birthDay);
        }

        public function setIndex(int $index) : Student {
            return $this->setProperty('index', $index);
        }

        public function setYearOfEnrollment(int $yearOfEnrollment) : Student {
            return $this->setProperty('yearOfEnrollment', $yearOfEnrollment);
        }
    }

现在，在另一个文件中创建此类的实例，并为每个属性尝试设置有效和无效的值。

<?php
    namespace Milantex\SampleApp;

    require_once './Student.php';

    $s = new Student();
    $s->setForename('Milan')
      ->setSurname('Tair')
      ->setBirthDay('1988-03-24')
      ->setYearOfEnrollment(2008)
      ->setIndex(2008213514);

    echo '<pre>' . print_r($s, true) . '</pre>';

输出

<pre>
  Milantex\SampleApp\Student Object
  (
      [forename:protected] => Milan
      [surname:protected] => Tair
      [birthDay:protected] => 1988-03-24
      [index:protected] => 2008213514
      [yearOfEnrollment:protected] => 2008
  )
</pre>

如您所见，有效值（目前都使用适当的设置器设置）被分配给了 $s 对象的属性。

现在，看看当我们尝试将 forename 设置为无效值（不匹配此属性定义的模式）时会发生什么

    # See the definition of the $forename property in the Student class (regex)
    # Since the text above is not a valid forename format, it will not be set
    $s->setForename('Not a valid name');    # This value is not valid

    echo '<pre>' . print_r($s, true) . '</pre>';

输出

<pre>
  Milantex\SampleApp\Student Object
  (
      [forename:protected] => Milan
      [surname:protected] => Tair
      [birthDay:protected] => 1988-03-24
      [index:protected] => 2008213514
      [yearOfEnrollment:protected] => 2008
  )
</pre>

请注意，forename 没有 变为 "Not a valid name"。相反，它保持为 "Milan"，这是分配给此属性的最新有效值。

现在，一些值将是有效的，一些则不是（索引和入学年份）。原始值将保持不变。

    # Almost all data that follow is valid (forename, surname and birthday),
    # but the year and the index are not. These will not be set to new values.
    $s->setForename('Pera')
      ->setSurname('Peric')
      ->setBirthDay('1991-04-30')
      ->setYearOfEnrollment(208)   # This value is not valid
      ->setIndex(2083321);         # This value is not valid

    echo '<pre>' . print_r($s, true) . '</pre>';

输出

<pre>
  Milantex\SampleApp\Student Object
  (
      [forename:protected] => Pera
      [surname:protected] => Peric
      [birthDay:protected] => 1991-04-30
      [index:protected] => 2008213514
      [yearOfEnrollment:protected] => 2008
  )
</pre>

最后，DateType 类不仅检查日期的格式，还检查日期是否有效。请看下面的示例

    # Tthis time the date will not be set, because it is impossible (May 31st).
    $s->setBirthDay('1991-04-31');   # There is no April 31st in the calendar

    echo '<pre>' . print_r($s, true) . '</pre>';

输出

<pre>
  Milantex\SampleApp\Student Object
  (
      [forename:protected] => Pera
      [surname:protected] => Peric
      [birthDay:protected] => 1991-04-30
      [index:protected] => 2008213514
      [yearOfEnrollment:protected] => 2008
  )
</pre>

如您所见，之前的有效日期（4月30日）保持不变，因为预期日期不是一个有效的日期，尽管它格式正确。

支持类型

目前，在 Milantex\TPC\Types 命名空间中只有四个类型类。这些是

Milantex\TPC\Types\DateType

DateType 类型类用于日期类型的属性。所需的格式是 YYYY-MM-DD。

参数

@min

此参数用于指定可以设置此属性的最小日期。如果没有定义，最小日期是 0000-00-00 00:00:00。

@max

此参数用于指定可以为该属性设置的最大的日期。如果没有定义，最大的日期为9999-12-31 23:59:59。

Milantex\TPC\Types\StringType

StringType 类型类用于字符串类型的属性。其主要特点是能够使用正则表达式定义值验证。

参数

@pattern

此参数用于指定用于匹配该属性预期值的正则表达式。如果没有定义，默认模式为 /^.$/。模式定义时无需引号，就像在 preg_ 函数中一样。

Milantex\TPC\Types\IntType

IntType 类型类用于整数类型（或长整型）的属性。

参数

@min

此参数用于指定可以为该属性设置的最小值。如果没有定义，最小值为 \PHP_INT_MIN。

@max

此参数用于指定可以为该属性设置的最大值。如果没有定义，最大值为 \PHP_INT_MAX。

Milantex\TPC\Types\FloatType

FloatType 类型类用于浮点类型（或双精度浮点型）的属性。

参数

@min

此参数用于指定可以为该属性设置的最小值。如果没有定义，最小值为 \PHP_FLOAT_MIN。

@max

此参数用于指定可以为该属性设置的最大值。如果没有定义，最大值为 \PHP_FLOAT_MAX。

创建自定义类型

您可以创建自定义类型类。类型类必须实现 Milantex\TPC\TypeInterface。

查看 FloatType 类型类的代码，了解如何创建自己的自定义类型类。

<?php
    namespace Milantex\TPC\Types;
    
    use Milantex\TPC\TypeInterface;

    class FloatType implements TypeInterface {
        private $min = \PHP_INT_MIN; # PHP_FLOAT_MIN will be available 7.2+
        private $max = \PHP_INT_MAX; # PHP_FLOAT_MAX will be available 7.2+

        public function __construct(\stdClass $tags) {
            if (\property_exists($tags, 'min') && \is_double($tags->min)) {
                $this->min = $tags->min;
            }

            if (\property_exists($tags, 'max') && \is_double($tags->max)) {
                $this->max = $tags->max;
            }
        }

        public function isValid($value) : bool {
            if (!\is_double($value)) {
                return false;
            }

            return $this->min <= $value && $value <= $this->max;
        }
    }