README

PHBeam是一个简单快速的PHP微框架。它没有任何管理面板。所有数据和配置都由PHP或JSON文件存储。

适用于构建拥有数十页甚至小型产品目录或相册的网站。

要求

您需要一个支持PHP >= 5.4的Web服务器。不需要数据库。

安装

PHBeam可以通过以下方式之一安装

1. 使用Composer（推荐）

确保已安装Composer。
在您希望创建新PHBeam项目的目录中运行此命令
```
composer create-project nikomtis/phbeam myproject
```
此方法将自动下载PHBeam并安装所有必要的依赖项。

2. 克隆Git仓库

使用以下命令克隆仓库

git clone https://github.com/nikomtis/phbeam.git myproject

克隆后，导航到项目目录（cd myproject）并运行composer install以安装依赖项。

3. 手动安装

从PHBeam发布中下载最新版本的zip文件。
将其提取到您希望的位置，并根据需要手动安装依赖项。

安装后配置

对于所有安装方法，配置您的Web服务器以使用public/index.php作为入口点。这通常涉及在Web服务器的配置中设置DocumentRoot或等效指令。

设置您的项目

要使用PHBeam引擎创建网站，您应遵循以下步骤

添加菜单和菜单项（路由）
为每个页面填充PHP文件中的HTML代码和meta标签
定义页面布局，如果您在不同页面上有不同的内容结构
创建具有相等或相似内容并出现在多个页面上的模块

让我们逐一回顾这些步骤。

添加路由（菜单项）

只有当网页存在于一个菜单文件中时，它才能向用户显示。

menus/目录存储包含网站路由的菜单文件。开箱即有一个名为main的菜单。让我们看看文件main.php。

<?php

return [
    '' => [
        'file' => 'home',
        'name' => 'Home',
        'layout' => '',
        'body_class' => '',
    ],
];

只有一个菜单项或路由。

数组第一级的每个键是页面URL。具有空URL的数组元素匹配网站首页。路由器会跳过前面的斜杠。

每个菜单项包含4个字段

file（必需）是content/目录中包含此页面HTML代码的文件名（不带扩展名）；如果该文件位于子目录中（例如content/subdirectory/page.php），字段必须填写如下：'file' => 'subdirectory/page'
name（可选）是菜单项显示名称；您可以使用它来渲染导航菜单
layout（可选）是页面应使用的布局名称；如果字段不存在或为空，页面将使用config.php中的default_layout值
body_class（可选）是应用于<body>HTML标签的CSS类；如果字段不存在或为空，页面将使用config.php中的default_body_class值

您可以自由添加自己的字段，例如用于特殊导航菜单样式或脚本的字段。

如果您要为某个页面添加新的菜单项，菜单文件将如下所示

<?php

return [
    '' => [
        'file' => 'home',
        'name' => 'Home',
        'layout' => '',
        'body_class' => '',
    ],
    'about' => [ // Page will be available on example.com/about
        'file' => 'about', // Page file with HTML code is "content/about.php"
        'name' => 'About us', // We want this name in navigation menu
    ]
];

在“创建模块”部分，我们将看到如何渲染导航菜单。

注册新菜单

如果你的网站只有一个导航菜单（主页、关于、联系方式等），你必须向主菜单文件添加菜单项。但你可能需要多个导航，例如侧边栏中的二级菜单。然后在 menus/ 目录中创建新的菜单文件 secondary.php 并在 config.php 中注册它。

...
'menus' => [
    'main',
    'secondary', // Separate menu for sidebar
],
...

填充网站内容

content/ 目录存储展示网页内容的文件。

每个页面可能有最多3个文件。以名为 "home" 的页面为例（菜单文件存储页面名称）

home.php 将包含此页面的HTML代码
home_meta.php 将存储将被插入到 <head> HTML标签中的标题、描述和关键词
home_modules.php 将控制哪些模块将在每个指定的位置渲染

因此，要添加新页面，你应该至少创建一个你指定在菜单中的文件名。

