README

LunaCMS 是一个用 PHP 构建的轻量级且可扩展的内容管理系统 (CMS)。它利用了现代 PHP 组件，如用于模板的 Twig、用于数据库交互的 Doctrine DBAL 以及用于处理电子邮件的 PHPMailer。本 README 提供了关于安装、配置和扩展 LunaCMS 以满足您的开发需求的全面说明。

功能

• MVC 架构：控制器和视图的明确关注点分离。
• 使用 Twig 模板化：灵活且功能强大的模板引擎。
• 数据库抽象：使用 Doctrine DBAL 进行稳健的数据库交互。
• 电子邮件处理：集成了 PHPMailer 用于发送电子邮件。
• 资产管理：利用 Gulp 编译 SCSS 和 JavaScript 资产。
• 路由系统：简单有效的路由用于处理 HTTP 请求。
• CLI 工具：使用 SiteGenerator 轻松设置项目。

安装

先决条件

• PHP 8.0 或更高版本
• Composer
• Node.js 和 npm
• Gulp CLI：使用 npm install --global gulp-cli 全局安装

步骤

1. 克隆存储库

   git clone https://github.com/mrmanchot/lunacms.git

2. 导航到项目目录

   cd lunacms

3. 安装 PHP 依赖

   composer install

4. 初始化 npm 并安装 Node 依赖

   如果 package.json 文件不存在，则初始化 npm

   npm init -y

   然后，安装 Gulp 及其依赖

   npm install --save-dev gulp sass gulp-sass gulp-concat gulp-uglify gulp-clean-css

5. 生成项目结构

   使用 CLI 脚本生成必要的目录和文件。

   php create_site.php /path/to/new/site

6. 配置项目

   使用您的项目特定设置编辑 config/config.json 文件。

7. 使用 Gulp 构建资产

   gulp

项目结构

/your-project
│
├── assets
│   ├── js
│   │   └── script.js
│   └── scss
│       └── main.css
│
├── cache
│   └── twig
│
├── config
│   ├── config.json
│   └── routes.php
│
├── public
│   ├── css
│   ├── js
│   ├── img
│   └── index.php
│
├── src
│   └── Controllers
│       └── PageController.php
│
├── templates
│   ├── includes
│   │   └── base.twig
│   └── index.twig
│
├── vendor
│
├── gulpfile.js

关键目录和文件的描述

• assets/：包含 JavaScript 和 SCSS 的源文件。
• cache/twig/：存储缓存的 Twig 模板。确保此目录可写。
• config/：配置文件。
  • config.json：主要配置文件。
  • routes.php：定义应用程序路由。
• public/：网站根目录。
  • index.php：应用程序的入口点。
  • css/、js/、img/：编译后的资产。
• src/Controllers/：包含控制器类。
  • PageController.php：示例控制器。
• templates/：Twig 模板。
  • includes/base.twig：基本模板。
  • index.twig：示例页面模板。
• vendor/：Composer 依赖。
• gulpfile.js：用于资产管理的 Gulp 配置。

配置

所有配置都通过 config/config.json 文件管理。以下是每个配置选项的解释。

{
    "base_path": /path/to/project",
    "lang": "en",
    "charset": "UTF-8",
    "database": {
        "host": "localhost",
        "dbname": "lunacms",
        "user": "root",
        "password": ""
    },
    "debug": true,
    "site": {
        "name": "Your Site Name",
        "base_url": "https://www.yoursite.com/"
    },
    "mail": {
        "host": "smtp.example.com",
        "port": 587,
        "username": "your_email@example.com",
        "password": "your_email_password",
        "encryption": "tls",
        "from_address": "no-reply@example.com",
        "from_name": "Your Site Name",
        "reply_to_address": "support@example.com",
        "reply_to_name": "Support Team"
    }
}

配置选项

• base_path：项目基本目录的绝对路径。
• lang：网站的默认语言。
• charset：模板中使用的字符编码。
• database:
  • host：数据库主机。
  • dbname：数据库名称。
  • user：数据库用户名。
  • password：数据库密码。
• debug：启用或禁用调试模式。启用时，显示详细的错误消息。
• site:
  • name：您网站的名称。
  • base_url：您网站的基 URL。
• mail:
  • host：SMTP 服务器主机。
  • port：SMTP 服务器端口。
  • username：SMTP 用户名。
  • password：SMTP 密码。
  • encryption：加密类型（tls 或 ssl）。
  • from_address：默认的发件人电子邮件地址。
  • from_name：默认的发件人姓名。
  • reply_to_address: 默认回复邮箱地址。
  • reply_to_name: 默认回复名称。

路由

LunaCMS 使用简单的路由系统将 URL 映射到控制器操作。路由定义在 config/routes.php 文件中。

定义路由

路由可以包含花括号 {} 内的动态参数。

<?php

use App\Controllers\PageController;

return [
    '' => PageController::class,
    'about' => PageController::class,
    'contact' => PageController::class,
    'blog/{slug}' => PageController::class,
];

支持的 HTTP 方法

目前，LunaCMS 支持 GET 和 POST 方法。您可以使用 Routing::get 和 Routing::post 方法为每个方法定义路由。

use LunaCMS\Routing;

// Define a GET route
Routing::get('about', PageController::class);

// Define a POST route
Routing::post('contact', ContactController::class);

控制器

