README

README.md

Eric Vought

2014-12-8 VCard-Tools PHP工具箱

MIT许可https://open-source.org.cn/licenses/MIT

Composer包：evought/vcard-tools

#项目介绍#

这项工作是一套PHP中操作VCard（RFC 6350）的工具，包括内存表示、数据库持久化和HTML模板。这些工具建立在Martins Pilsetnieks、Roberts Bruveris的VCard PHP类（https://github.com/nuovo/vCard-parser）和George_h在Stackoverflow上的RFC6868/VCard 3.0示例VCard SQL模式的基础上。VCard-Tools将改进的VCard类与一套用于数据库持久化的类（基于George_h的模式）以及灵活的HTML输出（针对VCard 4.0（RFC 6350）合规性）相结合，这些输出定义在EVought\vCardTools命名空间中。它还包括一个不断增长的PHPUnit测试套件。

此文件描述了项目、设置和基本用法。有关类层次结构和设计讨论等更多信息，请参阅Wiki。

该包目前处于预发布状态，不应被视为生产代码。GitHub存储库概述了通往1.0版本的目标和预期功能。

#许可#

所有组件均在MIT许可下。

#组件#

项目由EVought\vCardTools命名空间中的PHP类组成。主要的类是vCard、VCardDB和Template。SQL模式（MySQL）定义在sql/，文档材料在doc/，PHPUnit测试用例在tests/下。预定义的模板在src/templates/中。下面将描述数据库设置。还有一个Phing脚本来自动化项目维护任务。我还设置了NetBeans IDE的使用。

内部依赖项已分离。VCard可以在没有Template或VCardDB类的情况下使用。模板代码可以与原始VCard类（带有或没有数据库持久化）一起使用，而数据库持久化不需要使用Template类。

HTML模板设计时考虑了CSS样式。在标记中明确指示了类和角色作为样式钩子，并且为个人与组织或摘要与完整信息等提供不同的输出非常简单。在一个实际网站上，我打算让用户能够轻松地从搜索列表转到个人详细列表，导出原始.vcf文本，甚至可能生成QR码。我预计将添加一个用于正确hcard输出的模板，但这不应该很困难（根本不困难）使用现有代码来使用该机制生成符合规范的hcard。

数据库代码旨在适应不同的数据库设置，并且这将继续作为未来的设计方向。用于检索/存储/搜索VCard的SQL查询定义在外部.ini文件中，以简化维护并允许自定义。

##自动加载##

源文件和类的设计符合PSR-4规范，因此应该与兼容的自动加载器一起工作。Composer会自动生成这样的自动加载器，可以从vendor/autoload.php中包含。

##需求##

该项目正在针对以下内容开发

• PHP 7.0
• MySQL 5.7 (5.7.1.13)

已知此库不与PHP 5.4兼容，但持续集成服务器定期在hhvm（Hip Hop虚拟机）上进行测试。

依赖关系通过Composer进行跟踪。Composer工具，通过其composer.json中的配置获取、跟踪和安装构建和使用VCardTools所需的组件。Composer还提供了使用vCardTools类所需的自动加载脚本。

Composer将定位并安装VCardTools所需的两个其他PHP库：

• rhumsaa/uuid：一个用于生成RFC 4122版本1、3、4和5的通用唯一标识符（UUID）的工具。

• evought/data-uri：一个方便的类，用于在PHP中处理Data URI。

为了开发和运行测试，composer还将安装

• Phing
• PHPUnit
• PHPDocumentor

及其依赖项。

我在基于Intel的Fedora Linux 20工作站上进行了大部分开发，持续集成服务器定期在一个干净的Ubuntu Linux环境中测试代码。

注意：我发现，为了在裸Linux Mint 18安装（php7已存在）上使composer工作，我必须安装php-dom（一个PHP扩展）和composer包。php-xdebug对于单元测试是必需的。

$ sudo apt-get install php-dom php-xdebug composer

提示：最好不在Linux Mint/Ubuntu上通过apt安装其他php包，以便让composer自己管理版本，正确匹配您可能正在使用的此库的版本。这样，您可以在必要时同时独立地使用多个依赖版本。

通过Composer包含

要通过Composer将此库包含到更大的项目中，您首先必须为您的项目有一个composer.json。该文件必须包含以下额外设置

"require": {
        "evought/vcard-tools": "dev-master"
    }

如果您只使用VCard-Tools的非数据库部分，这应该足以让您开始，并执行“composer install”以获取和安装此包。如果您还使用数据库部分，事情会复杂一些，因为您还必须将数据库模式安装到您的数据库中，并在升级到VCard-Tools的新版本时能够更新模式。VCard-Tools提供了一些工具来简化此过程，并允许您在情况不寻常时自定义此过程。您将想要仔细阅读数据库设置部分。如果您在单独的目录中检出此包的源代码，设置它并运行其测试以查看它是如何独立工作的，这可能有助于您理解如何围绕它设置项目。

