README

使用关系型数据库持久化数据的 PHP 内容存储库 API （PHPCR）的实现。

Jackalope 使用 Doctrine DBAL 抽象数据库层。目前测试可兼容 MySQL、PostgreSQL 和 SQLite。

目前，它在功能、性能和稳定性方面不如 Jackalope-Jackrabbit，但它可以运行在任何拥有 PHP 和 SQL 数据库的服务器上。

在 [email protected] 上讨论，或访问 irc.freenode.net 上的 #jackalope

许可

本代码采用 MIT 许可证和 Apache 许可证版本 2.0 双重许可。请参阅此文件夹中的 LICENSE 文件。

要求

• PHP 版本：查看 composer.json
• 以下数据库之一，包括其 PDO 扩展
  • MySQL >= 5.1.5（需要 ExtractValue 函数）
  • PostgreSQL
  • SQLite
  • Oracle

安装

安装 jackalope 的推荐方法是使用 composer。

$ mkdir my-project
$ cd my-project
$ composer init
$ composer require jackalope/jackalope-doctrine-dbal

创建仓库

设置一个新的由 Doctrine DBAL 支持的数据库。您可以使用您喜欢的 GUI 前端，或者使用以下命令

MySQL

注意，您需要至少 MySQL 5.1.5 版本，否则您将收到 SQLSTATE[42000]: Syntax error or access violation: 1305 FUNCTION cmf-app.EXTRACTVALUE does not exist 错误

mysqladmin -u root -p  create database jackalope
echo "grant all privileges on jackalope.* to 'jackalope'@'localhost' identified by '1234test'; flush privileges;" | mysql -u root -p

还请注意，在使用 MySQL/MariaDB 时，您需要配置要使用的编码（见下面的 "引导" 部分）。

如果您已配置了编码但仍然遇到编码问题，例如 SQLSTATE[42000]: Syntax error or access violation: 1253 COLLATION 'utf8_bin' is not valid for CHARACTER SET 'utf8mb4'，您可以在调用 RepositoryFactoryDoctrineDBAL::getRepository 时设置 jackalope.case_sensitive_encoding 参数。

PostgreSQL

psql -c "CREATE ROLE jackalope WITH ENCRYPTED PASSWORD '1234test' NOINHERIT LOGIN;" -U postgres
psql -c "CREATE DATABASE jackalope WITH OWNER = jackalope;" -U postgres

SQLite

如果您指定了驱动程序和路径（"pdo_sqlite"，"jackalope.db"），则会自动创建数据库。不需要指定数据库名称。

有关详细信息，请参阅 Doctrine 配置页面。

Oracle

免责声明：没有与 Oracle 的持续集成。Jackalope 1.8.0 已由我们的用户之一在 Oracle 19c Enterprise Edition 上成功测试。如果您计划使用 Jackalope 与 Oracle 数据库一起使用，我们建议您设置 Jackalope 测试套件以确保您的 Jackalope 和 Oracle 版本可以很好地协同工作。

注意：已自动添加 doctrine 中间件到数据库连接，以解决 Oracle 在其结果中将小写表和字段名称转换为上划线的问题。

CLI 工具

我们提供了一些有用的命令来与仓库交互。

注意：如果您使用的是与 Symfony 框架集成的 PHPCR，则 DoctrinePHPCRBundle 提供了正常 Symfony 控制台中的命令。只有在您不使用 Symfony 集成的 Jackalope 的情况下才进行以下设置。

要使用控制台，将 cli-config.dist.php 复制到 cli-config.php 并配置连接参数。然后您可以从 Jackalope 目录中运行命令 ./bin/jackalope

有一个 Jackalope 特定的命令 jackalope:init:dbal，您需要运行它以初始化数据库，然后才能使用它。

您可以从 phpcr-utils 获得许多有用的命令。要获取所有命令的列表，请输入

$ ./bin/jackalope

要获取有关特定命令的更多信息，请使用help命令。例如，要了解关于phpcr:workspace:export命令的更多信息，您会输入

$ ./bin/jackalope help phpcr:workspace:export

启动过程

在您可以使用Jackalope与数据库一起使用之前，您需要准备数据库。创建一个数据库，如上所述，然后确保命令行实用工具已设置（见上“CLI工具”）。现在您可以运行

$ bin/jackalope jackalope:init:dbal

完成这些步骤后，您可以启动库。获取使用doctrine-dbal后端的PHPCR会话的极简示例代码

// For further details, please see Doctrine configuration page.
// http://docs.doctrine-project.org/projects/doctrine-dbal/en/latest/reference/configuration.html#connection-details

use Doctrine\DBAL\DriverManager;
use Jackalope\RepositoryFactoryDoctrineDBAL;
use PHPCR\SimpleCredentials;

