README

Period Bundle

Symfony Bundle - AndanteProject

将 thephpleague/period 集成到 Doctrine 和 Symfony Form 的Symfony Bundle。

要求

Symfony 5.4-6.x 和 PHP 8.0。

安装

通过 Composer

$ composer require andanteproject/period-bundle

特性

• 在您的数据库中持久化 Period、Duration 和 Sequence；
• 轻松持久化 Period 作为 JSON 字段或 doctrine embeddable object（并且允许它为 null!!）。
• Doctrine DQL 函数。
• 使用 Period 在 Symfony 表单中的表单类型；
• 如魔法般使用 ✨。

基本用法

在 安装 之后，请确保您已将此包注册到您的 symfony 包列表中（config/bundles.php）

return [
    /// bundles...
    Andante\PeriodBundle\AndantePeriodBundle::class => ['all' => true],
    /// bundles...
];

如果您使用的是 Symfony Flex，则此操作将自动完成。否则，请自行注册。

Doctrine 映射

此包将注册 period、duration 和 sequence doctrine 类型，以便您可以将 Period、Duration 和 Sequence 对象映射到数据库。

<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use League\Period\Duration;
use League\Period\Period;
use League\Period\Sequence;

/**
 * @ORM\Entity()
 */
class Meeting
{
    /**
     * @ORM\Column(type="period", nullable=true)
     */
    private ?Period $period = null;
    
    /**
     * @ORM\Column(type="duration", nullable=true)
     */
    private ?Duration $duration = null;
    
    /**
     * @ORM\Column(type="sequence", nullable=true)
     */
    private ?Sequence $sequence = null;
}

这些类型将在您的数据库中创建一个 JSON 字段。如果您想为 Period 创建一个具有 startDate 和 endDate 的单独列，请检查下面的 Embeddable 映射。

Embeddable Period 映射

<?php

namespace App\Entity;

use Doctrine\ORM\Mapping as ORM;
use League\Period\Period;

/**
 * @ORM\Entity()
 */
class Meeting
{
    /**
     * @ORM\Embedded(class="League\Period\Period", columnPrefix="period_")
     */
    private ?Period $period = null;
}

这将创建数据库中的 3 个不同列，如 period_start_date、period_end_date 和 period_boundary_type 而不是 JSON 字段。如果您想为映射使用不同的名称，请检查此包的 配置。⚠️ 请注意：Doctrine v2 不允许嵌入式类为 null。这是 Doctrine v3 预期的一项功能。但是，通过一些内置的魔法，此包允许您使用 null Period。👍

Doctrine DQL 函数

无论您为 Period 使用哪种映射（类型 或 嵌入式），您都可以使用这些 DQL 函数来访问 Period 属性

• PERIOD_START_DATE() 以访问 period.startDate，例如 PERIOD_START_DATE(meeting.period)；
• PERIOD_END_DATE() 以访问 period.endDate，例如 PERIOD_END_DATE(meeting.period)；
• PERIOD_BOUNDARY_TYPE() 以访问 period.boundaryType，例如 PERIOD_BOUNDARY_TYPE(meeting.period)。

Period 表单类型

像往常一样使用 Andante\PeriodBundle\Form\PeriodType 作为表单。此包附带没有表单主题，因此构建表单主题由您自己负责。

<?php

declare(strict_types=1);

use Andante\PeriodBundle\Form\PeriodType;
use Symfony\Component\Form\AbstractType;
use Symfony\Component\Form\Extension\Core\Type;
use Symfony\Component\Form\FormBuilderInterface;

class EventType extends AbstractType
{
    public function buildForm(FormBuilderInterface $builder, array $options)
    {
        $builder
            ->add('name', Type\TextType::class)
            ->add('period', PeriodType::class)
        ;
    }
}

PeriodType 选项

default_boundary_type

类型: string 默认值: []，允许的值：[]、()、(]、[])，如果没有通过boundary_type_choice选择，将使用哪种边界类型。

