README

用于制作标准化但灵活的webservice类的基礎框架。

版本兼容性

安装

通过Composer

$ composer require czim/laravel-service

除非您使用自动发现，否则请将以下代码行添加到您的config/app.php文件中的providers数组中

    \Czim\Service\Providers\ServiceServiceProvider::class,

需求

要使用SshFileService，您需要安装PHP的libssh2扩展。

使用方法

服务

使用服务的三种基本步骤

1. 实例化一个服务
   • 传递默认值（可选）
   • 传递一个解释器实例（可选）
2. 在服务实例上执行call()

对于简单的SOAP服务，可能如下所示

    // Set up defaults
    $defaults = new \Czim\Service\Requests\ServiceSoapRequestDefaults();

    $defaults->setLocation('http://www.webservicex.net/globalweather.asmx?WSDL')
             ->setOptions([
                 'trace'      => true,
                 'exceptions' => true,
                 'features'   => SOAP_SINGLE_ELEMENT_ARRAYS,
             ]);

    // Instantiate service, with a to-array interpreter
    $service = new SoapService(
        $defaults,
        new \Czim\Service\Interpreters\BasicSoapXmlAsArrayInterpreter()
    );

    // Prepare a specific request
    $request = new ServiceSoapRequest();

    $request->setBody([
        'CityName'    => 'Tokyo',
        'CountryName' => 'Japan',
    ]);

    // Perform the call, which will return a ServiceReponse object
    $response = $service->call('GetWeather', $request);

可用服务

• RestService：用于HTTP REST请求，需要一个ServiceRestRequest对象来传递默认值/请求。
  • 请参阅下面的RestServices部分。
• RestCurlService：与上述类似，但直接使用cURL而不是guzzle
• SoapService：用于SOAP请求，需要一个ServiceSoapRequest对象来传递默认值/请求。
  • 请参阅关于BeSimple的注释。
• FileService：用于检索单个文件的 内容，需要一个ServiceSshRequest对象来传递默认值/请求。
• MultiFileService：用于检索多个文件的内容并将它们的解释合并在一起，需要一个ServiceSshRequest对象来传递默认值/请求。
• SshFileService：类似于MultiFileService，但通过登录SSH服务器来检索文件。请参阅上面的要求。

请参阅这个示例列表以获取更多信息。

RestServices和HTTP方法

在使用RestService时，请注意关于'method'的潜在混淆。服务中的$method参数在call()中不指的是HTTP方法（例如GET、POST等）。为了跨服务兼容性，它用于设置URI路径，因为这最好对应于SOAP调用中的'method'。HTTP方法应在调用之前单独设置在服务上，使用setHttpMethod()。

因此，对/comments/13的DELETE调用可能如下设置

    // Set up the default and base URI for the service
    $defaults = new \Czim\Services\Requests\ServiceRestRequestDefaults();
    $defaults->setLocation('http://base.service.url.com/v1');
    $defaults->setHttpMethod($service::METHOD_DELETE);

    // Instantiate a new service with the defaults
    $service = new \Czim\Service\Services\RestService($defaults);

    // Perform a call to delete comment 13
    $result = $service->call('comments/13');

如果未设置，默认HTTP方法是POST。

或者，可以通过在ServiceRequest参数中设置它来按调用配置HTTP方法，而不会影响默认设置

    // Set up the default and base URI for the service
    $defaults = new \Czim\Services\Requests\ServiceRestRequestDefaults();
    $defaults->setLocation('http://base.service.url.com/v1');

    // Instantiate a new service with the defaults
    $service = new \Czim\Service\Services\RestService($defaults);

    // Create a request object with an HTTP method
    $request = new \Czim\Service\Requests\ServiceRestRequest();
    $request->setHttpMethod($service::METHOD_DELETE);

    // Perform a call to delete comment 13
    $result = $service->call('comments/13', $request);

优先级顺序如下

1. 调用请求中设置的HTTP方法
2. 服务默认请求中设置的HTTP方法
3. 在服务中直接定义的HTTP方法

解释器

服务对每次调用总是返回一个ServiceResponse。响应的内容（主要是通过getData()可访问的数据，但还包括其其他属性）由为服务设置的服务解释器实例确定。服务解释器负责将原始数据解释和转换为你喜欢的（标准化）格式和响应内容。

标准可用解释器

• BasicDefaultInterpreter：设置响应，但不以任何方式操作原始数据
• BasicJsonInterpreter：将带有原始JSON的字符串转换为对象或关联数组
• BasicQueryStringInterpreter：将查询字符串转换为对象或数组
• BasicRawXmlInterpreter：将原始XML字符串转换为SimpleXML对象
• BasicRawXmlAsArrayInterpreter：与上面相同，但转换为关联数组
• BasicSoapXmlInterpreter：生成由SoapClient返回的SimpleXML对象的响应
• BasicSoapXmlAsArrayInterpreter：与上面相同，但转换为关联数组

建议扩展这些或为复杂服务创建自己的解释器。我经常构建使用czim/laravel-dataobject的解释器，将原始数据转换为可验证的特定数据对象。有关提示和有用方法，请参阅AbstractServiceInterpreter源代码。

解释器装饰器

提供了一些解释器的装饰器

• FixXmlNamespacesDecorator：将原始XML中的相对路径命名空间重写为绝对路径，因为某些XML否则可能无法解析（技巧性方法）。
• RemoveXmlNamespacesDecorator：完全从原始XML中删除XML命名空间（技巧性方法）。

它们遵循解释器的标准装饰器模式，因此可以使用以下方式使用

    // Decorate a raw XML interpreter with a namespace removal decorator
    $interpreter = new \Czim\Service\Interpreters\Decorators\RemoveXmlNamespacesDecorator(
        new \Czim\Service\Interpreters\Decorators\BasicRawXmlInterpreter()
    );

    // Inject the interpreter into a new service
    $service = new \Czim\Service\Services\FileService(null, $interpreter);

可以扩展AbstractValidationPreDecorator以轻松设置在装饰的解释器执行业务之前对原始数据的验证。同样，可以扩展AbstractValidationPostDecorator以在解释器处理响应后返回的ServiceResponse对象上进行验证。

服务集合

通过包装多个服务，此包提供了一个ServiceCollection。这是对Illuminate\Support\Collection的简单扩展，只能用于存储ServiceInterface对象。

您可以像设置普通集合一样设置它

    $services = new \Czim\Service\Collections\ServiceCollection();

    // Adding services
    $services->put('service name', $service);

    // Performing calls on a service
    $service->get('service name')
            ->call('someMethod', [ 'param' => 'value' ]);

请注意，在集合上调用get()以获取不存在的服务的值将抛出异常；尝试在其中存储非ServiceInterface的对象也将抛出异常。

注意

BeSimple SoapClient

已设置BeSimpleSoapService服务类以使用BeSimple SoapClient。

要使用它，只需包含此包即可。

composer require "besimple/soap-client"

使用DOMDocument作为SimpleXml的替代方案

当使用DomDocumentBasedXmlParser时，请注意，这将不会返回SimpleXml-类型的对象，而是一个DOMElement。为了合理地使用它，请使用DomObjectToArrayConverter将其转换为数组。这意味着在重新绑定或注入其中之一时，请将它们视为一对。

请注意，DOMDocument方法较慢且使用更多内存。如果没有特定的原因要使用此方法，请坚持使用默认设置。

贡献

请参阅CONTRIBUTING以获取详细信息。

致谢

• Coen Zimmerman
• 所有贡献者

许可协议

MIT许可协议（MIT）。有关更多信息，请参阅许可文件。