README

介绍
要求
安装
用法
贡献

介绍

此包将面向对象的方法引入WordPress高级自定义字段（ACF）插件。ACF管理器将帮助你在单个PHP类中直接创建字段组、Gutenberg块、选项页面和灵活内容，从而使你的应用程序文件夹保持整洁和结构化。使用此包将使你忘记ACF后台界面，允许你进行版本控制你的ACF组，并将更改推送到多个环境变得轻而易举。

除了这些（令人惊叹）的功能之外，当从数据库中检索你的字段时，你还将收到FieldSet对象而不是数组，这使得字段可以转换成模型、类或其他基于字段名称转换的数据（例如，名为“image”的字段可能成为App\Models\Attachment对象，具有所有相应的属性和方法）。

幕后，acf-manager使用wordplate/extended-acf包的定制分支，附带明确的文档，所以请确保检查官方仓库以了解如何定义字段。

为了在您的应用程序中使用Eloquent模型（以及相应的内置转换器），如果尚未包含在您的框架中，我们强烈建议您查看ObjectPress库，它将一些最好的Laravel功能引入任何WordPress安装。

此包是独立的，但与Bedrock/Sage 10堆栈完全兼容，带有本地WordPress主题（已设置自动加载逻辑），并且可能与其他许多框架兼容。

基本用法

在其最基本的用法中，此插件可以按以下方式创建字段组

# Define field group
class Header extends \Grogu\Acf\Entities\FieldGroup
{
    public function fields(): array
    {
        return [
            Text::make('Titre', 'title')
                ->required(),
            Image::make('Image')
                ->previewSize('medium')
                ->returnFormat('id')
                ->required(),
        ];
    }

    public function location(): array
    {
        return [
            Location::where('post_type', 'page'),
        ];
    }
}

# Boot field group
add_action('acf/init', fn () => Header::make()->boot());

此包有一个配置文件来管理你的块注册，无需使用WordPress钩子

return [

    /*
    |--------------------------------------------------------------------------
    | The registred ACF field groups & layouts
    |--------------------------------------------------------------------------
    |
    | Register here your ACF groups. Please note that only groups with
    | at least a location needs to be registred (eg: don't need to
    | register groups being cloned in other group or flexible)
    |
    */

    'groups' => [
        App\Acf\Header::class,
    ],

    [...]
];

创建灵活内容部分也非常简单

use Grogu\Acf\Entities\FieldGroup;

class FreeSection extends FieldGroup
{
    public function fields(): array
    {
        return [
            FlexibleContent::make('Components')
                    ->buttonLabel('Add a new section')
                    ->thumbnails(true)
                    ->modal([
                        'enabled' => true,
                        'col'     => '4',
                    ])
                    ->layouts([
                        Blocks\Header::make()->toLayout(),
                        Blocks\Services::make()->toLayout(),
                        Blocks\Worldwide::make()->toLayout(),
                    ]),
        ];
    }

    [...]
}

最后，当返回你的字段时，你可以将它们解析到Field sets中，以利用转换和流畅的界面，允许在类上有多个访问器

<?php

use Grogu\Acf\Entities\FieldSet;

$fields = FieldSet::make(get_field('header', $post_id));

?>

// views/header.blade.php
<div class="bloc-header-home">
    <div class="main-text">{{ $fields->title }}</div>
    <img src="{{ $fields->image->url }}" alt="{{ $fields->image->alt }}">
</div>

FieldSet类完全流畅，所有这些方法都有效以获取值

$fields = FieldSet::make([
    'sub' => [
        'field' => 'foo',
    ],
]);

$fields->sub->field
$fields->sub?->field
$fields['sub']['field']
$fields->get('sub.field')

准备好开始了吗？

要求

ACF管理器有一些要求

PHP >= 8.0
WordPress
启用ACF插件

安装

使用Composer将包安装到您的主题目录中

composer require wp-grogu/acf-manager

在您的已自动加载的app/文件夹中创建一个Acf命名空间，它可能看起来像这样

- theme
    - config
    - app
        - Acf
            - Groups
            - Blocks
            - Templates
            - Options
        [...]
    [...]

在您的functions.php文件中启动模块

[...]
/*
|--------------------------------------------------------------------------
| Load Grogu ACF Manager
|--------------------------------------------------------------------------
|
| Grogu ACF Manager module helps us create and retreive ACF field groups.
| This line starts the engine, loads the config/acf.php config file,
| and register our field groups, gutemberg blocks and layouts.
|
*/