$driver    = 'pdo_mysql'; // pdo_pgsql | pdo_sqlite
$host      = 'localhost';
$user      = 'admin'; // only used for recording information about the node creator
$sqluser   = 'jackalope';
$sqlpass   = 'xxxx';
$database  = 'jackalope'; 
// $path      = 'jackalope.db'; // for SQLite
$workspace = 'default';
$charset   = 'utf8mb4'; // only for MySQL/MariaDB

// Bootstrap Doctrine
$connection = DriverManager::getConnection([
    'driver'    => $driver,
    'host'      => $host,
    'user'      => $sqluser,
    'password'  => $sqlpass,
    'dbname'    => $database,
    // 'path'   => $path, // for SQLite
    'charset    => $charset, // only for MySQL/MariaDB
]);

$factory = new RepositoryFactoryDoctrineDBAL();
$repository = $factory->getRepository(
    ['jackalope.doctrine_dbal_connection' => $connection]
);

// Dummy credentials to comply with the API
$credentials = new SimpleCredentials($user, null);
$session = $repository->login($credentials, $workspace);

要使用不同于default的工作空间，您需要首先创建它。要创建新的工作空间，请运行命令bin/jackalope phpcr:workspace:create <myworkspace>。您也可以使用PHPCR API从您的代码中创建工作空间。

用法

入口点是创建存储库工厂。工厂还指定了存储后端。从此点开始，使用方式没有差异（除了支持的功能）。

// See Bootstrapping for how to get the session.

$rootNode = $session->getNode('/');
$whitewashing = $rootNode->addNode('www-whitewashing-de');

$session->save();

$posts = $whitewashing->addNode('posts');

$session->save();

$post = $posts->addNode('welcome-to-blog');

$post->addMixin('mix:title');
$post->setProperty('jcr:title', 'Welcome to my Blog!');
$post->setProperty('jcr:description', 'This is the first post on my blog! Do you like it?');

$session->save();

有关如何使用PHPCR API的更详细教程，请参阅PHPCR教程。

性能调整

如果您知道您将需要请求的节点的大量子节点，请使用Session::getNode上的深度提示。这将预取子节点以减少往返数据库的次数。这是PHPCR标准的一部分。您也可以全局设置获取深度，但这仅是Jackalope特有的：调用Session::setSessionOption使用Session::OPTION_FETCH_DEPTH设置一个大于1的值。

如果只需要知道子节点的名称，而无需实际的节点，请使用Node::getNodeNames。注意，您不应在jackalope中使用getNodeNames上的typeFilter。使用typeFilter与getNodes仅获取您感兴趣的类型的节点非常有意义。

高级配置

日志记录

Jackalope支持日志记录，例如，调查使用的查询的数量和类型。要启用日志记录，向存储库工厂提供一个日志记录器实例。

use Jackalope\RepositoryFactoryDoctrineDBAL;
use Jackalope\Transport\Logging\DebugStack;

$factory = new RepositoryFactoryDoctrineDBAL();
$logger = new DebugStack();

$parameters = [
    'jackalope.doctrine_dbal_connection' => $connection,
    'jackalope.logger' => $logger,
];

$repository = $factory->getRepository($parameters);

//...

// at the end, output debug information
var_dump($logger->calls);

您还可以使用Psr3Logger类将一个PSR-3兼容的日志记录器（如monolog）包装起来。

注意，在Symfony2中使用jackalope时，日志记录器集成在调试工具栏中。

自定义UUID生成器

默认情况下，Jackalope使用phpcr-utils中的UUIDHelper类。如果您想使用其他内容，您可以为参数jackalope.uuid_generator提供一个返回UUIDs的闭包，并将其传递给$factory->getRepository($parameters)。

实现说明

有关Jackalope构建的介绍，请参阅doc/architecture.md。查看源文件并生成phpdoc。

运行测试

Jackalope-doctrine-dbal与phpcr-api-tests套件集成，该套件测试所有PHPCR功能。

如果您想运行测试，请参阅测试文件夹中的README文件。

待办事项

要完成的工作的最好概述是跳过的API测试。查看ImplementationLoader以了解目前不工作的是什么，并开始修改 :-)

还可以查看此项目和基础jackalope/jackalope的问题跟踪器。

贡献者

• Christian Stocker [email protected]
• 大卫·布赫曼 [email protected]
• 托比亚斯·伊本诺特 [email protected]
• 罗兰·席尔特 [email protected]
• 乌韦·耶格尔 [email protected]
• 卢卡斯·卡韦·史密斯 [email protected]
• 本杰明·艾伯莱 [email protected]
• 丹尼尔·巴索蒂 [email protected]
• 以及许多其他人