README

与 PEAR DB 兼容的替代品，从 PEAR DB 分支而来。

此存储库已移动（正在移动？）

从 2022 年 8 月起，此存储库将从 https://github.com/wethersherbs/pineapple 移动到 https://github.com/may-den/pineapple。旧引用仍然有效，一个存档分支将保留在旧 URL 上以实现兼容性。请相应地更新任何引用、书签以及 composer/packagist 引用。

是什么？

围绕 PDO 或 Doctrine DBAL 的兼容层，为基于 PEAR DB 的应用程序提供向后兼容性。

它几乎是一个即插即用的替代品（但不是），您需要修改您的应用程序，但这些修改应该是最小的。

为什么？

PEAR DB 非常古老（版权范围在 Pineapple 诞生前 9 年结束），已被 MDB2 弃用，而 MDB2 又已过时。一些项目基于这些模块，但需要升级路径，这意味着可以使用现代数据库访问方法开发新代码，同时保留对旧代码的访问，而无需打开第二个数据库连接。

最终，它将为您所做的一切提供向后兼容性，并让您为未来的工作编写更现代的东西。

如何？

此软件包是 PEAR 和 DB 的分支，经过大量重构。它的目的是提供一个方法兼容的即插即用替代品，重新实现 PEAR::raiseError 和 PEAR::isError，以及 DB 类下的所有方法。删除特定连接的驱动程序，只包含两个连接驱动程序：DoctrineDbal，它接受构建的 doctrine/dbal 对象，以及 PdoDriver，它接受构建的 PDO 对象。它旨在仅作为迁移到 PDO 或 Doctrine DBAL 的途径，在保持单个数据库连接的同时保留旧系统的运行。

目的是移除未使用的功能，清理（移除所有警告和通知），使 PSR-2 清洁，并全面测试 DB 兼容层。全局常量将被类常量替换，以保持干净的常量命名空间。

您的应用程序负责缓存构建的数据库连接对象。请勿在依赖注入后使用 Pineapple 获取您的连接对象。

用法

在 Doctrine DBAL 模式下

<?php

use Pineapple\DB;
use Pineapple\DB\Driver\DoctrineDbal;

// lengthy dbal connection here...

$db = DB::factory(DoctrineDbal::class);
$db->setConnectionHandle($dbalConn);
$result = $db->query('SELECT USER(), DATABASE()');

在 PDO 模式下

<?php

use Pineapple\DB;
use Pineapple\DB\Driver\PdoDriver;

$db = DB::factory(PdoDriver::class);
$db->setConnectionHandle(new PDO('sqlite::memory:'));
$result = $db->query('SELECT CURRENT_TIMESTAMP');

集成到您的项目中

类名更改

首先，您应该注意以下类名的更改。如果您使用类型提示、使用 instanceOf 或检查类名的方法，您需要了解以下类名的更改：

### 常量更改

其次，PEAR_ 和 DB_ 全局常量（定义）现在是类常量，需要相应地限定作用域。所有以 PEAR_ 开头的东西都位于 Pineapple\Util 中，所有以 DB_ 开头的东西都位于 Pineapple\DB 中。我们建议使用命名空间别名，例如。

<?php
use Pineapple\DB;

$query = $db->query('SELECT CURRENT_TIMESTAMP');
if (DB::isError($query) && $query->getCode() === DB::DB_ERROR_INVALID) {
    die();
}

已弃用方法和变量访问。

第三，PEAR 和 DB 的很大一部分被无耻地移除和丢弃。位于 PEAR 类中且不是 isError 的任何东西

isError
引发错误
抛出错误

...现在已被移除。保留上述方法作为类方法和静态方法调用（已确定这两种方法在审查的代码中广泛使用）。

所有DSN处理代码已从DB（现在为Pineapple\DB）类中移除。它仅作为驱动类构造工厂和错误处理的覆盖存在。以下方法被保留（其他所有内容，例如connect()）现在已被移除）

