README

用于创建带有炭的网站的骨架。

见下文，了解此骨架的结构和目标概述。

安装

此骨架可在Packagist上找到，并可以使用Composer进行安装。

composer create-project charcoal/boilerplate example-project

安装骨架后，将您的Web服务器的文档根目录指向example-project/www目录。

默认情况下，骨架包括Apache的.htaccess文件。请参见下文中的配置您的Web服务器示例。

从命令行，PHP提供了一个内置的Web服务器，用于快速提供项目。

cd www
php -S localhost:8080

在浏览器中访问http://localhost:8080以查看以下内容

示例：骨架的默认索引页面

更新

此骨架不提供自动升级的过程。您将必须手动移植任何更新。

这是因为骨架是您项目的起点，其各种文件主要存在于演示目的，否则将根据您的需求删除或修改。

应用程序配置

创建config/config.sample.json文件的副本，并将其命名为config/config.local.json。这是您的环境特定配置文件，并且它应该排除在您的项目源代码库之外。编辑此文件以配置数据库、第三方服务、日志和缓存等服务。

有关您项目的任何其他选项都应在config目录中的所有其他文件中进行更改。

数据库配置

如果您的项目不需要任何数据库存储，请在config/config.local.json文件中添加以下内容，使用内存数据库，例如SQLite

{
    "databases": {
        "default": {
            "type": "sqlite",
            "database": ":memory:"
        }
    },
    "default_database": "default"
}

如果您的项目使用MySQL，请创建一个空数据库，并确保一个SQL用户具有此数据库的正确权限。然后在config/config.local.json文件中添加以下内容

{
    "databases": {
        "default": {
            "type": "mysql",
            "hostname": "127.0.0.1",
            "database": "foobar",
            "username": "foo_bar",
            "password": "l337"
        }
    },
    "default_database": "default"
}

项目名称

默认情况下，骨架使用“Acme”作为虚拟名称。在存储库中应更改一些地方以反映您的项目

config/admin.json：请参见admin.title。
config/config.json：请参见project_name和cache.prefix。

您还应该更改Composer依赖项清单的详细信息

composer.json：请参见name。

管理仪表板

提供了一个快速简单的命令行脚本，用于安装管理区域的资源。

./build/scripts/install-charcoal-admin.sh

之后，在浏览器中访问 http://localhost:8080/admin/login，可以看到以下内容：

示例：Charcoal的管理登录页面

可以从 config/admin.json 文件中自定义管理区域。

安装Locomotive模板

可选地，还提供了一个快速简单的脚本，用于安装Locomotive的前端开发工具。

./build/scripts/install-locomotive-boilerplate.sh

有关更多信息，请访问Locomotive的模板仓库。

服务器要求

PHP >= 7.4
PHP 扩展
- JSON
- MBString
- PDO
- SPL

服务器配置

Apache配置

以下配置可以作为配置Apache HTTP服务器的起点。注意，应使用此配置而不是骨架的.htaccess文件。

注意，您应将path/to/example-project/www替换为example-project/www的实际路径。

示例：Apache配置

# Set document root to be "example-project/www"
DocumentRoot "path/to/example-project/www"

<Directory "path/to/example-project/www">
    <IfModule mod_rewrite.c>
        RewriteEngine on

        # If a directory or a file does not exist,
        # forward the request to the application controller
        RewriteCond %{REQUEST_FILENAME} !-d
        RewriteCond %{REQUEST_FILENAME} !-f
        RewriteRule ^ index.php
    </IfModule>
</Directory>

Nginx配置

以下配置可以作为配置Nginx HTTP服务器的起点。

注意，您应将path/to/example-project/www替换为example-project/www的实际路径。

示例：Nginx配置

