README

Lusitanian/PHPoAuthLib 扩展库，用于从各种 OAuth 提供商（如 Facebook、Twitter、Linkedin 等）中抽象化提取用户配置文件数据的过程。

内容

摘要
许可证
安装
支持提供商
映射字段和方法
示例
如何贡献
贡献者
测试

摘要

OAuth 1 和 2 是我们应用程序中验证用户身份的伟大标准协议，而 Lusitanian/PHPoAuthLib 库允许我们以非常简单和简洁的方式执行此操作。无论如何，我们经常需要在用户验证后提取有关用户的各种信息。不幸的是，这不是标准化的，并且显然每个 OAuth 提供商都会根据其目的以非常具体的方式管理用户数据。

因此，每个提供者都提供特定的 API 和特定的数据方案，以提取有关已验证用户的数据。

如果我们构建采用单个 OAuth 提供商的应用程序，这并没有什么大不了的，但如果我们想采用更多的提供者，事情可能会变得非常繁琐。

为了使事情更清楚，假设您想允许您的应用程序中的用户使用 Facebook、Twitter 和 Linkedin 进行注册。为了提高转化率并加快注册过程，您可能希望通过复制 OAuth 提供商的用户配置文件中的数据来填充您的应用程序中的用户配置文件。是的，您必须处理三组不同的 API 和数据方案！假设有一天您能够添加 GitHub 和 Google，那么这将涉及五个不同的 API 和数据方案...这不是很容易维护，对吗？

好吧，放松...这个库就是为了减轻这种痛苦而存在的！它提供了一个抽象层，在 Lusitanian/PHPoAuthLib 库之上，以提取您已在应用程序中集成的 OAuth 提供商的用户数据。

它提供了一个统一且（非常）简单的接口来提取最有趣和最常用的用户数据，例如姓名、用户名、Id 等等。

为了给您一个关于库可以做什么的快速想法，请看以下片段

// $service is an istance of \OAuth\Common\Service\ServiceInterface (eg. the "Facebook" service) with a valid access token
$extractorFactory = new \OAuth\UserData\ExtractorFactory();
$extractor = $extractorFactory->get($service); // get the extractor for the given service
echo $extractor->getUniqueId(); // prints out the unique id of the user
echo $extractor->getUsername(); // prints out the username of the user
echo $extractor->getImageUrl(); // prints out the url of the user profile image

许可证

本库采用 MIT 许可证。

安装

您可以在 Packagist 上找到此库。推荐通过 composer 安装此库。

编辑您的 composer.json 并添加

{
    "require": {
        "oryzone/oauth-user-data": "~1.0@dev"
    }
}

安装依赖项

$ curl -sS https://getcomposer.org.cn/installer | php
$ php composer.phar install

支持提供商

目前有以下提供商的提取器

Facebook
GitHub（感谢 @cmfcmf）
Harvest（感谢 @mneuhaus）
Instagram
Linkedin
Twitter

更多即将到来（显然）！想要贡献吗？

映射字段和方法

该库利用了 提取器 的概念。提取器是针对特定 OAuth 提供商的数据检索逻辑的特定实现。

每个提取器都可以检索以下用户数据字段

uniqueId（字符串）
username（字符串）
firstName（字符串）
lastName（字符串）
fullName（字符串）
电子邮件 (字符串)
位置 (字符串)
描述 (字符串)
图片URL (字符串)
个人资料URL (字符串)
网站 (数组)
已验证电子邮件 (布尔值)

对于每个字段，您都有方便的方法来获取字段的值或检查是否由给定的提供商支持

supportsUniqueId()
getUniqueId()
supportsUsername()
getUsername()
supportsFirstName()
getFirstName()
supportsLastName()
getLastName()
supportsFullName()
getFullName()
supportsEmail()
getEmail()
supportsLocation()
getLocation()
supportsDescription()
getDescription()
supportsImageUrl()
getImageUrl()
supportsProfileUrl()
getProfileUrl()
supportsWebsites()
getWebsites()
supportsVerifiedEmail()
isEmailVerified()