控制器处理您应用程序的业务逻辑。它们扩展了抽象类 LunaCMS\Controller，该类提供了渲染模板、访问数据库和发送电子邮件等常见功能。

扩展控制器

要创建新的控制器，扩展 Controller 类并实现 dataAssignment 方法。

<?php

namespace App\Controllers;

use LunaCMS\Controller;

class PageController extends Controller
{
    public function dataAssignment(): void
    {
        $site = $this->getConfigVar('site');
        $this->template = $this->params['slug'] ?? 'index';
        $this->css[] = '/css/main.css';
        $this->js[] = '/js/main.js';
        $this->addVar('meta_title', 'Title | ' . $site['name']);
        $this->addVar('meta_description', 'Description');
    }
}

控制器生命周期

1. 初始化 (__construct)：设置 Twig、数据库连接和邮件发送器。
2. 初始化 (init)：分配路由参数并执行控制器逻辑。
3. 处理 (treatment)：可选的预处理方法。
4. 数据分配 (dataAssignment)：分配要传递给视图的数据。
5. 渲染 (display)：使用分配的变量渲染 Twig 模板。

使用 Twig 模板化

LunaCMS 使用 Twig 作为其模板引擎。模板位于 templates/ 目录中。

创建模板

在 templates/ 目录或其子目录中创建新的 Twig 模板。

{% extends 'includes/base.twig' %}

{% block title %}
    <h1>Welcome to {{ site.name }}</h1>
{% endblock %}

{% block content %}
    <p>{{ content }}</p>
{% endblock %}

扩展基本模板

使用 {% extends %} 指令从基本模板继承。

{% extends 'includes/base.twig' %}

{% block title %}
    <h1>About Us</h1>
{% endblock %}

{% block content %}
    <p>Information about us.</p>
{% endblock %}

包含部分模板

使用 {% include %} 指令包含部分模板。

{% include 'includes/header.twig' %}

<div class="content">
    {{ content }}
</div>

{% include 'includes/footer.twig' %}

使用 Gulp 管理资源

LunaCMS 使用 Gulp 编译和管理资源，如 SCSS 和 JavaScript 文件。

Gulp 任务

• scss：编译 SCSS 文件到 CSS 并压缩它们。
• js：连接并压缩 JavaScript 文件。
• watch：监视 SCSS 和 JS 文件的变化并自动重新编译它们。
• default：运行 scss、js 和 watch 任务。

运行 Gulp

执行以下命令以启动 Gulp 任务

gulp

这将编译您的资源并开始监视变化。

自定义 Gulp

您可以通过修改 gulpfile.js 来添加更多任务或调整现有任务。

const gulp = require('gulp');
const sass = require('gulp-sass')(require('sass'));
const concat = require('gulp-concat');
const uglify = require('gulp-uglify');
const cleanCSS = require('gulp-clean-css');

gulp.task('scss', () => 
    gulp.src('assets/scss/**/*.scss')
        .pipe(sass().on('error', sass.logError))
        .pipe(cleanCSS())
        .pipe(gulp.dest('public/css'))
);

gulp.task('js', () => 
    gulp.src('assets/js/**/*.js')
        .pipe(concat('main.js'))
        .pipe(uglify())
        .pipe(gulp.dest('public/js'))
);

gulp.task('watch', () => {
    gulp.watch('assets/scss/**/*.scss', gulp.series('scss'));
    gulp.watch('assets/js/**/*.js', gulp.series('js'));
});

gulp.task('default', gulp.series('scss', 'js', 'watch'));

数据库交互

LunaCMS 使用 Doctrine DBAL 进行数据库交互，提供强大的抽象层。

访问数据库连接

在您的控制器中，您可以如下访问数据库连接

$connection = $this->getConnection();

// Example query
$sql = "SELECT * FROM users WHERE id = ?";
$stmt = $connection->prepare($sql);
$stmt->bindValue(1, $userId);
$stmt->execute();
$user = $stmt->fetchAssociative();

执行查询

Doctrine DBAL 允许您执行各种类型的查询，包括选择、插入、更新和删除。

// Select Query
$users = $connection->fetchAllAssociative('SELECT * FROM users');

// Insert Query
$connection->insert('users', [
    'name' => 'John Doe',
    'email' => 'john@example.com'
]);

// Update Query
$connection->update('users', ['email' => 'john.doe@example.com'], ['id' => 1]);

// Delete Query
$connection->delete('users', ['id' => 1]);

发送电子邮件

LunaCMS 集成 PHPMailer 用于发送电子邮件。您可以使用 Controller 类提供的 sendEmail 方法发送电子邮件。

发送电子邮件

$toEmail = 'recipient@example.com';
$toName = 'Recipient Name';
$subject = 'Welcome to LunaCMS';
$body = '<p>Thank you for registering!</p>';
$altBody = 'Thank you for registering!';

$sent = $this->sendEmail($toEmail, $toName, $subject, $body, $altBody);

if ($sent) {
    // Email sent successfully
} else {
    // Handle the failure
}

配置邮件设置

确保您的 config/config.json 中的 mail 部分正确配置了您的 SMTP 服务器详细信息。

"mail": {
    "host": "smtp.example.com",
    "port": 587,
    "username": "your_email@example.com",
    "password": "your_email_password",
    "encryption": "tls",
    "from_address": "no-reply@example.com",
    "from_name": "Your Site Name",
    "reply_to_address": "support@example.com",
    "reply_to_name": "Support Team"
}