如果您使用数据库组件，您需要将额外的依赖项添加到项目的composer.json文件中

"require-dev": {
    "phing/phing": "2.*",
    "robmorgan/phinx": "*"
},

这些设置将安装Phing项目自动化工具和Phinx数据库迁移工具。

源代码安装

在检出包后，“composer install”应该将所需的依赖项获取并安装到vendor/子目录中。各种工具将安装到vendor/bin中。如果您在一个类Unix环境中运行，您可以通过

$ . ./dotme.sh

将vendor/bin添加到您的路径中。

依赖版本将被锁定到 composer.lock 文件中指定的版本。要强制更新到依赖项的新版本，需要使用 "composer update"。

数据库设置#

为了使用该软件，需要一个数据库（例如 VCARD）来包含表，以及一个具有适当权限来访问它的用户。在适当的设置和数据库中具有适当权限的用户的情况下，phing 和 phinx 将为您实际加载模式。

这些说明针对的是使用 VCard-Tools 检出源的用户。在这种情况下，设置数据库的任务已经在 build.xml 文件中。如果您将此库包含在另一个项目中，您需要创建自己的 build.xml。有关如何做到这一点的说明，请参阅“您的项目的 build.xml”部分。

首先，您需要一个具有创建数据库和授予对该数据库中测试用户权限的权限的 MySQL 用户账户。我称这个为 开发者账户。您可以使用 MySQL 的 root 用户来做这件事，但从一般原则来看，最好有一个具有低于超级用户权限但高于您的单元测试账户的开发者账户。在某些环境中，例如共享数据库，您可能没有使用 root 账户的选项。根据您的设置，这可以通过例如 PHPMyAdmin 或命令行工具来完成。在大多数环境中

$ mysql --user=root -p

将作为 MySQL root 用户打开 SQL 壳，提示输入密码。然后您可以创建所需的账户并授予它权限

mysql> create user 'developer'@'localhost' identified by 'password';
mysql> grant all on VCARD.* to 'developer'@'localhost' with grant option;

用适当的值替换 'developer' 和 'password'。如果您将使用脚本创建下面的单元测试用户，您还需要

mysql> grant create user on *.* to developer@localhost;

在您的项目文件夹中创建一个 ${env.USER}.properties 文件，从 db.properties 复制并编辑值以设置数据库的用户名、密码、主机、数据库名等。（换句话说，我会把这些设置放在 'evought.properties' 中）。由于您的个人属性文件不会受到 git 的控制，您不必担心将设置（和密码！）提交回仓库。phing 构建脚本 build.xml 将使用这些设置来构建一些配置文件，初始化数据库，并运行测试。注意单元测试用户的设置，如下所示。

运行 'phing config' 将构建所需的配置文件（例如 database.php）。每次更改这些设置时，您都希望运行

$ phing cleanConfig && phing config

以强制它们重新构建。然后您可以

$ phing createUnitDBUser

使用开发用户凭据根据 db.properties 设置为您创建单元测试用户。如果您的开发用户被允许创建用户和授予权限，那么您通常不需要修改这些值。否则，覆盖 ${env.USER}.properties 文件中的设置，并使用您创建开发用户的过程以相同的方式创建单元测试用户。在下一步将为该用户授予适当的权限。

$ phing creatUnitDB
$ phing migrateDevelopment

创建数据库并向您的测试用户（对 VCARD.* 的 SELECT、INSERT、UPDATE 和 DELETE 权限）授予权限，然后运行所有数据库模式迁移，使数据库达到当前状态。

单元测试将在每次运行后自动删除新行并重置表状态，因此您 不应该 需要自行清理和重置数据库，除非发生了某些事情破坏了其状态，或者您故意对数据进行或对模式进行了更改。如果发生这种情况

$ phing rollbackDevelopment && phing migrateDevelopment

将重新创建表，或者在极端情况下

$ phing dropUnitDB $ phing createUnitDB && phing migrateDevelopment

单元测试依赖于一个 xml 表转储来设置/重置测试用例的初始状态。如果模式已更改，您将想要通过运行（例如）来重新创建此文件

$mysqldump --xml -t -u [username] -p [database] > tests/emptyVCARDDB.xml

有关更多信息，请参阅 PHPUnit 手册，数据库测试章节。

数据库迁移

VCardTools使用Phinx来管理数据库架构的变化。数据库更改集（“迁移”）在src/sql/migrations中以有序的PHP脚本形式定义。每个迁移的脚本模板通过运行“phinx create”命令创建，然后在模板中填写up()/down()或change()方法。

