README

本包的目的是为了提供方便访问XML Soccer API，用于检索足球（足球）比赛的历史和实时数据。

需求

PHP 7.0+、Composer、SimpleXML

安装

该包旨在与使用Composer作为依赖管理器的项目集成。要将此包添加到项目中，请导航到项目的根目录并执行 composer require petercoles/xml-soccer。

基本用法

为了进行API请求，您需要一个API密钥。XML Soccer慷慨地提供了免费的演示API密钥，以便您可以测试该服务。您可以在这里获取一个。

一旦您有了API密钥，请实例化一个Api客户端实例，并将密钥作为第一个参数传递。对于对演示系统（例如，如果您还没有付费订阅并且正在使用免费API密钥或正在测试并希望有更慷慨的API限制）的请求，请将第二个参数设置为true。要访问完整服务，只需省略第二个参数。例如

use PeterColes\XmlSoccer\ApiClient;

class MyRequest()
{
    ...

    public function getLiveData()
    {
        $client = new ApiClient('YOUR_API_KEY_HERE', true));  // for the demo service

        $response = $client->getLiveScore()->get();
    }

    ...
}

这将返回从XMLSoccer服务接收的原始数据，以纯XML形式。

可用的方法列表的完整列表可以在XML Soccer服务描述中找到。有关服务的更多通用文档也可用。

许多方法需要参数。这些参数以关联数组的形式传递。例如

$client->getNextMatchOddsByLeague([ 'league' => 3 ]);
$client->GetFixturesByLeagueAndSeason([ 'league' => 3, 'seasonDateString' => '0506' ]);

响应转换

如果您喜欢手动解析XML数据，则可能只需要使用 ->get() 方法 ... 随意跳过本节的其余部分。

或者，此包提供了三种更友好的方式来接收响应。

SimpleXML对象

使用get()方法的替代方案xml()将导致响应转换为SimpleXMLElement对象。以下是如何迭代这些对象的示例

try {
    $xml = $client->getLiveScore()->xml();
} catch(\Exception $e) {
    exit('XML Soccer Exception: '.$e->getMessage());
}

foreach ($xml->Match as $match) {
    echo "$match->HomeTeam v $match->AwayTeam : $match->HomeGoals-$match->AwayGoals";
}

PHP对象

如果您不是XML的忠实粉丝，没有问题。使用object()方法将响应转换为PHP对象。例如，$object = $client->getLiveScore()->object();。

大多数响应对象是属性简单列表。因此，getAllLeagues将返回一个包含League属性的对象，该属性又包含一个数组，其中包含一个描述一个联赛（即比赛，包括杯赛和混合赛，如欧洲冠军联赛）的对象。

object(stdClass) {
    ["League"]=>
    array(n) {
        [0]=>
        object(stdClass) {
            ["Id"] => "1",
            ["Name"] => "English Premier League",
            {"Country"] => "England",
            ...
            ["IsCup"] => "false"
        },
        ...
        [n]=>
        object {
            ["Id"] => "57",
            ["Name"] => "Ligaat AL",
            {"Country"] => "Isreal",
            ...
            ["IsCup"] => "false"
        }
    }
    ["AccountInformation"]=> string "Blah."
}

但是，例如从Live Score或Historic Fixtures检索的比赛数据具有更复杂的结构，包含有关进球、黄牌、替补和球员的信息，所有这些信息都压缩在默认响应字符串中，您必须将其拆包才能理解它们。

本包也处理这一点，因此当转换为对象时，此XML进球字符串

<HomeGoalDetails>50': Riccardo Orsolini;38': Andrea Favilli;4':Own A N Other;</HomeGoalDetails>

将返回为

...
    ["HomeGoalDetails"]=>
    array(3) {
        [0]=>
        object(stdClass) {
            ["Minute"] => 50,
            ["Player"] => "Riccardo Orsolini",
            ["Own"] => false
        },
        [1]=>
        object(stdClass) {
            ["Minute"] => 38,
            ["Player"] => "Andrea Favilli",
            ["Own"] => false
        },
        [2]=>
        object(stdClass) {
            ["Minute"] => 4,
            ["Player"] => "A N Othe",
            ["Own"] => true
        }
...

其中的数据可以通过这种方式访问

foreach ($object->Match[23]->HomeGoalDetails as $goal) {
    echo $goal->Minute;   
    echo $goal->Player;   
    echo $goal->Own;   
}

... 对于黄牌、替补和球员列表也是如此。

请注意，对于比赛数据，每个值都转换为适当的类型，即数字数据为整数，适当的地方为布尔值，而不是默认为字符串。

JSON

如果您希望以JSON格式接收对象，即JSON编码的字符串，这对于缓存或传递到浏览器端应用程序可能很有用，那么请使用json()方法，例如：$json = $client->getLiveScore()->json();。

升级

在版本1中，数据是通过调用类似于getLiveScore()的XMLSoccer方法返回的。然而，在版本2中，数据是通过get()、xml()、object()或json()（参见上面的描述）返回的，具体取决于您的喜好。

如果您在版本1中使用object()或json()，只需将此调用移至请求的末尾，例如：$json = $client->json()->getLiveScore();变为$json = $client->getLiveScore()->json();。

如果您没有使用任何转换，那么只需追加xml()以返回一个简单的simpleXML对象，如版本1中的默认设置，例如：$xml = $client->getLiveScore();变为$xml = $client->getLiveScore()->xml();。

测试套件

提供了四套测试，包括一般单元测试，它简单地检查客户端是否按预期运行；集成测试，它（主要）连接到XML Soccer演示服务，并确认请求已发送且响应符合预期；以及PHP对象和JSON转换的特殊测试套件。

在运行任何测试套件之前，请将phpunit.xml.dist复制到phpunit.xml。如果您想运行集成测试，还需要编辑此文件，在指定的位置插入您的XML Soccer API密钥。这个新文件将被排除在任何git提交之外，这样即使您向此包做出公开贡献，您的API密钥也将保持保密。

要单独运行单元测试，只需执行vendor/bin/phpunit tests/UnitTest。同样，要单独运行集成测试，请执行vendor/bin/phpunit tests/IntegrationTest，或者要运行所有内容，只需执行vendor/bin/phpunit。

如果您只有演示服务密钥，那么集成测试中的一个可能失败，因为它只能针对实时服务运行。如果发生这种情况，添加--exclude-group live标志以抑制这个不重要的测试。

实时和演示API都被限制以避免对服务器的过度负载。大多数对演示API的调用需要在请求之间有5秒的间隔（对于实时系统，间隔更大，取决于发送的具体请求）。集成测试套件在运行每个受影响的测试之前强制执行此延迟，因此如果您运行它，请预期执行过程中会有5秒的暂停。

petercoles / xml-soccer

维护者

详细信息