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属性的 对象，而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();。

测试套件

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

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

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

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

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