new Grogu\Acf\Core\Bootloader;

创建一个config/acf.php文件，它将使用WP-CLI保存您的配置

wp grogu-acf install:config

或者直接从源文件复制粘贴。

用法

每个字段组或Gutenberg块都有自己的独立类/文件。显然，它们都有自己的字段，有些可能还有一个或多个位置。所有这些都使用伟大的wordplate/extended-acf包定义，该包为ACF提供流畅的API。

创建字段组

要创建一个组，请运行以下WP-CLI命令

wp grogu-acf make:group GroupName
wp grogu-acf make:group GroupName --in:Templates # specify subdir

将创建一个新文件

<?php

namespace App\Acf;

use Grogu\Acf\Entities\FieldGroup;
use WordPlate\Acf\Location;

class GroupName extends FieldGroup
{
    /**
     * The group name to be displayed in back office. Required.
     *
     * @var string
     */
    public string $title = 'GroupName';
    
    /**
     * The group slug to be used when transformed into a flexible layout.
     *
     * @var string
     */
    public string $slug = 'group-name';

    /**
     * The group fields definition.
     *
     * @return array
     */
    public function fields(): array
    {
        return [
            //
        ];
    }

    /**
     * The group location configuration.
     *
     * @return array
     */
    public function location(): array
    {
        return [
            // Location::where('post_type', 'page'),
        ];
    }
}

您可以使用类属性来管理组的额外配置

class GroupName extends FieldGroup
{
    [...]

    /**
     * The group style.
     *
     * @var string default|seamless
     */
    public string $style = 'default';

    /**
     * The group position.
     *
     * @var string normal
     */
    public string $position = 'normal';

    /**
     * The group menu order. Lowest value appears first.
     *
     * @var int
     */
    public int $order = 10;

    /**
     * The hidden items on screen
     *
     * @var array
     */
    public array $hide_on_screen = [
        'the_content',
    ];
}

一旦您的字段和位置定义完成，您可以在config/acf.php配置文件中使用groups键注册您的新组

[...]

'groups' => [
    App\Acf\GroupName::class,
],

您还可以使用PHP的splat运算符组合来自另一个组的字段

public function fields(): array
{
    return [
        ...Groups\Header::clone(),

        Text::make('Headline', 'headline'),
    ];
}

创建Gutenberg块

// WIP

与灵活内容协同工作

由于您的字段定义在单个类中，因此将字段从一个组复制到另一个组或将其转换为布局变得非常简单。例如，我们将假设您正在将每个灵活布局定义为独立的字段组，位于app/Acf/Groups目录中。您将以这种方式定义灵活布局及其布局

namespace App\Acf\Templates;

use App\Acf\Groups;

class FreeSection extends FieldGroup
{
    public string $title = 'Free section';

    public function fields(): array
    {
        return [
            FlexibleContent::make('Components', 'components')
                    ->thumbnails(true)
                    ->modal([
                        'enabled' => true,
                        'col'     => '4',
                    ])
                    ->layouts([
                        Groups\TextImage::make()->toLayout(),
                    ]),
        ];
    }

    public function location(): array
    {
        return [
            Location::where('page_template', 'template-freesection.blade.php'),
        ];
    }
}

确保App\Acf\Templates\FreeSection组已注册在您的acf配置文件中，就这样！

在幕后，布局的字段组$title和$slug属性用于定义布局。但是，如果您需要更多对字段注册的控制，您可以手动定义您的布局

use WordPlate\Acf\Fields\Layout;

public function fields(): array
{
    return [
        FlexibleContent::make('Components', 'components')
            ->layouts([
                Layout::make('WYSIWYG section', 'wysiwyg-layout')
                    ->layout('block')
                    ->fields(
                        Groups\Wysiwyg::clone()
                    ),
                
                Layout::make('WYSIWYG section (grey background)', 'wysiwyg-grey-layout')
                    ->layout('block')
                    ->fields(
                        Groups\Wysiwyg::clone()
                    ),
            ]),
    ];
}

检索你的字段（FieldSet类）

// WIP

字段转换

// WIP

贡献

请随时贡献！您可以发送合并请求。

wp-grogu / acf-manager

维护者

详细信息

README

介绍

基本用法

要求

安装

用法

创建字段组

创建Gutenberg块

与灵活内容协同工作

检索你的字段（FieldSet类）

字段转换

贡献