README

Raccoon 是一个基于 Composer & NPM & Babel (ES 2015 预设) & Gulp & Knacss 的 WordPress 入门主题。

摘要

要求
安装
如何使用 Raccoon
如何用 Raccoon 编码
- 面向对象的 PHP 类
- Raccoon 爱PSR-2 编码标准和文档
如何使用 Raccoon 帮助您使用 WordPress
第三方功能
- Raccoon 爱Bedrock

要求

为了其开发，Raccoon 需要

PHP >= 5.6
Composer
带有 npm 的 Node.js 进行包管理
WordPress >= 4.4

安装

很简单：您只需克隆存储库并运行 composer install 以启动所有所需任务。

git clone https://github.com/hiwelo/raccoon.git
composer install

如何使用 Raccoon

准备工作

在进行任何修改之前，请运行

composer work

使用此命令，您将验证您的存储库是最新的，并启动所有监视任务。

供应商更新

定期，别忘了使用以下命令更新所有依赖项（composer & npm）

composer update

提交前

在进行任何修改并在提交任何内容之前，我强烈建议您运行

composer test

如果没有错误，您就可以提交您的修改。

如果存在一些错误并且您绝对想要提交，您必须运行此命令以避免预提交验证

git commit --no-verify

文档

如果您想解析所有 PHP 文件以生成文档，请运行

composer documentation

生成的文档位于 ./docs/api/ 文件夹中。

如何用 Raccoon 编码

面向对象的 PHP 类

Raccoon 是一个基于 OOP 的 WordPress 模板。所有 Raccoon 的类都放在命名空间 Hwlo\Raccoon\ 中，您可以在 ./lib 目录中找到它们。

您创建的任何自定义类都应该放在特定的命名空间中。例如，您可以使用类似于 Hwlo\Raccoon\Custom\ 的命名空间。

当您创建一个新的命名空间时，您必须在 composer.json 文件的 autoload 部分中添加它。我强烈建议使用 PSR-4 命名空间。

例如，如果您想注册一个类似于 Hwlo\Raccoon\Custom\ 的自定义命名空间，您必须将自定义类写入 ./custom-lib/ 并更新 composer.json 如下所示

{
  "autoload": {
    "psr-4": {
      "Hwlo\\Raccoon\\": "./lib/",
      "Hwlo\\Raccoon\\Custom\\": "./custom-lib/"
    }
  }
}

对于每个新创建的类，您可能需要重新生成 ./vendor/autoload.php 文件。为此操作，请运行

composer autoload

Raccoon 喜爱 PSR-2 编码规范和文档

当一只浣熊工作时，它会确保自己的工作可以被所有人理解。因此，它会编写符合 PHP 社区使用的标准的脚本。

Raccoon 使用 PSR-2 编码规范进行测试。每次修改都必须通过 PSR-2 语法检查才能提交。因此，Raccoon 只有很少的修改：脚本文档需要由 ruleset.xml 为 PHP CS 验证提供。

您可以通过以下命令在任何时候对所有的 PHP 和 JavaScript 文件运行测试控制

composer test

一些 PHP 文件上的错误可以通过 phpcbf 自动修复。要这样做，请运行

composer phpcbf

所以不要忘了：要让 Raccoon 开心，请为您的 该死的 代码编写文档！ :D

浣熊如何帮助您使用 WordPress

配置清单

为了避免多个初始化函数，Raccoon 使用一个 JSON 配置文件：manifest.json。在此文件中，您可以设置 WordPress 向其主题提供的所有功能。

WordPress 主题命名空间

使用 Raccoon，您可以为此主题定义一个特定的命名空间。这个命名空间主要会被用于字符串翻译方法，如 __() 或 _e() 或 _x() 或 _n()。

要定义一个特定的命名空间，您必须更新 manifest.json 如下所示

{
  "namespace": "raccoon"
}

如果为空或未定义，则默认命名空间将是 raccoon。

主题支持

使用 Raccoon，您可以使用 manifest.json 文件轻松设置所有主题功能。

WordPress 文档中描述的所有功能都可以带或不带参数进行注册。考虑到 JSON 格式，一个功能至少需要一个布尔值。

以下是您可以在 manifest.json 文件中设置的语句类型

{
  "theme-support": {
    "title-tag": true,
    "post-thumbnail": true,
    "automatic-feed-links": true,
    "post-formats": [
      "link",
      "quote",
      "audio",
      "video"
    ],
    "html5": [
      "caption",
      "comment-form",
      "comment-list",
      "gallery",
      "search-form"
    ]
  }
}

主题功能

Raccoon 有一个功能允许您禁用一些 WordPress 功能，如小工具或评论。在 manifest.json 文件中，您可以通过以下方式轻松（启用/禁用）这些功能

