README

该 vCard 库提供了创建 vCard (RFC 6350) 字符串的能力。

创建 vCard 文件

该库允许以面向对象的方式创建 vCard。

库提供类常量以提供代码补全并提高代码可读性。

要创建 vCard，创建一个新的 Vcard 对象然后向其中添加属性；支持具有相同名称的多个属性。

由分号字符（例如，N 和 ADR）分隔的多个字段可以指定为数组；空字段必须给出。如果属性字段是一个列表，它也可以指定为数组。

以下等价

->addProperty(
    Vcard::PROPERTY_N,
    'Perreault;Simon;;;ing. jr,M.Sc.'
)

->addProperty(
    Vcard::PROPERTY_N,
    [
        'Perreault',
        'Simon',
        '',
        '',
        'ing. jr,M.Sc.'
    ]
)

将属性参数作为数组提供，其中键是参数名称（提示：使用类常量）和值是值；如果值是列表，它也可以指定为数组。

以下等价

[
    Vcard::PARAMETER_VALUE => Vcard::VALUE_DATA_TYPE_URI,
    Vcard::PARAMETER_TYPE => '"' . Vcard::TYPE_WORK . ',' . Vcard::TYPE_VOICE . '"',
    Vcard::PARAMETER_PREF => 1
]

[
    Vcard::PARAMETER_VALUE => Vcard::VALUE_DATA_TYPE_URI,
    Vcard::PARAMETER_TYPE => [
        Vcard::TYPE_WORK,
        Vcard::TYPE_VOICE
    ],
    Vcard::PARAMETER_PREF => 1
]

最后，调用 Vcard 的 render() 方法。

注意

该库不会进行任何有效性检查；可能创建一个不是有效 vCard 的字符串。

示例

以下示例创建了 RFC6350 的第 8 节中的 vCard。

$vCard = (new Vcard())
    ->addProperty(
        Vcard::PROPERTY_FN,
        'Simon Perreault'
    )
    ->addProperty(
        Vcard::PROPERTY_N,
        [
            'Perreault',
            'Simon',
            '',
            '',
            'ing. jr,M.Sc.'
        ]
    )
    ->addProperty(
        Vcard::PROPERTY_BDAY,
        '--0203'
    )    
    ->addProperty(
        Vcard::PROPERTY_ANNIVERSARY,
        '20090808T1430-0500'
    )
    ->addProperty(
        Vcard::PROPERTY_GENDER,
        Vcard::GENDER_MALE
    )
    ->addProperty(
        Vcard::PROPERTY_LANG,
        'fr',
        [
            Vcard::PARAMETER_PREF => 1
        ]
    )
    ->addProperty(
        Vcard::PROPERTY_LANG,
        'en',
        [
            Vcard::PARAMETER_PREF => 2
        ]
    )
    ->addProperty(
        Vcard::PROPERTY_ORG,
        'Viagenie',
        [
            Vcard::PARAMETER_TYPE => Vcard::TYPE_WORK
        ]
    )
    ->addProperty(
        Vcard::PROPERTY_ADR,
        [
            '',
            'Suite D2-630',
            '2875 Laurier',
            'Quebec',
            'QC',
            'G1V 2M2',
            'Canada'
        ],
        [
            Vcard::PARAMETER_TYPE => Vcard::TYPE_WORK
        ]
    )
    ->addProperty(
        Vcard::PROPERTY_TEL,
        'tel:+1-418-656-9254;ext=102',
        [
            Vcard::PARAMETER_VALUE => Vcard::VALUE_DATA_TYPE_URI,
            Vcard::PARAMETER_TYPE => [
                Vcard::TYPE_WORK,
                Vcard::TYPE_VOICE
            ],
            Vcard::PARAMETER_PREF => 1
        ]
    )
    ->addProperty(
        Vcard::PROPERTY_TEL,
        'tel:+1-418-262-6501',
        [
            Vcard::PARAMETER_VALUE => Vcard::VALUE_DATA_TYPE_URI,
            Vcard::PARAMETER_TYPE => [
                Vcard::TYPE_WORK,
                Vcard::TYPE_CELL,
                Vcard::TYPE_VOICE,
                Vcard::TYPE_VIDEO,
                Vcard::TYPE_TEXT
            ],
        ]
    )
    ->addProperty(
        Vcard::PROPERTY_EMAIL,
        'simon.perreault@viagenie.ca',
        [Vcard::PARAMETER_TYPE => Vcard::TYPE_WORK]
    )
    ->addProperty(
        Vcard::PROPERTY_GEO,
        'geo:46.772673,-71.282945',
        [
            Vcard::PARAMETER_TYPE => Vcard::TYPE_WORK
        ]
    )
    ->addProperty(
        Vcard::PROPERTY_KEY,
        'http://www.viagenie.ca/simon.perreault/simon.asc',
        [
            Vcard::PARAMETER_TYPE => Vcard::TYPE_WORK,
            Vcard::PARAMETER_VALUE => Vcard::VALUE_DATA_TYPE_URI
        ]
    )
    ->addProperty(Vcard::PROPERTY_TZ, '-0500')
    ->addProperty(
        Vcard::PROPERTY_URL,
        'http://nomis80.org',
        [
            Vcard::PARAMETER_TYPE => Vcard::TYPE_HOME
        ]
    )
    ->render()
;

导入 vCard

使用 Vcard 的静态 import() 方法导入 vCard 文件

$vcard = Vcard::import($string);

安装

安装该库的首选方式是使用 composer。

运行以下命令

php composer.phar require --prefer-dist beastbytes/icalendar

或者

"beastbytes/vcard": "^1.0.0"

将其添加到 composer.json 的 'require' 部分。

测试

单元测试

该包使用 PHPUnit 进行测试。要运行测试

./vendor/bin/phpunit

静态分析

代码使用 Psalm 进行静态分析。要运行静态分析

./vendor/bin/psalm

许可

vCard 库是免费软件。它根据 BSD 许可证发布。有关许可证信息，请参阅 LICENSE 文件。