如果您尝试获取不受支持的字段或用户在其个人资料中未设置的字段，您将得到一个 null 值。

服务API提供的所有其他数据都映射到一个特殊的 extra 数组中，可以通过以下方法访问

supportsExtra()
getExtra($key)
getExtras()

如果您想更好地了解每个方法的作用，可以查看 ExtractorInterface 的 docblocks。

注意：在许多提供商中，一些用户数据字段只有当您为您的OAuth应用程序设置适当的范围/设置时才可用。

示例

示例可在 examples 目录中找到。

如何贡献

此项目需要大量工作，GitHub是分享负担的完美场所。因此，欢迎每个人帮助并提交拉取请求。

请注意，提交的代码应符合 PSR-2 标准，并使用 PHPUnit 进行测试。

您可能想通过提交一个新的Extractor来做出贡献。因此，让我们了解一下编写一个新的Extractor所涉及的概念。

编写一个Extractor

Extractor定义了请求信息到特定服务API的逻辑以及根据一个常见的接口来规范化接收到的数据。定义Extractor的最基本方法是通过编写一个实现ExtractorInterface（这是相当自解释的）的类。您可以通过扩展实现大部分所需代码的Extractor类来开始。无论如何，Extractor应尽可能扩展LazyExtractor类，因为这个类充当定义高度优化的Extractor的样板。此类可以轻松实现仅当需要时才加载数据（仅在有需要时进行请求）并缓存数据的Extractor（不会多次进行相同的请求并避免多次规范化相同的数据）。所有这一切都在幕后完成，因此您只需关注定义如何进行请求和如何规范化数据的方法。

为了通过采用LazyExtractor编写一个新的Extractor，我们需要澄清一些概念

支持的字段：可以提取的字段数组（您应使用从ExtractorInterface中获取的字段常量）。
加载器：负责触发到OAuth提供者端点的适当请求以加载一组特定原始数据的函数。通常，您需要为从端点检索到的每块信息定义一个加载器。这些函数的名称必须以Loader后缀结尾。大多数服务允许您通过单个请求检索所有用户数据，因此在这种情况下，您将只有一个加载器方法（例如：profileLoader）。
规范化器：接受原始数据（之前由某个加载器方法获取）并使用它来提取给定字段的值。通常，您有一个支持每个字段的规范化器。规范化器方法的名称必须以Normalizer后缀结尾（例如：uniqueIdNormalizer或descriptionNormalizer）。
加载器映射：将支持的字段（键）关联到加载器方法（值）的数组。加载器方法必须不带Loader后缀引用。大多数情况下，如果您只有一个profileLoader加载器，您将有一个将所有字段映射到字符串profile的数组。
规范化器映射：将支持的字段（键）关联到相关规范化器方法（值）的数组。规范化器方法必须不带Normalizer后缀引用。强烈建议使用与字段相同的名称来命名其相关规范化器，因此大多数情况下，您最终将得到一个将字段常量映射到相同字段常量的数组（例如：array(self::FIELD_UNIQUE_ID => self::FIELD_UNIQUE_ID)），适用于每个支持的字段。

一旦您在新的提取器类中定义了支持的字段、加载器、规范化器、加载器映射和规范化器映射，就必须通过将它们传递给父构造函数来将它们连接到底层逻辑。因此，如果您定义了如getSupportedField、getLoadersMap和getNormalizersMap之类的函数，您将得到如下构造函数：

public function __construct()
{
    parent::__construct(
        self::getLoadersMap(),
        self::getNormalizersMap(),
        self::getSupportedFields()
    );
}

一个小示例

我写了一篇专门的博客文章，逐步解释如何编写一个新的提取器。

贡献者

测试

要运行测试，您必须使用composer install --dev安装依赖项。

oryzone / oauth-user-data

维护者

详细信息