{
  "theme-features": {
    "comments": false,
    "widget": false
  }
}

文章类型

创建自定义文章类型

使用 Raccoon，您可以通过 manifest.json 文件轻松地设置自定义文章类型。

每个自定义文章类型都必须有一个标题和一个参数数组。所有在 WordPress 文档中描述的参数都可以用于 manifest.json 文件。

例如，如果您想注册与 WordPress 文档中相同的文章类型，您必须像这样更新 manifest.json：

{
  "post-types": {
    "books": {
      "labels": {
        "name": "Books",
        "singular_name": "Book",
        "menu_name": "Books",
        "name_admin_bar": "Book",
        "add_new": "Add New",
        "add_new_item": "Add New Book",
        "new_item": "New Book",
        "edit_item": "Edit Book",
        "view_item": "View Book",
        "all_items": "All Books",
        "search_items": "Search Books",
        "parent_item_colon": "Parent Books:",
        "not_found": "No books found.",
        "not_found_in_trash": "No books found in Trash."
      },
      "description": "Description.",
      "public": "true",
      "publicly_queryable": "true",
      "query_var": "true",
      "rewrite": {
        "slug": "book"
      },
      "menu_icon": "dashicons-editor-paragraph",
      "supports": [
        "title",
        "editor",
        "author",
        "thumbnail",
        "excerpt",
        "custom-fields",
        "revisions",
        "post-formats"
      ]
    }
  }
}

值得注意的是，您不能在 manifest.json 中声明名为 remove 的自定义文章类型。

取消注册文章类型

使用 Raccoon，您也可以通过 manifest.json 文件轻松取消注册现有的文章类型。

每个现有的文章类型，包括文章或页面，都可以使用此 manifest.json 功能取消注册。您只需将以下内容添加到您的 manifest.json：

{
  "post-types": {
    "remove": ["post"]
  }
}

例如，如果您想注册与 WordPress 文档中相同的文章类型，您必须像这样更新 manifest.json：

文章状态

使用 Raccoon，您可以通过 manifest.json 文件轻松设置自定义文章状态。每个自定义文章状态都将自动添加到每个管理员面板页面中的文章状态选择框中。

每个自定义文章状态都可以使用 WordPress register_post_status() 方法中描述的所有参数。

例如，如果您想注册一个新的自定义文章状态，您必须像这样更新 manifest.json：

{
  "post-status": {
    "archive": {
      "label": "Archive",
      "exclude_from_search": false,
      "public": false,
      "internal": false,
      "protected": true,
      "private": false,
      "publicly_queryable": false,
      "show_in_admin_all_list": true,
      "show_in_admin_status_list": true,
      "_builtin": true,
      "label_count": [
        "Archive <span class=\"count\">(%s)</span>",
        "Archives <span class=\"count\">(%s)</span>"
      ]
    }
  }
}

值得注意的是，您不能在 manifest.json 中声明名为 remove 的自定义文章状态。

侧边栏

使用 Raccoon，您可以通过 manifest.json 文件轻松设置侧边栏。

每个侧边栏都必须有一个参数数组。所有在 WordPress 文档中描述的参数都可以用于 manifest.json 文件。

例如，如果您想注册与 WordPress 文档中相同的侧边栏，您必须像这样更新 manifest.json：

{
  "sidebars": [
    {
      "name": "Sidebar name",
      "id": "unique-sidebar-id",
      "description": "Description.",
      "class": "sidebarClassName",
      "before_widget": "<li id=\"%1$s\" class=\"widget %2$s\">",
      "after_widget": "</li>",
      "before_title": "<h2 class=\"widget__title\">",
      "after_title": "</h2>"
    }
  ]
}

小工具

使用 Raccoon，您可以通过 manifest.json 文件轻松设置小工具。

每个小工具都必须包含一个特定的 OOP PHP 类，如 WordPress 文档中所述。因此，对于小工具注册，您只需在 manifest.json 中添加小工具类名及其完整的命名空间，如下所示

{
  "widgets": [
    "Hwlo\\Raccoon\\WidgetExample"
  ]
}

第三方功能

浣熊喜欢Bedrock

Bedrock 是一个 WordPress 模板，主要通过将新的 wp-content/ 文件夹重命名为 app/ 来创建更好的项目结构。 Bedrock 使用 Composer 和环境变量。

例如，Raccoon 可以使用 Bedrock 的环境变量来了解环境状态（开发、生产、预发布）并管理哪些调试信息应该由主题返回。如果您不使用 Bedrock，您可以在 manifest.json 文件中手动设置环境状态，如下所示

{
  "environment-status": "development"
}

hiwelo / raccoon-starter

维护者

详细信息