工厂
isError
isConnection
errorMessage

最重要的是，以下方法已从驱动类中移除

用查询占位符（参数化查询）替换这些

quoteString
quote

如果需要DBMS抽象检查，用Doctrine DBAL的调用替换这些

getTables
getSpecialQuery
getListOf

序列功能应通过SQL实现

createSequence
dropSequence
getSequenceName
nextId

上述方法的移除意味着类变量现在是私有和受保护的混合，并且将不会对您的应用程序可用。已经提供了一些“获取器”（和一些设置器），以便您使用。请参阅

getOption（伴随DB的setOption）
getFeature
getLastQuery
getFetchMode
getFetchModeObjectClass
getLastQuery
getLastParameters
getNativeErrorCode

为了在运行时切换数据库，构建的驱动对象的_db属性的变化已被替换为对changeDatabase方法的调用。

最后，autoPrepare和autoExecute将不再在没有WHERE子句的情况下执行UPDATE或DELETE。通过调用方法setAcceptConsequencesOfPoorCodingChoices来更改此行为。

代码更改摘要

所有类都是命名空间化的。请参阅前一个部分中的类名映射表。
所有全局变量现在都已删除。
全局常量已移动到类常量。
已删除所有连接驱动程序。提供的唯一驱动程序是DoctrineDbal和PdoDriver，分别用于连接Doctrine的DBAL和PDO，并且意图是通过这两个层之一执行所有连接。
已删除PEAR中的所有方法，除了isError、raiseError和throwError。这包括PEAR的伪析构函数（关闭函数）。
已删除旧构造函数和'_Name'析构函数的兼容性名称。
已删除PEAR和DB错误抑制。
用于帮助多驱动程序兼容性的大量代码已被删除。
润色并遵循PSR-2。重构以支持PHP的一些更现代的方面（例如，将方法静态替换为类静态）。
为未处理的事件（通常会导致die）添加了三个新异常：DriverException、FeatureException和StatementException。
不要使用connect()，使用factory()并使用setConnectionHandle()设置连接。

测试套件

构建了一套测试套件，以帮助在重构期间进行回归测试。已尽力实现对所有方法和类的100%覆盖率。请确保在提交补丁或拉取请求之前运行测试套件。

测试套件的脚本已放入项目的composer.json文件中。要执行它，请运行

$ composer test

遗憾的是，composer压缩了彩色输出，这有助于在交互式运行时指示失败。如果您希望以彩色化查看输出，请运行

$ vendor/bin/phpunit --coverage-html='coverage/' --coverage-text='php://stdout' --colors=auto

我们建议在支持的PHP矩阵（5.6-8.1）上测试所有更改。

致谢

Pineapple是以下人员的工作：

九个nine@aphlor.org（GitHub用户borb）

应对Mayden表示感谢，因为它支持作者完成Pineapple的初始发布。

数据库的作者应该获得最多的赞誉；源代码在整体上进行了重构。

以下赞誉来自数据库

Stig Bakken ssb@php.net
Tomas V.V.Cox cox@idecnet.com
Daniel Convissor danielc@php.net

以及以下来自 PEAR

Sterling Hughes sterling@php.net
Stig Bakken ssb@php.net
Tomas V.V.Cox cox@idecnet.com
Greg Beaver cellog@php.net

有关其他归属信息，请参阅文件 "CONTRIBUTORS.md"。

许可协议

上游 PEAR 在 BSD 2-clause 许可协议下分发。本协议予以保留。此协议适用于类 Util、Error 和 Exception。

上游 DB 在 PHP 许可协议下分发，该协议是一种 BSD-style 许可协议。本协议予以保留。此协议适用于所有其他类，包括由 DB_mysqli 派生的 DoctrineDbal（不再包含在此软件包中）。

任何额外的代码或测试套件均提供在 PHP 许可协议下。

may-den / pineapple

维护者

详细信息