还有一个名为 "404" 的特殊页面。如果没有为请求的路线设置菜单项，它将渲染。你也可以操作它的文件。

定义页面布局

layouts/ 目录存储页面布局。布局是页面内容的包装器。

这里有一个包含你网站主要标记的 layout.php 文件。这是添加字体、样式表和脚本的正确位置。你可以使用 phb_insert_css() 和 phb_insert_js() 函数添加本地CSS和JS文件。如果你想从 public/css/main.css 文件中添加样式表，只需这样做

<head>
    ...
    <?php phb_insert_css('main'); ?>
    ...
</head>

它将被渲染为

<head>
    ...
    <link rel="stylesheet" href="/css/main.css?v=1531560805">
    ...
</head>

在上面的代码中，你可以看到 "v" URL参数。这是文件最后修改的时间戳。这有助于清除浏览器缓存以更新你的样式表。

phb_insert_js() 的工作方式类似。这段代码

<?php phb_insert_js('main'); ?>

将被渲染为

<script src="/js/main.js?v=1531560805"></script>

自定义布局

你可以添加不同的布局，这些布局将被不同的页面使用。

有一个名为 bare.php 的布局是现成的，它直接渲染网页内容而不影响页面视图；默认情况下，所有页面都使用它（默认布局可以在 config.php 文件中更改，请参阅 default_layout 选项）。但你可以为一些页面添加另一个布局，例如使用具有 container 类的 div 来限制内容宽度。只需创建一个名为 container.php 的文件（你可以选择任何名称）并包含以下代码

<div class="container">
    <?php echo $GLOBALS['article']; ?>
</div>

然后指定 container 布局（不包含扩展名）以在菜单文件中的任何页面中。

404 页面的布局可以在 config.php 中指定 - error_page_layout 就是你要找的。

创建模块

modules/ 目录存储可以包含在任何网站位置的文件。

让我们看看如何添加一个导航栏模块。

首先，我们需要在 modules/ 目录中创建 navbar.php 文件

<ul class="nav">
    <?php foreach ($GLOBALS['menu_main'] as $alias => $menu_item): ?>
        <a href="/<?php echo $alias; ?>" class="nav-link<?php if ($alias === $GLOBALS['path']) echo ' active'; ?>">
            <?php echo $menu_item['name']; ?>
        </a>
    <?php endforeach;?>
</ul>

我们在该文件中使用的内容

$GLOBALS['menu_main'] 是从 menus/main.php 文件中获取的 main 菜单项的关联数组
$alias 是页面的URL，用于构建链接（不要忘记前面的 / 以定义URL根目录）
$GLOBALS['path'] 是当前页面的URL
$menu_item['name'] 是页面名称；你可以访问菜单文件中显示的所有菜单项字段

现在你可以在页面文件（甚至在其他模块）的任何地方插入 <?php phb_insert_module('navbar'); ?> 来渲染导航栏。

但使用模块位置会更方便。

使用模块位置

让我们升级我们的自定义布局 layouts/container.php（使用Bootstrap CSS类）

<div class="container">
    <?php if (phb_get_position_modules('sidebar')): ?>
        <div class="row">
            <div class="col-sm-3">
                <aside>
                    <?php phb_insert_position('sidebar'); ?>
                </aside>
            </div>
            <div class="col-sm-9">
                <main>
                    <?php echo $GLOBALS['article']; ?>
                </main>
            </div>
        </div>
    <?php else: ?>
        <main>
            <?php echo $GLOBALS['article']; ?>
        </main>
    <?php endif;?>
</div>

我们可以使用 phb_get_position_modules('sidebar') 函数来检查当前页面是否在 sidebar 位置有模块，并防止渲染空的侧边栏。

插入 <?php phb_insert_position('sidebar'); ?> 以指定模块应出现的位置。

然后通过编辑菜单文件或在 config.php 文件中设置 default_layout 选项来配置页面使用 container 布局。

在 content/home_modules.php 中定义此模块为 sidebar 位置。

<?php

return [
    'sidebar' => [
        'navbar'
    ]
];

