Skip to content

Latest commit

 

History

History
135 lines (123 loc) · 13.5 KB

MANIFEST.md

File metadata and controls

135 lines (123 loc) · 13.5 KB
Raw

Manifest

This file intends to explain the way the files are generated and why. Moreover, it gives tips on how the generated classes should be used.

TL;DR

When everything goes well, you must end up with the folders and files structures as below (basic usage):

{destination}
|──── src                 # can be removed if necessary, read src-dirname option
|─────|──── ArrayType     # generated only if Array Structs are declared
|─────|──── | ....
      |──── EnumType      # generated only if Enumerations are declared
      |─────| ....
      |──── ServiceType   # contains ServiceType classes
      |─────| ....
      |──── StructType    # contains Struct classes, used to construct request parameters
      |─────| ....
      |──── ClassMap.php  # generated in order to map generated Struct classes to Soap Structs
|──── vendor              # generated by composer if standalone option is enabled, true by default
|──── | ....
|──── composer.json       # generated if standalone option is enabled, true by default
|──── composer.lock       # generated by composer if standalone option is enabled, true by default
|──── tutorial.php        # generated if gentutorial option is enabled, true by default

Read next to learn about the classes goal, their usage and how to customize them.

PHP files and classes

  • Files and classes are generated using our own PhpGenerator library. The PhpGenerator is independent and not tweaked specifically for this project, it can be used freely and for any purpose.
  • Classes are generated under the src folder within the destination folder based on their category and their namespace.
  • Classes are not namespaced by default.
  • Classes are named after the element name all with respecting the PHP class naming constraints. Generated names can be prefixed and suffixed if needed.
  • Classes are generated with predefined comments and annotations. You can add your proper annotations.
  • Classes require PHP >= 7.4 as of PackageGenerator >= 4.0.

Struct classes

  • Classes represent any parameter that can be sent to the Soap server within the Soap request as soon as the parameter is not a scalar value.
  • Classes are generated under the src/StructType folder by default.
  • Classes extend the AbstractStructBase class from the PackageBase dependency in order to benefit from generic methods.
  • Struct properties are:
    • Named after the element name all with respecting the PHP class property naming constraints.
    • Typed based on their definition.
    • null by default, if not an array and not detected as required.
    • With their proper setter and getter. You are strongly encouraged to always use the setter for the following reasons:
      • Chained calls: The setters are fluent (return the current object instance), so you can chain the calls such as $object->setFirstname('Bob')->setLastname('Barfield').
      • Parameter type: The setter parameter is typed based on the element type declaration. This way you're assured that the XML request will be well-generated.
      • Validation rules: The setter contains validation rules based on the element declaration avoiding you from making a mistake that would lead to a wrong XML request. An InvalidArgumentException exception is thrown with an explicit message if you made a mistake.
      • Removable property: The setter removes the property from the object if it is declared as removable from the request (nillable=true + minOccurs=0). Passing null or an empty array to the setter removes the property from the object thus the XML request does not contain the element, which is often required by the Soap Server which handles the request.
    • Enhanced with methods:
      • Array property: If the property is detected as an array, you end up with a fluent-typed addTo{PropertyName}(?{propertyType} $item) method.
      • List property: If the property is detected as a list of value (xs:list):
        • The setter allows you to pass either a string or an array.
        • If the values are restricted to an enumeration of values, a validation rule is applied on the parameter value to ensure you pass the right values.
        • If you pass an array, the values are concatenated into a string with a space within each value.
      • XML Any (<xs:any/>): If the property is detected as an XML string:
        • The setter allows you to pass either a string or a DOMDocument object that is converted to string for the XML request.
        • The getter is adapted (get{PropertyName}(bool $asDomDocument = false)) and allows you to get a DOMDocument object from the XML string of the property returned by the XML response.

StructArray classes

  • Classes are an extension of Struct Classes and are generated with the same benefits.
  • Classes represent an element that contains only one array-type property.
  • Classes are generated under the src/ArrayType folder by default.
  • Classes extend the AbstractStructArrayBase class from the PackageBase dependency in order to benefit from generic methods.
  • Classes are empowered thanks to AbstractStructArrayBase class:
    • They are Traversable, Countable and they also implement the ArrayAccess interface.
    • They always contain the getAttributeName(): string method that returns the property name that is an array.
  • Classes contain return-typed methods to ease the manipulation of the array property (in addition to the AbstractStructArrayBase methods):
    • current(): ?{childElementType}: returns the current iteration element.
    • item($index): ?{childElementType}: returns the item at the given position (alias of offsetGet).
    • first(): ?{childElementType}: returns the first element.
    • last(): ?{childElementType}: returns the last element.
    • offsetGet($offset): ?{childElementType}: returns the last element.
    • add(?{childElementType} $item): self: adds the item to the current array property.

StructEnum classes

  • Classes represent any enumeration declared by the WSDL. They contain constants that should be used to define the value of a Struct property marked as an enumeration value or enumeration-typed values within an array-typed property.
  • Classes are generated under the src/StructEnumType folder by default.
  • Classes extend the AbstractStructEnumBase class from the PackageBase dependency in order to benefit from generic methods.
  • Classes are empowered thanks to AbstractStructEnumBase class:
    • They always contain the getValidValues(): array method that returns the constants values contained by the class.
    • The valueIsValid($value): bool method allows checking if the value is a valid value declared by the enumeration (used by a validation rule within a Struct's setter).

Service classes

  • Classes are generated in order to gather Soap operations named similarly in one or many classes based on your choice.
  • Classes are generated under the src/ServiceType folder by default.
  • Classes extend the AbstractSoapClientBase class from the PackageBase dependency in order to benefit from generic methods.
  • Classes contain custom method(s) in order to define the Soap Header(s) based on what is defined in the WSDL.
    • Methods are named setSoapHeader{SoapHeaderName}({SoapHeaderType} ${SoapHeaderName}, string $namespace = '{soapHeadernamespace}'}, bool $mustUnderstand = false, ?string $actor = null).
  • Classes contain one method per Soap operation named after the operation name all with respecting the PHP method naming constraints. The method returns:
    • false:
      • This means there is an error with the request or the Soap Server that has triggered a SoapFault (be sure that WsdlToPhp\PackageBase\AbstractSoapClientBase::WSDL_TRACE=true).
      • Use getLastError(string $methodName): ?SoapFault to get the SoapFault thrown when the method cas called.
      • $methodName has the form {fully qualified classname}::{__FUNCTION__} aka __METHOD__.
    • A {returnType} object/value result:
      • The getResult method is annotated with the @return annotation listing all the possible return types.
      • Be sure to check the result type before using the returned result.

ClassMap class

  • ClassMap class is generated under the src folder.
  • ClassMap class has a unique-final-static method named get which returns the array to be used as the classmap option for the SoapClient class.

composer.json

  • composer.json file is generated when standalone option is enabled under the destination folder.
  • composer.json name can be set.
  • composer.json settings can be customized.

tutorial.php

  • tutorial.php file is generated under the destination folder if it is enabled (true by default).
  • tutorial.php file is a boilerplate demonstrating how to instantiate each generated ServiceType class.
  • tutorial.php demonstrates how to call each setSoapHeader{SoapHeaderName} method.
  • tutorial.php demonstrates how to call each operation generated per ServiceType class.