server {
    listen 80;
    listen [::]:80;

    server_name example-project.test;
    root        /path/to/example-project/www;
    access_log  /path/to/example-project/logs/access.log;
    error_log   /path/to/example-project/logs/error.log;

    index index.php;

    charset utf-8;

    location / {
        # Redirect everything that isn't a real file to index.php
        try_files $uri $uri/ /index.php$is_args$args;
    }

    location = /favicon.ico {
        access_log off;
        log_not_found off;
    }

    location = /robots.txt  {
        access_log off;
        log_not_found off;
    }
 
    error_page 404 /index.php;

    location ~ \.php$ {
        fastcgi_pass unix:/var/run/php/php8.0-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~* /\. {
        deny all;
    }
}

开发

代码风格检查

默认情况下，骨架使用一些编码风格和静态代码分析工具进行开发

EditorConfig - 在不同的编辑器之间保持一致的编码风格。
JSON Lint - JSON编码风格检查器。
PHP语法检查 - 命令行中的PHP语法检查器。
PHP_CodeSniffer (PHPCS) - PHP编码风格检查器。
PHPStan - 静态PHP代码分析器。
Psalm - 静态PHP代码分析器。

PHPStan和Psalm一起使用，以利用每个工具的专长。

可以通过运行以下命令之一执行代码风格检查：

# Run JSON Lint, PHP Lint, PHPCS, PHPStan, and Psalm
composer lint

# Run only JSON Lint
composer lint:json
./vendor/bin/jsonlint config/*.json

# Run only PHP syntax check
composer lint:php
php -l src/*.php

# Run only PHPCS
composer lint:phpcs
./vendor/bin/phpcs -ps --colors src/

# Run only PHPStan
composer lint:phpstan
./vendor/bin/phpstan analyse

# Run only Psalm
composer lint:psalm
./vendor/bin/psalm

大多数这些工具都可以从以下文件中进行配置：

EditorConfig - .editorconfig 文件。
PHP_CodeSniffer - phpcs.xml.dist 文件或phpcs.xml文件。
PHPStan - phpstan.neon.dist 文件或本地phpstan.neon文件。
Psalm - psalm.xml.dist 文件或本地psalm.xml文件。

测试

默认情况下，PHP测试位于tests目录，并使用PHPUnit框架进行开发。

可以通过运行以下命令之一执行测试：

composer test
composer test:phpunit
./vendor/bin/phpunit

PHPUnit 可以从phpunit.xml.dist或本地phpunit.xml文件进行配置。

优化

锁定依赖关系

当您将composer.lock文件包含在项目源代码控制存储库中时，可以显著加快项目依赖项的安装速度。Composer会自动生成并保持此文件更新。

自动加载器优化

在生产部署时，请确保您已优化Composer的类自动加载映射，以便Composer能快速找到给定PHP类的对应文件

composer install --optimize-autoloader --no-dev

贡献

我们感谢对骨架和Charcoal的任何贡献，无论是错误、错别字、建议还是改进。

概述

尽管可以投入使用，但此骨架仍然不完整。

它尚未展示Charcoal框架的所有功能，因此需要大量手动调整选项。

以下是使用此骨架预期完成的简要“使命声明”

一个完全自动化的设置过程。
- 可选安装Locomotive Boilerplate以快速进行前端集成。
支持单语和多语言应用程序。
- 默认数据提供英文和法语。
- 易于国际化（i18n）和本地化（l10n）。
支持Mustache和Twig模板。
- 主页，带有一些选项和小工具（如轮播图）等。
- 新闻列表/新闻详情，支持附件。
- 日历（事件列表）具有ajax选项/事件详情，支持附件。
- 博客/文章详情，支持附件以及启用评论和ajax操作的选项
- 联系，包含保存到数据库的联系方式表单，并基于类别选项发送确认电子邮件，支持ajax操作。
- 地图，按类别显示位置。
一个工作的管理仪表板。
- 用户管理。
- 默认配置允许管理CMS对象（部分、新闻、事件、博客、位置等）
- 权限系统正常工作并启用。
- 通知系统正常工作并启用。
- 修订系统正常工作并启用。
- 媒体库正常工作并启用。
- 内置的帮助（文档）系统正常工作并启用。
每个页面和每个对象上的元数据100%完全正常工作。
- 使用对象的元数据信息，所有这些都可以在charcoal-admin中编辑。
提供优化的SEO功能集。
搜索功能启用
- 返回所有类型CMS对象（部分、新闻、事件、博客、位置等）的结果。
- 使用的关键词，所有这些都可以在charcoal-admin中编辑。
- 还可以在附件中搜索。
- 自动完成功能启用并正常工作。
100%使用PHPUnit测试。

🚂

炭 / 样板

维护者

详细信息