README

❗ 此 PHP 库是为 TYPO3 CMS 开发的，旨在为 TYPO3 扩展开发者提供。

➡️ 您可以在 TYPO3 官方网站 上找到完整的文档，甚至可以下载 🔗PDF 版本。

介绍

配置对象 提供了处理配置树 强大工具，通过将任何 配置平面数组（可能来自 TypoScript、JSON、XML 等来源）转换为更灵活的 PHP 对象结构。其主要目标是 将配置处理与应用程序的主要逻辑分离，以便脚本可以在整个过程中专注于 使用已经验证过的配置。

问题

当脚本使用配置树来处理应用程序的部分时，这个树通常在脚本执行过程中 逐步分析；如果值中包含错误，脚本可能被迫停止，过早（整个过程没有完全运行）也可能过晚（一些敏感操作可能已经运行）。此外，配置树越深，处理和防止所有可能的配置错误就越困难。

当涉及到可能被任何第三方用户定制的配置时（这在TYPO3中很常见，归功于TypoScript），验证规则必须 深思熟虑且强大，以防止用户因配置错误而破坏您的API脚本。

解决方案

使用 配置对象 来导出您的配置处理：让整个 创建和验证过程在您的应用程序外部管理，并享受API提供的 许多其他功能（缓存管理、父级、持久性等）。

它 简单、快速且可靠。

示例

假设您有这个配置数组

$myCompany = [
    'name'      => 'My Company',
    'employees' => [
        [
            'name'   => 'John Doe',
            'gender' => 'Male',
            'email'  => 'john.doe@my-company.com'
        ],
        [
            'name'   => 'Jane Doe',
            'gender' => 'Female',
            'email'  => 'jane.doe@my-company.com'
        ]
    ]
];

虽然这个例子很简单，但它使我们能够很容易地理解这个API是如何工作的。

以下是一个使用 配置对象API 的示例，展示这种配置可能的样子。

您可以看到这里使用了 两个服务。

• 缓存服务

  它会在对象及其子对象创建后，将整个公司对象存储在缓存条目中。这将在下次必须检索对象时提高性能。

• 父级服务

  使用这个服务，类 Employee 能够从其父类（即 Company 类）检索数据。在这个示例中，我们使用它为员工动态生成一个电子邮件地址，如果尚未分配的话。

namespace MyVendor\MyExtensions\Company;

use Romm\ConfigurationObject\ConfigurationObjectInterface;
use Romm\ConfigurationObject\Traits\ConfigurationObject\DefaultConfigurationObjectTrait;
use Romm\ConfigurationObject\Traits\ConfigurationObject\MagicMethodsTrait;
use MyVendor\MyExtensions\Model\Company\Employee;

class Company implements ConfigurationObjectInterface
{
    use DefaultConfigurationObjectTrait;
    use MagicMethodsTrait;

    const CACHE_NAME = 'cache_company';

    /**
     * @var string
     * @validate NotEmpty
     */
    protected $name;

    /**
     * @var \ArrayObject<MyVendor\MyExtensions\Company\Employee>
     */
    protected $employees;

    /**
     * @return ServiceFactory
     */
    public static function getConfigurationObjectServices()
    {
        return ServiceFactory::getInstance()
            ->attach(ServiceInterface::SERVICE_CACHE)
            ->setOption(CacheService::OPTION_CACHE_NAME, self::CACHE_NAME)
            ->attach(ServiceInterface::SERVICE_PARENTS);
    }
}

namespace MyVendor\MyExtensions\Company;

use Romm\ConfigurationObject\Service\Items\Parents\ParentsTrait;
use Romm\ConfigurationObject\Traits\ConfigurationObject\MagicMethodsTrait;

class Employee
{
    use ParentsTrait;
    use MagicMethodsTrait;

    /**
     * @var string
     * @validate NotEmpty
     */
    protected $name;

    /**
     * @var string
     * @validate NotEmpty
     * @validate Romm.ConfigurationObject:HasValues(values=Male|Female)
     */
    protected $gender;

    /**
     * @var string
     * @validate EmailAddress
     */
    protected $email;

    /**
     * Returns the email of the employee.
     *
     * If the email was not registered, a default one is assigned to
     * him, based on its name and its company name.
     *
     * Example: `John Doe` of the company `My Company` will be assigned
     * the default email: `john.doe@my-company.com`.
     *
     * @return string
     */
    public function getEmail()
    {
        if (null === $this->email
            && $this->hasParent(Company::class)
        ) {
            $sanitizedEmployeeName = SomeUtility::sanitizeStringForEmail($this->getName());

            $company = $this->getParent(Company::class);
            $sanitizedCompanyName = SomeUtility::sanitizeStringForEmail($company->getName(), '-');

            $this->email = vprintf(
                '%s@%s.com',
                [$sanitizedEmployeeName, $sanitizedCompanyName]
            );
        }

        return $this->email;
    }
}