README

这是一个Wolfram|Alpha APIs (V2)的PHP包装器，Wolfram|Alpha是由Wolfram Research开发的计算知识引擎。

我制作它是因为官方网站上的版本缺少一些我认为必要的和有用的部分和方法。

在这个README文件中，我将解释如何在PHP项目中设置和使用它。

简介

为了使用Wolfram|Alpha Engine API，您必须有一个AppID。要获得AppID，您必须在Wolfram|Alpha开发者门户注册为开发者。这是一个非常简单的流程：注册后，您只需创建一个新应用，指定一个名称和描述。

实际上，您每月可以免费使用2000次API调用。如果您不喜欢这个限制，请联系Wolfram以找到满足您需求的解决方案。

如何安装包装器

安装Wolfram|Alpha PHP包装器非常简单。在您的项目中，只需将以下内容添加到您的composer.json文件中的require元素。

{
    "require": {
        "francescomalatesta/wolframalpha": "dev-master"
    }
}

如果您不知道Composer是什么，现在是时候解决这个问题了！ :)

只需执行composer install，您就完成了：现在让我们转到Engine类。

Engine

Engine类是您向Wolfram|Alpha Engine发送查询的入口点。您可以使用以下简单语法初始化它。

$engine = new WolframAlpha\Engine('YOUR_APP_ID');

没有了。

process()

您可以使用此方法向引擎发送查询。以下是签名。

public function process($query, $assumptions = array(), $formats = array('image', 'plaintext'))

在$query中，您需要放入要发送的查询（例如："谁在购买《天堂阶梯》？"）。

在$assumptions中，您可以指定一个或多个要应用于查询的假设。如果您不知道它们，请查看API文档和本README文件的末尾。

在$formats中，您将放入请求输出的所需格式。默认情况下，您有image和plaintext。您还可以使用：html、cell、sound和minput。

这里有一个非常简单的调用示例。

// sending a query with the 'e' character
$result = $engine->process('e');

就是这样。

有时查询可能需要很长时间才能执行，因此您可能会在发送请求之前验证查询。Engine类有一个validate()方法可以帮助您。

以下是签名。

public function validate($query, $assumptions = array())

重要：process()方法返回一个QueryResult对象。validate()方法返回一个ValidateQueryResult对象。请继续阅读以了解更多信息。

重要2： Wolfram|Alpha引擎的输出数据格式是XML。我使用了PHP的SimpleXML来处理XML节点。如果您也需要处理XML，除了Image类外，每个类都有一个parsedXml属性，是一个SimpleXMLElement实例。这意味着，如果您愿意，您可以在任何地方处理XML，无论是否使用我们的类。

// output echo
echo $result->parsedXml->asXML();

// saving XML output on a file
$result->parsedXML->asXML($fileName);

查询结果

QueryResult类包含了您处理响应所需的一切。首先，让我们看看基本方法。

属性

您可以通过指定属性来访问每个查询结果的属性。

var_dump($result->success);

我使用了魔术方法来添加更简单、更实用的语法。您可以在文档参考页面上找到每个属性。

有用方法

这不仅仅是属性。我还添加了一些有用的方法来控制警告、错误等。

错误和警告

在Wolfram|Alpha中，您可能会在输出中遇到许多问题。正如您所想象的那样，警告与错误是不同的。

实际上，警告不会中断程序。错误会。

使用hasWarnings()和getWarnings()，您可以在代码中处理警告。以下是一个示例。

if($result->hasWarnings())
{
    foreach($result->getWarnings() as $name => $message)
    {
        echo $name: . ' ' . $message;
    }
}

hasWarnings()方法返回一个简单的布尔值。getWarnings()方法返回一个关联数组，格式为$name => $message。

getError()

对于警告，您刚才看到的方法同样适用于错误，但有一点区别...在一个Wolfram|Alpha引擎请求中，错误始终只有一个，在单个查询中。

以下是一个示例。语法应该很容易理解。

if($result->hasError())
{
    echo 'Error ' . $result->getError()['code'] . ': ' . $result->getError()['message'];
}

hasProblems()

另一个“检查”方法是hasProblems()，它用于仅控制queryresult XML项的success属性的状态。它返回一个布尔值。

if($result->hasProblems())
{
    // deal with it...
}

技巧和建议

您知道，Wolfram|Alpha引擎是一个非常优秀的人。它不仅为您做一些肮脏的数学和数据处理，有时还会建议您如果写错了什么。

技巧用于您输入了错误的内容，而引擎没有理解它。《em>getTips()是一个方法，它返回一个字符串数组，您可以使用它这样

if(count($result->getTips()) > 0)
{
    foreach($result->getTips() as $tip)
    {
        echo 'Tip: ' . $tip;
    }
}

建议更具体一些。如果技巧给您提供了使用引擎的正确建议，那么建议就像“哦，你写了Chucago，但我想你可能指的是Chicago！”

您可以使用getSuggestions()方法查看建议。

if(count($result->getSuggestions()) > 0)
{
    foreach($result->getSuggestions() as $suggestion)
    {
        echo 'Suggestion: ' . $suggestion;
    }
}