$builder->add('period', PeriodType::class, [
    'default_boundary_type' => '()',
]);

boundary_type_choice

类型: bool 默认值: false 是否包含BoundaryTypeChoiceType以允许用户选择边界类型。默认为false。要更改用于创建Period的边界类型，请查看default_boundary_type选项。

$builder->add('period', PeriodType::class, [
    'boundary_type_choice' => true,
]);

start_date_child_name

类型: string 默认值: start 表单子元素处理startDate属性时应如何调用。

$builder->add('period', PeriodType::class, [
    'start_date_child_name' => 'custom_start_date_form_child_name',
]);

end_date_child_name

类型: string 默认值: end 表单子元素处理endDate属性时应如何调用。

$builder->add('period', PeriodType::class, [
    'end_date_child_name' => 'custom_end_date_form_child_name',
]);

boundary_type_child_name

类型: string 默认值: boundary

$builder->add('period', PeriodType::class, [
    'boundary_type_child_name' => 'custom_boundary_type_form_child_name',
]);

如何调用处理boundaryType属性的表单子元素。

start_date_form_type

类型: string 默认值: Symfony\Component\Form\Extension\Core\Type\DateTimeType 用于startDate属性的表单类型。您可以将其替换为自定义内容。

use App\Form\MyDateTimeType;

$builder->add('period', PeriodType::class, [
    'start_date_form_type' => MyDateTimeType::class,
]);

end_date_form_type

类型: string 默认值: Symfony\Component\Form\Extension\Core\Type\DateTimeType 用于endDate属性的表单类型。您可以将其替换为自定义内容。

use App\Form\MyDateTimeType;

$builder->add('period', PeriodType::class, [
    'end_date_form_type' => MyDateTimeType::class,
]);

start_date_options

类型: array 默认值: [] 用于startDate表单子元素的附加选项。

$builder->add('period', PeriodType::class, [
    'start_date_options' => [
        'label' => 'A different Label',
        // + whatever option allowed by DateTimeType
    ],
]);

end_date_options

类型: array 默认值: [] 用于endDate表单子元素的附加选项。

$builder->add('period', PeriodType::class, [
    'end_date_options' => [
        'label' => 'A different Label',
        // + whatever option allowed by DateTimeType
    ],
]);

boundary_type_options

类型: array 默认值: [] 用于boundaryType表单子元素的附加选项。

$builder->add('period', PeriodType::class, [
    'boundary_type_options' => [
        'label' => 'A different Label',
        // + whatever option allowed by Andante\PeriodBundle\Form\BoundaryTypeChoiceType
    ],
]);

allow_null

类型: bool 默认值: true 用于boundaryType表单子元素的附加选项。

$builder->add('period', PeriodType::class, [
    'allow_null' => false,
    // Allow to trigger an error when your Period property is not nullable.
]);

配置（完全可选）

此扩展包旨在节省您的时间并尽可能遵循最佳实践。

这意味着您甚至可以忽略在您的应用程序中拥有andante_period.yml配置文件。

但是，出于任何原因，请使用扩展包配置来更改大多数行为以满足您的需求。

andante_period:
  doctrine:
    embedded_period:
      default:
        start_date_column_name: start_date # default: null
          # Column name to be used on database for startDate property. 
        # If set to NULL will use your default doctrine naming strategy
        end_date_column_name: end_date # default: null
          # Column name to be used on database for endDate property. 
        # If set to NULL will use your default doctrine naming strategy
        boundary_type_column_name: boundary_type # default: null
          # Column name to be used on database for update boundaryType property. 
        # If set to NULL will use your default doctrine naming strategy
      entity: # You can use per-entity configuration to override default config
        App\Entity\Event:
          start_date_column_name: starting_at
          end_date_column_name: ending_at
        App\Entity\Meeting:
          start_date_column_name: start
          end_date_column_name: end

由AndanteProject团队用爱💖构建。