README

一个用于生成站点地图的Charcoal包。

安装

composer require charcoal/contrib-sitemap

设置

对于Charcoal项目，此包可以通过两种方式注册。

Charcoal模块

站点地图模块将注册服务提供者（见下文）和路由（/sitemap.xml）。

您可以从配置文件注册此模块

"modules": {
    "charcoal/sitemap/sitemap": {}
}

Charcoal服务提供者

站点地图的服务提供者将注册构建站点图所需的服务（见下文）。

您可以从配置文件注册服务提供者

{
    "service_providers": {
        "charcoal/view/service-provider/view": {}
    }
}

要从配置文件注册路由

{
    "routes": {
        "actions": {
            "sitemap.xml": {
                "route": "/sitemap.xml",
                "methods": [ "GET" ],
                "controller": "charcoal/sitemap/action/sitemap",
                "action_data": {
                    "sitemap_ident": "xml"
                }
            }
        }
    }
}

默认情况下，动作控制器将查找名为xml的站点图层次结构，这可以通过sitemap_ident控制器设置进行更改。

概述

路由

• GET /sitemap.xml — 分配给 Charcoal\Sitemap\Action\SitemapAction 的路由。
  用于提供XML文档。

服务

• charcoal/sitemap/builder — Charcoal\Sitemap\Service\Builder 的实例。
  用于从配置的模型生成链接集合。
• sitemap/formatter/xml — Charcoal\Sitemap\Service\XmlFormatter 的实例。
  用于从Builder返回的链接集合生成XML。
• sitemap/presenter — Charcoal\Sitemap\Service\SitemapPresenter 的实例。
  用于解析模型转换。
• sitemap/transformer/factory — Charcoal\Factory\GenericFactory 的实例 (charcoal/factory)。
  用于从对象类型解析对象转换器。

配置

可以从应用程序的配置集下的sitemap键配置站点图。您可以设置要包含的对象和可用翻译（l10n）。

大多数选项都可以使用您应用程序选择的模板语法（以下示例中使用Mustache）渲染。

默认选项

{
    /**
     * The service's configuration point.
     */
    "sitemap": {
        /**
         * One or more groups to customize how objects should be processed.
         *
         * The array key is an arbitrary identifier for the grouping of models.
         */
        "<group-name>": {
            /**
             * Whether or not to include links to translations.
             *
             * - `true` — Multilingual. Include all translations
             *   (see `locales.languages`).
             * - `false` — Unilingual. Include only the default language
             *   (see `locales.default_language`).
             */
            "l10n": false,
            /**
             * The language to include a link to if group is unilingual.
             *
             * If `l10n` is `true`, this option is ignored.
             *
             * Defaults to the application's current language.
             */
            "locale": "<current-language>",
            /**
             * Whether or not to check if the routable object
             * has an active route (`RoutableInterface#isActiveRoute()`)
             *
             * - `true` — Include only routable objects with active routes.
             * - `false` — Ignore if a routable object's route is active.
             */
            "check_active_routes": false,
            /**
             * Whether or not to prepend relative URIs with
             * the application's base URI (see `base_url`).
             *
             * - `true` — Use only the object's URI (see `sitemap.*.objects.*.url`).
             * - `false` — Prepend the base URI if object's URI is relative.
             */
            "relative_urls": false,
            /**
             * The transformer to parse each model included in `objects`.
             *
             * Either a PHP FQCN or snake-case equivalent.
             */
            "transformer": "<class-string>",
            /**
             * Map of models to include in the sitemap.
             */
            "objects": {
                /**
                 * One or more models to customize and include in the sitemap.
                 *
                 * The array key must be the model's object type,
                 * like `app/model/foo-bar`, or fully-qualified name (FQN),
                 * like `App\Model\FooBar`.
                 */
                "<object-type>": {
                    /**
                     * The transformer to parse the object.
                     *
                     * Either a PHP FQCN or snake-case equivalent.
                     */
                    "transformer": "<class-string>",
                    /**
                     * The URI of the object for the `<loc>` element.
                     */
                    "url": "{{ url }}",
                    /**
                     * The name of the object. Can be used in a
                     * custom sitemap builder or XML generator.
                     */
                    "label": "{{ title }}",
                    /**
                     * Map of arbitrary object data that can be used
                     * in a custom sitemap builder or XML generator.
                     */
                    "data": {},
                    /**
                     * List or map of collection filters of which objects
                     * to include in the sitemap.
                     *
                     * ```json
                     * "<filter-name>": {
                     *     "property": "active",
                     *     "value": true
                     * }
                     * ```
                     */
                    "filters": [],
                    /**
                     * List or map of collection orders to sort the objects
                     * in the sitemap.
                     *
                     * ```json
                     * "<order-name>": {
                     *     "property": "position",
                     *     "direction": "ASC"
                     * }
                     * ```
                     */
                    "orders": [],
                    /**
                     * Map of models to include in the sitemap
                     * below this model.
                     *
                     * Practical to group related models.
                     */
                    "children": {
                        /**
                         * One or more models to customize and include in the sitemap.
                         */
                        "<object-type>": {
                            /**
                             * A constraint on the parent object to determine
                             * if the child model's objects should be included
                             * in the sitemap.
                             */
                            "condition": null
                        }
                    }
                }
            }
        }
    }
}

每个模型都可以覆盖其组中的以下选项：l10n、locale、check_active_routes、relative_urls。

示例

以下示例，标识为footer_sitemap，使用l10n选项标记为多语言，这将包含所有翻译。

{
    "sitemap": {
        "footer_sitemap": {
            "l10n": true,
            "check_active_routes": true,
            "relative_urls": false,
            "transformer": "charcoal/sitemap/transformer/routable",
            "objects": {
                "app/object/section": {
                    "transformer": "\\App\\Transformer\\Sitemap\\Section",
                    "label": "{{ title }}",
                    "url": "{{ url }}",
                    "filters": {
                        "active": {
                            "property": "active",
                            "value": true
                        }
                    },
                    "data": {
                        "id": "{{ id }}",
                        "metaTitle": "{{ metaTitle }}"
                    },
                    "children": {
                        "app/object/section-children": {
                            "condition": "{{ isAnObjectParent }}"
                        }
                    }
                }
            }
        }
    }
}

用法

使用构建器

构建器只返回一个数组。如果您需要其他格式，则需要自己创建转换器。

给定上述设置

$builder = $container['charcoal/sitemap/builder'];
// 'footer_sitemap' is the ident of the settings you want.
$links = $builder->build('footer_sitemap');

您还可以使用SitemapBuilderAwareTrait，它包含对站点图构建器的设置器和获取器，以便在所有必要的类中以最少的代码使用它。

XML格式化器

XML格式化器从构建器返回的数组生成有效的XML站点图。

$builder = $container['charcoal/sitemap/builder'];
$links   = $builder->build('footer_sitemap');

$formatter = $container['sitemap/formatter/xml'];
$sitemap   = $formatter->createXmlFromCollections($links);

开发

要安装开发环境

composer install

要运行脚本（PHP lint、PHPCS、PHPStan和PHPUnit）

composer lint
composer test

许可

Charcoal根据MIT许可证授权。有关详细信息，请参阅LICENSE。