Pod和子Pod

在Wolfram|Alpha的世界里，结果是有组织的Pod。您可以将它们视为构成最终结果的“元素”。每个Pod还有一个或多个子Pod。子Pod是结果的“单一单位”。它可以是文本，也可以是图像（等等）。

使用包装器，读取请求的结果非常简单。

首先，您可以使用pods属性访问您的Pod。

$pods = $result->pods;

注意：如果查询没有Pod，$result->pods将是null。如果需要，请使用isset()进行检查。

$pods是PodsCollection类的实例。它是一个特殊对象，因为您可以像处理数组一样处理它（多亏了ArrayAccess和Countable接口），但它还具有其他方法。

让我们举个例子

// counting result pods
echo count($result->pods);

// access a specific Pod
var_dump($result->pods['Input']);

然而，有时迭代数组直到找到您需要的Pod并不那么有用。PodsCollection类还有一些实用方法，可以让代码更具表现力。这些方法是has()和find()。

if($pods->has('Input'))
{
    $inputPod = $pods->find('input');
}

如您想象的那样，has()函数接受所需Pod的ID作为输入，如果Pod存在则返回true，否则返回false。 find()函数接受相同的参数作为输入，如果存在则返回Pod类的实例，否则返回null。

然而，谈到Pods，一个PodsCollection是一个Pod实例的集合。

Pod类

Pod类是对结果Pod的抽象，您可以在应用程序中轻松使用。您可以像访问属性一样访问每个Pod属性

echo $pod->title;
echo $pod->id;
echo $pod->position;

...等等。

您可以使用以下方法访问您的子Pod

$pod->subpods;

subpods是一个简单的Subpod对象数组。

Subpod类

Pod有其自己的子Pod。子Pod有其自己的值。

您可以像这样访问您的子Pod值

// access to a simple element
echo $subpod->plaintext;

此外，您在子Pod中也可能得到一个图像作为结果。在这种情况下，图像数据将被包裹在一个Image对象中。

$image = $subpod->img;

echo $image->src;

图像可用的属性有：src、width、height、title和alt。

提示：当您想要处理一个子Pod值但不确定其存在时，使用简单的

if(isset($subpod->plaintext))
{
    // ready to go!
}

假设

假设是Wolfram|Alpha告诉您“嘿，我有一些结果，但您问我的意思可能有多种不同的解释！”的一种方式。请记住，这与“建议”是不同的概念。

对于Pods，您可以通过以下方式访问（如果存在）查询的假设

$assumptions = $result->assumptions;

注意：如果查询没有假设，$result->assumptions将是null。如有必要，请使用isset()进行检查。

$result->assumptions将是一个AssumptionsCollection类的实例。对于PodsCollection类也是如此：您可以像数组一样遍历它，并使用简单的count()方法计算其元素。

foreach($assumptions as $type => $assumption)
{
    echo 'Type: ' . $type;
    
    // deal with assumptions here...
}

您还可以使用与之前在PodsCollection中看到相同的has()和find()方法。

if($assumptions->has('Clash'))
{
    $assumption = $assumptions->find('Clash');
    
    // your awesome code goes here
}

AssumptionsCollection中的每个元素都将是一个Assumption类的实例。

假设和假设值

使用这些类处理假设相当容易。首先，您可以像访问对象属性一样访问假设属性

echo $assumption->type;

同样，一个Pod有其自己的子Pod，一个假设有其自己的假设值。您可以在$assumption->values中找到它们，作为一个包含AssumptionValue实例的关联数组，其中键是值的名称。

属性访问也是一样，以下是一个示例

$assumptionValue = $assumption->values['Character'];

echo $assumptionValue->desc;
// outputs: a character

echo $assumptionValue->input;
// outputs: *C.eta-_*Character-

注意：一旦您有了假设值输入，您就可以将$assumptionValue->input中包含的字符串作为Engine类process()方法中的$assumptions数组的元素，来指定一个新的请求。

验证查询结果

有时，使用Wolfram|Alpha Engine的完整过程可能需要很长时间。您可能发现知道如果想要，只需验证一个查询而不是将其提交给引擎并知道会发生什么是有用的。

Engine类有一个validate方法，可以解决这个问题。就像您之前看到的process()方法一样，只是没有一些参数。您可以指定一些假设，如果需要的话。

validate()方法将返回一个ValidateQueryResult实例，它比QueryResult对象要轻一些，因为它只包含警告、错误数据和假设。

注意：使用validate()方法并不是为了节省一些API调用，而是为了处理时间。所以，如果您想验证一个查询然后处理它，这将花费您两个API调用。

其他注意事项

我们在这里结束了！这是我第一次在Github上的“严肃”项目。所以，对于每个反馈、错误或您认为有趣的事情，请与我联系。

在“tests”文件夹中，你可以找到...当然，测试。然而，错误总是会发生。问题是你的朋友！

如果你想直接联系我，请在twitter上搜索@malatestafra，或者也许可以在Facebook上添加我。如果你不喜欢社交网络，发送电子邮件到francescomalatesta(at)live(dot)it也是可以的：）