传递数据到模块

您可能需要在不同的页面上渲染相似但不完全相同的模块，例如带有背景图像的页面标题。让我们看看如何做到这一点。

创建 modules/fancy_title.php 文件

<div class="fancy-title" style="background-image: url(<?php echo $params['image']; ?>)">
    <div class="fancy-title-text">
        <?php echo $params['text']; ?>
    </div>
</div>

并将其添加到 content/home_modules.php

<?php

return [
    'sidebar' => [
        'navbar',
        'fancy_title' => [
            'text' => 'Home', // $params['text'] in the module file
            'image' => '/img/home.jpg' // $params['image']
        ]
    ]
];

如果不希望使用位置，您可以使用第二个参数将参数传递给模块

<?php phb_insert_module('fancy_title', ['text' => 'Home', 'image' => '/img/home.jpg']); ?>

更改模块类前缀

当使用位置渲染模块时，它将被包裹在一个带有前缀CSS类的div中。例如，如果您的模块文件是 navbar.php，CSS类将是 module_navbar。

您可以通过编辑 config.php 中的 modules_classes_prefix 选项来更改类前缀。

允许URL参数

PHBeam路由器严格检查URL与菜单文件中别名的匹配。如果只有多余的字符，您将看到404错误页面。所有URL参数都将被阻止。

但如果您希望允许通过URL参数打开网站页面，请将所需的参数添加到 config.php 中。例如，要允许像 example.com/about?yclid=123123 这样的URL（此类URL由Yandex.Direct使用）执行此操作

<?php

return [
    'allowed_url_params' => [
        'yclid',
    ],
    ...
];

处理资源

在PHBeam中，您可以存储自定义数据数组：小型产品目录、照片画廊、新闻源等。您可以使用PHP或JSON文件来完成此操作。

PHP资源

让我们为两个产品添加资源。

创建 resources/catalog_iphones.php 资源文件

<?php

return [
    'iphone_x_256_silver' => [
        'name' => 'iPhone X 256GB Silver',
        'image' => '/img/catalog/iphones/iphone_x_256_silver.png',
        'memory' => '256',
        'display' => '5,8',
    ],
    'iphone_8_64_gold' => [
        'name' => 'iPhone 8 64GB Gold',
        'image' => '/img/catalog/iphones/iphone_8_64_gold.png',
        'memory' => '64',
        'display' => '4,7',
    ],
];

然后创建 modules/catalog.php 模块

<div class="catalog">
    <?php foreach (phb_get_data_from_php("resources/catalog_{$params['category']}") as $key => $product): ?>
        <div class="product">
            <div class="product-image">
                <img src="<?php echo $product['image']; ?>" alt="<?php echo $product['name']; ?>">
            </div>
            <div class="product-name">
                <?php echo $product['name']; ?>
            </div>
            <div class="product-memory">
                <?php echo $product['memory']; ?>GB
            </div>
            <div class="product-display">
                <?php echo $product['display']; ?>"
            </div>
        </div>
    <?php endforeach; ?>
</div>

并在您的页面上合适的位置插入 <?php phb_insert_module('catalog', ['category' => 'iphones']); ?>

phb_get_data_from_php() 函数返回包含指定PHP文件数据的数组。我们可以遍历数组并为每个数组元素渲染一些HTML代码。

JSON资源

您还可以使用JSON资源。在这种情况下，您的资源文件 resources/catalog_iphones.json 将如下所示

{
  "iphone_x_256_silver": {
    "name": "iPhone X 256GB Silver",
    "image": "/img/catalog/iphones/iphone_x_256_silver.png",
    "memory": "256",
    "display": "5,8"
  },
  "iphone_8_64_gold": {
    "name": "iPhone 8 64GB Gold",
    "image": "/img/catalog/iphones/iphone_8_64_gold.png",
    "memory": "64",
    "display": "4,7"
  }
}

您需要使用 phb_get_data_from_json() 而不是 phb_get_data_from_php() 函数。

许可证

MIT许可。

nikomtis / phbeam

维护者

详细信息