通过运行phing任务“phing migrateDevelopment”来应用所有未应用的迁移，通过调用“phinx migrate development”，所有定义的迁移将通过“phing rollbackDevelopment”任务回滚，该任务运行“phinx rollback development”。“phinx status”将显示已应用到当前数据库的迁移列表。“phing migrate”和“phing rollback”带适当的参数将使数据库达到特定状态。

因此，对数据库架构的所有更改都应该通过向项目中添加适当的迁移脚本来完成（或至少在原型设计后将其永久化）。

自定义查询##

单个SQL查询在src/sql/VCardDBQueries.ini中配置，但您不需要更改该文件。创建自己的.ini文件，其中只包含您需要定制的查询，并将该.ini文件传递给VCardDB构造函数。VCardDB将使用VCardDBQueries.ini中的默认查询来处理无法在您的自定义文件中找到的内容。从default.ini文件开始工作，以确保预期的返回列和命名参数匹配。在此约束下，可以连接/拆分表或调用存储过程，以便将VCardDB集成到更大的应用程序架构中。

您的项目的build.xml

如果您将此库包含在更大的项目中，您将需要一个build.xml来告诉phing如何自动化项目任务。VCard-Tools提供了一个构建文件，您可以将其包含在build.xml中以自动化使用VCard-Tools所需的数据库部分。为此，您在build.xml中使用导入任务

<property name="vcardtools.dir" value="${vendor.dir}/evought/vcard-tools"/>
<import file="${vcardtools.dir}/phingDBTasks.xml"/>

导入将加载我们提供的xml文件，为您设置属性和任务，例如我们在上面的数据库设置部分中提到的createUnitDB任务。因此，您的项目的build.xml可能看起来像这样

<project name="project" default="dist" basedir="."
     description="Project including VCard-Tools">
  <!-- get dependencies from Composer -->
  <php expression="include('vendor/autoload.php')"/>

  <!-- set global properties for this build -->
  <property name="src.dir" value="src"/>
  <property name="test.dir" value="tests"/>
  <property name="dist.dir"  value="dist"/>
  <property name="doc.dir"  value="docs"/>
  <property name="apidoc.dir" value="docs/api"/>
  <property name="vendor.dir" value="vendor"/>
  <property name="vendor.bin.dir" value="${vendor.dir}/bin"/>
  <property name="reports.dir" value="reports"/>

  <!-- per-user properties for overriding settings, such as db connection -->
  <property file="${env.USER}.properties"/>

  <property name="vcardtools.dir" value="${vendor.dir}/evought/vcard-tools"/>
  <import file="${vcardtools.dir}/phingDBTasks.xml"/>

  <!-- Your project's other task definitions -->
</project>

您可以直接从vendor/evought/vcard-tools复制db.properties、database.php.in和phinx.yml.in到您的项目目录中，并按照数据库设置部分中描述的方式进行编辑。已努力命名所有VCard-Tools属性和任务，以便它们不会与项目可能需要的任何其他数据库任务冲突。然后，您可以定义生产数据库的自定义设置，连接到其他数据库，甚至创建自己的迁移（重命名我们的phinx.yml文件，创建自己的，并使用phinx的-c选项选择要使用的一个）。如果您需要大量自定义行为，您可以选择不包含phingDBTasks.xml并定义自己的phing任务，从我们的示例中剪切和粘贴。当然，您也可以根据需要复制和修改VCard-Tools build.xml文件的部分。

#文档和示例#

除了代码注释之外，使用类的最佳资源之一是测试用例。目前还没有公开可见的类演示。

API文档由doc phing任务生成

$ phing doc

并将放置在docs/api中。cleanDocs将删除生成的文档。

单元测试

运行单元测试需要安装PhpUnit。如果它位于路径中，可以使用test phing任务运行完整的测试套件

$ phing test

此操作还会在 reports/ 目录下生成测试覆盖率报告。

注意：如果你有失败的测试用例，请参阅问题 #59。

提供了一个 phpunit.xml 文件，可以从命令行手动运行测试。

$ phpunit tests/VCardTests.php

如果测试实际失败，应该能够正常工作并提供更详细的输出。我还经常在 NetBeans IDE 下运行测试。如果你将项目配置为使用 phpunit 的 bootstrap.php（项目->属性->测试），则在 NetBeans 下运行整个测试套件或单个测试将可以顺利运行。

持续集成服务器

VCard-Tools 使用 Travis 持续集成服务器。这意味着每次将更改提交到这个库时，Travis CI 都会检出更改的干净副本，构建它们，设置数据库，并运行单元测试套件。实际上，它会多次运行此过程，以使用不同版本的 PHP 运行测试。这个过程有助于确保提交的更改不会破坏现有测试，并且不会隐藏开发工作站的特殊错误。

如果构建失败，开发者会收到一封焦急的电子邮件，告知他们修复问题。