Options

Available options

When a command line option name is indicated such as composer-name, you should be aware that it has to be prefixed with --:

$ wsdltophp --composer-name="my/sdk"

Required options
Class naming
- Prefix
- Suffix
Basic authentication
- Login
- Password
Proxy settings
Directories structure
Classes inheritance
Miscellaneous

Required options

WSDL URL or path

This is the absolute url or the absolute/relative path from which the WSDL has to be loaded.

Command line option name: urlorpath
Methods names:
- $options->setOrigin(string $origin)
- $generator->setOptionOrigin(string $origin)

Destination

This is the absolute/relative path where the package has to be generated into.

Command line option name: destination
Methods names:
- $options->setDestination(string $destination)
- $generator->setOptionDestination(string $destination)

Composer name

This option is required in order to generate the composer.json file with a valid composer name. If you do not want to provide a composer name then you MUST set the option standalone to false.

Command line option name: composer-name
Methods names:
- $options->setComposerName(string $composerName)
- $generator->setOptionComposerName(string $composerName)

Force

/!\ Command line only /!\

Without this option, the generator will display all the options that are going to be used to generate your package.

Command line option name: force

The output without this option is such as below:

 Start at 2016-11-30 01:15:12
  Generation not launched, use "--force" option to force generation
  Generator's option file used: /path/to/your/configuration/file.yml
  Used generator's options:
    category: "cat"
    gather_methods: "start"
    generic_constants_names: false
    generate_tutorial_file: true
    add_comments: {"date":"2015-04-22","author":"Me","release":"1.1.0","team":"Dream"}
    namespace_prefix: "My\\Project"
    standalone: true
    validation: true
    struct_class: "\\Std\\Opt\\StructClass"
    struct_array_class: "\\Std\\Opt\\StructArrayClass"
    soap_client_class: "\\Std\\Opt\\SoapClientClass"
    origin: "http:\/\/developer.ebay.com\/webservices\/latest\/ebaySvc.wsdl"
    destination: "\/var\/www\/Api\/"
    src_dirname: "SoapClient"
    prefix: "Api"
    suffix: "Project"
    basic_login: "*******"
    basic_password: "*******"
    proxy_host: "****************************"
    proxy_port: "*******"
    proxy_login: "*******"
    proxy_password: "*******"
    soap_options: []
    composer_name: "wsdltophp\/package"
    composer_settings: {"config":{"disable-tls":true},"require":{"wsdltophp\/wssecurity":"dev-master"}}
    structs_folder: "Structs"
    arrays_folder: "Arrays"
    enums_folder: "Enums"
    services_folder: "Services"
 End at 2016-11-30 01:15:12, duration: 00:00:00

Class naming

Prefix

If you wish to prefix all the generated classes, you can pass the string you want and it will be used to prefix every generated class as it is.

Command line option name: prefix
Methods names:
- $options->setPrefix(string $prefix)
- $generator->setOptionPrefix(string $prefix)

Suffix

If you wish to suffix all the generated classes, you can pass the string you want and it will be used to suffix every generated class as it is.

Command line option name: suffix
Methods names:
- $options->setSuffix(string $suffix)
- $generator->setOptionSuffix(string $suffix)

Basic authentication

These two options are useful only when the WSDL is protected by a Basic HTTP Authentication.

Login

The login that has been provided to you.

Command line option name: login
Methods names:
- $options->setBasicLogin(string $login)
- $generator->setOptionBasicLogin(string $login)

Password

The password that has been provided to you.

Command line option name: password
Methods names:
- $options->setBasicPassword(string $password)
- $generator->setOptionBasicPassword(string $password)

Proxy settings

These options are useful only when you're behind a proxy.

Proxy host

Your proxy host.

Command line option name: proxy-host
Methods names:
- $options->setProxyHost(string $host)
- $generator->setOptionProxyHost(string $host)

Proxy port

Your proxy port (often 3128).

Command line option name: proxy-port
Methods names:
- $options->setProxyPort(string $port)
- $generator->setOptionProxyPort(string $port)

Proxy login

Your proxy login if any.

Command line option name: proxy-login
Methods names:
- $options->setProxyLogin(string $login)
- $generator->setOptionProxyLogin(string $login)

Proxy password

Your proxy password if any.

Command line option name: proxy-password
Methods names:
- $options->setProxyPassword(string $password)
- $generator->setOptionProxyPassword(string $password)

Directories structure

By default, the generated package looks like this:

|-- src
|   |-- ArrayType: classes that contain one property which is an array of items
|   |-- EnumType: classes that only contain constants, enumerations
|   |-- ServiceType: classes that map to the operations
|   |-- StructType: any type that represents a request/response parameter
|   `-- ClassMap.php: the class that defines the mapping used by the SoapClient class
|-- vendor
|   |-- bin
|   |-- composer
|   |-- wsdltophp
|   `-- autoload.php
|-- composer.json
|-- composer.lock
|-- tutorial.php

Every level of this directory structure can be modified using options.

Src dirname

This option defines the name of the root directory src.

If you do not want the src directory in order to have its children directories at the root level, then pass an empty string.

If you want to rename the src directory, then pass the string you want.

Command line option name: src-dirname
- set this option to "/" if you wish to remove the src directory level
Methods names:
- $options->setSrcDirname(string $name)
- $generator->setOptionSrcDirname(string $name)

Structs folder

The Structs are all the classes that map the structs declared in the WSDL/schema of your SOAP Web Service. They contain properties you set to send a request. They also contain all the properties you receive from a response. These classes names are passed to the SoapClient class in order to have full automatic mapping of your parameters and responses.

By default, these classes are generated under the StructType folder (which is used as namespace too).

Command line option name: structs-folder
Methods names:
- $options->setStructsFolder(string $folder)
- $generator->setOptionStructsFolder(string $folder)

Arrays folder

The Arrays are all the classes that map the structs that contain only one property which is an array of any type of value declared in the WSDL/schema of your SOAP Web Service. They are used both in the request and the response. These classes names are passed to the SoapClient class in order to have full automatic mapping of your parameters and responses.

By default, these classes are generated under the ArrayType folder (which is used as namespace too).

Command line option name: arrays-folder
Methods names:
- $options->setArraysFolder(string $folder)
- $generator->setOptionArraysFolder(string $folder)

Enums folder

The Enums are all the classes that contain the enumerations values declared in the WSDL/schema of your SOAP Web Service as constants. They are used to help you define the value awaited by a property of Struct class.

By default, these classes are generated under the EnumType folder (which is used as namespace too).

Command line option name: enums-folder
Methods names:
- $options->setEnumsFolder(string $folder)
- $generator->setOptionEnumsFolder(string $folder)

Services folder

The Services are all the classes that contain operations declared in the WSDL/schema of your SOAP Web Service. Operations are gathered using the beginning or the ending of the operation's name (see Gather operations methods option).

By default, these classes are generated under the ServiceType folder (which is used as namespace too).

Command line option name: services-folder
Methods names:
- $options->setServicesFolder(string $folder)
- $generator->setOptionServicesFolder(string $folder)

Classes inheritance

The generated Struct, Array and Service classes all inherit from base classes which are defined by the PackageBase project. This inheritance is used to ensure the homogeneity of these classes. In addition, they provide additional useful base behaviors.

Struct

By default, Struct classes inherit from the \WsdlToPhp\PackageBase\AbstractStructBase class. If you wish to implement your own base class, please read this section first then provide the fully qualified name of your class to the option.

Command line option name: struct
Methods names:
- $options->setStructClass(string $class)
- $generator->setOptionStructClass(string $class)

StructArray

By default, Struct array classes inherit from the \WsdlToPhp\PackageBase\AbstractStructArrayBase class. If you wish to implement your own base class, please read this section first then provide the fully qualified name of your class to the option.

Command line option name: structarray
Methods names:
- $options->setStructArrayClass(string $class)
- $generator->setOptionStructArraylass(string $class)

SoapClient

By default, Service classes inherit from the \WsdlToPhp\PackageBase\AbstractSoapClientBase class. If you wish to implement your own base class, please read this section first then provide the fully qualified name of your class to the option.

Just to understand when this option is useful, imagine you have a SOAP Web Service which does not handle certain XML tags added by the native PHP SoapClient class. Overridding the native PHP SoapClient class is possible so this option gives you the possibility to do so. In addition to providing you a way to implement generic methods for every Service class, it also provides you a way to use your own SoapClient class implementation. The best way to understand how it works is to take a look to the PackageEws365 project that uses this feature with a custom SoapClient base class (from which every Service class inherit) and a custom SoapClient class (that inherits from the native PHP SoapClient class) in order to remove empty XML tags present in the XML request.

Command line option name: soapclient
Methods names:
- $options->setSoapClientClass(string $class)
- $generator->setOptionSoapClientClass(string $class)

Miscellaneous

Standalone

This option allows you to generate the package with two different perspectives:

standalone (default behaviour): this means the package is generated as an independent project with its own composer.json file. At the end of the generation, the root directory where the package has been generated will contain the composer.json, the composer.lock file and the vendor directory. So you can create a php file, add require_once __DIR__ . '/vendor/autoload.php';, then start using the generated classes.
not standalone: this means the package is generated as part of an existing project using its own composer.json file. So if you specified the namespace option with Ews for example, you need to add something like "Ews\\": "/destination_option_value/src/", in the autoload > psr-4 section of your existing composer.json file.
Command line option name: standalone
Methods names:
- $options->setStandalone(bool $standalone)
- $generator->setOptionStandalone(bool $standalone)

Namespace

This option is useful in several cases:

The operations/structs uses a reserved PHP keyword or function name, this allows to avoid the class name or the method name to be replaced by a safe name,
You want to generated the package into an existing namespace of yours without having to edit your composer.json,
You simply can't stand classes without a namespace,
Etc.

To conclude, you can specify the namespace with a value like Ews or Package\Ews.

Command line option name: namespace
Methods names:
- $options->setNamespace(string $namespace)
- $generator->setOptionNamespace(string $namespace)

Classes comments

Classes comments allows to add annotations with a value or simply a comment into every generated classes' PHP Doc block of the file.

Suppose you generate the package dynamically and you want to know when the package has been generated, with which version of your code it has been generated and you want to add your own description, you can add @date and @codeVersion annotations with your own value such as:

Command line usage :

$ wsdltophp --addcomments="date:2017/06/21" \
            --addcomments="codeVersion:2017/06/21" \
            --addcomments="This has been generated from server 01"

Methods usage:

/* @var GeneratorOptions $options */
$options->setAddComments([
    "date" => date("Y/m/d"),
    "codeVersion" => MY_CODE_VERSION,
    "This has been generated from server 01",
]);

/* @var Generator $generator */
$generator->setOptionAddComments([
    "date" => date("Y-m-d"),
    "codeVersion" => MY_CODE_VERSION,
    "This has been generated from server 01",
]);

This will generate a PHP Doc block such as:

/**
 * This class stands for Add ServiceType
 * @package Ews
 * @subpackage Services
 * @date 2017/06/21
 * @codeVersion 1.3.2
 * This has been generated from server 01
 */

Command line option name: addcomments
Methods names:
- $options->setAddComments(array $comments)
- $generator->setOptionAddComments(array $comments)

Constants naming

Constants classes are generated to represent enumerations defined in a WSDL/schema.

For example when the schema declares this:

<xs:simpleType name="ExchangeVersionType">
 <xs:restriction base="xs:string">
  <xs:enumeration value="Exchange2007" />
  <xs:enumeration value="Exchange2007_SP1" />
  <xs:enumeration value="Exchange2010" />
  <xs:enumeration value="Exchange2010_SP1" />
  <xs:enumeration value="Exchange2010_SP2" />
  <xs:enumeration value="Exchange2013" />
  <xs:enumeration value="Exchange2013_SP1" />
  <xs:enumeration value="Exchange2015" />
  <xs:enumeration value="V2_47" />
 </xs:restriction>
</xs:simpleType>

By default, you end up with a class like:

namespace Ews\EnumType;

class EwsExchangeVersionType
{
    /**
     * Constant for value 'Exchange2007'
     * @return string 'Exchange2007'
     */
    const VALUE_EXCHANGE_2007 = 'Exchange2007';
    /**
     * Constant for value 'Exchange2007_SP1'
     * @return string 'Exchange2007_SP1'
     */
    const VALUE_EXCHANGE_2007_SP_1 = 'Exchange2007_SP1';
    /**
     * Constant for value 'Exchange2010'
     * @return string 'Exchange2010'
     */
    const VALUE_EXCHANGE_2010 = 'Exchange2010';
    /**
     * Constant for value 'Exchange2010_SP1'
     * @return string 'Exchange2010_SP1'
     */
    const VALUE_EXCHANGE_2010_SP_1 = 'Exchange2010_SP1';
    /**
     * Constant for value 'Exchange2010_SP2'
     * @return string 'Exchange2010_SP2'
     */
    const VALUE_EXCHANGE_2010_SP_2 = 'Exchange2010_SP2';
    /**
     * Constant for value 'Exchange2013'
     * @return string 'Exchange2013'
     */
    const VALUE_EXCHANGE_2013 = 'Exchange2013';
    /**
     * Constant for value 'Exchange2013_SP1'
     * @return string 'Exchange2013_SP1'
     */
    const VALUE_EXCHANGE_2013_SP_1 = 'Exchange2013_SP1';
    /**
     * Constant for value 'Exchange2015'
     * @return string 'Exchange2015'
     */
    const VALUE_EXCHANGE_2015 = 'Exchange2015';
    /**
     * Constant for value 'V2_47'
     * @return string 'V2_47'
     */
    const VALUE_V_2_47 = 'V2_47';
    ...

But you can decide to end up with this class:

namespace Ews\EnumType;

class EwsExchangeVersionType
{
    /**
     * Constant for value 'Exchange2007'
     * @return string 'Exchange2007'
     */
    const ENUM_VALUE_1 = 'Exchange2007';
    /**
     * Constant for value 'Exchange2007_SP1'
     * @return string 'Exchange2007_SP1'
     */
    const ENUM_VALUE_2 = 'Exchange2007_SP1';
    /**
     * Constant for value 'Exchange2010'
     * @return string 'Exchange2010'
     */
    const ENUM_VALUE_3 = 'Exchange2010';
    /**
     * Constant for value 'Exchange2010_SP1'
     * @return string 'Exchange2010_SP1'
     */
    const ENUM_VALUE_4 = 'Exchange2010_SP1';
    /**
     * Constant for value 'Exchange2010_SP2'
     * @return string 'Exchange2010_SP2'
     */
    const ENUM_VALUE_5 = 'Exchange2010_SP2';
    /**
     * Constant for value 'Exchange2013'
     * @return string 'Exchange2013'
     */
    const ENUM_VALUE_6 = 'Exchange2013';
    /**
     * Constant for value 'Exchange2013_SP1'
     * @return string 'Exchange2013_SP1'
     */
    const ENUM_VALUE_7 = 'Exchange2013_SP1';
    /**
     * Constant for value 'Exchange2015'
     * @return string 'Exchange2015'
     */
    const ENUM_VALUE_7 = 'Exchange2015';
    /**
     * Constant for value 'V2_47'
     * @return string 'V2_47'
     */
    const ENUM_VALUE_8 = 'V2_47';
    ...

Command line option name: genericconstants
Methods names:
- $options->setGenericConstantsName(bool $generic)
- $generator->setOptionGenericConstantsName(bool $generic)

Composer settings

Composer settings option is useful when you generate a package with the standalone option set to true. In this case, the composer.json file is generated with default values and the composer update --verbose --optimize-autoloader --no-dev command is executed.

Imagine you need to disable tls (not safe) and you want to add the package wsdltophp/wssecurity:~1.0 into the require section (so it is fetched at the execution of the composer update command) of the generated composer.json file, you can do it this way:

Command line usage:

# take attention to the notation which is a sort of JSON notation such as path.to.the.section.key:value
$ wsdltophp --composer-settings="config.disable-tls:true" \
            --composer-settings="require.wsdltophp/wssecurity:~1.0"

Methods usage:

/* @var GeneratorOptions $options */
$options->setComposerSettings([
    "config.disable-tls:true",
    "require.wsdltophp/wssecurity:~1.0",
]);

/* @var Generator $generator */
$generator->setOptionComposerSettings([
    "config.disable-tls" => true,
    "require.wsdltophp/wssecurity" => "~1.0",
]);

This will generate this composer.json file (in part):

{
    "name": "wsdltophp/ews",
    "description": "Package generated from main.wsdl using wsdltophp/packagegenerator",
    "require": {
        "php": ">=5.3.3",
        "ext-soap": "*",
        "wsdltophp/packagebase": "~1.0",
        "wsdltophp/wssecurity": "~1.0"
    },
    "autoload": {
        "psr-4": {
            "": "./src/"
        }
    },
    "config": {
        "disable-tls": true
    }
}

To conclude, in most case you won't need it but it's here if you need.

Command line option name: composer-settings
Methods names:
- $options->setComposerSettings(array $settings)
- $generator->setOptionComposerSettings(array $settings)

Validation

By default, every generated setter in the Struct classes contains a sanity check as soon the value is not typed as another generated class. This means string, bool, float and int types are always checked when you pass a value. In addition, other validations are present to ensure that you pass the correct value according to the specification of the schema. The sanity check rules are defined in the File\Validation namespace and force values of type:

fractionDigits: you MUST pass exactly a certain number of digits after the decimal symbol
length: you MUST pass a string/number with the exact length
maxExclusive: you MUST pass a number which is strictly inferior to the specified value
maxInclusive: you MUST pass a number which is inferior or equal to the specified value
maxLength: you MUST pass a string/number which has a length strictly inferior to the specified value
minExclusive: you MUST pass a number which is strictly superior to the specified value
minInclusive: you MUST pass a number which is superior or equal to the specified value
minLength: you MUST pass a string/number which has a length strictly superior to the specified value
pattern: you MUST pass a string which match the specified regexp pattern
totalDigits: you MUST pass number that contains exactly the number of digits (negative, positive, decimal symbols are not taken into account) specified by the value
enumeration value: you MUST pass a value which is contained by a generated constants class for enumerations
array of values: you MUST pass an array containing only values of the specified value type

So if you pass an invalid value, a native PHP InvalidArgumentException with a dedicated message is throwned. There are some samples of generated methods:

// a string is expected to be 1 character length at least 
public function setImAddress($imAddress = null)
{
    // validation for constraint: minLength
    if ((is_scalar($imAddress) && strlen($imAddress) < 1) || (is_array($imAddress) && count($imAddress) < 1)) {
        throw new \InvalidArgumentException('Invalid length, please provide an array with 1 element(s) or a scalar of 1 character(s) at least', __LINE__);
    }
    // validation for constraint: string
    if (!is_null($imAddress) && !is_string($imAddress)) {
        throw new \InvalidArgumentException(sprintf('Invalid value, please provide a string, "%s" given', gettype($imAddress)), __LINE__);
    }
    $this->ImAddress = $imAddress;
    return $this;
}

// an array of string is expected
public function setEntry(array $entry = array())
{
    foreach ($entry as $additionalEntriesEntryItem) {
        // validation for constraint: itemType
        if (!is_string($additionalEntriesEntryItem)) {
            throw new \InvalidArgumentException(sprintf('The Entry property can only contain items of string, "%s" given', is_object($additionalEntriesEntryItem) ? get_class($additionalEntriesEntryItem) : gettype($additionalEntriesEntryItem)), __LINE__);
        }
    }
    $this->Entry = $entry;
    return $this;
}

// an enumeration value is exepected from the \Ews\EnumType\EwsMonthNamesType constant class
public function setMonth($month = null)
{
    // validation for constraint: enumeration
    if (!\Ews\EnumType\EwsMonthNamesType::valueIsValid($month)) {
        throw new \InvalidArgumentException(sprintf('Value "%s" is invalid, please use one of: %s', $month, implode(', ', \Ews\EnumType\EwsMonthNamesType::getValidValues())), __LINE__);
    }
    $this->Month = $month;
    return $this;
}

// a string is expected to math the pattern
public function setPersonId($personId = null)
{
    // validation for constraint: pattern
    if (is_scalar($personId) && !preg_match('/[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}/', $personId)) {
        throw new \InvalidArgumentException(sprintf('Invalid value, please provide a scalar value that matches "[0-9A-Fa-f]{8}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{4}-[0-9A-Fa-f]{12}", "%s" given', var_export($personId, true)), __LINE__);
    }
    // validation for constraint: string
    if (!is_null($personId) && !is_string($personId)) {
        throw new \InvalidArgumentException(sprintf('Invalid value, please provide a string, "%s" given', gettype($personId)), __LINE__);
    }
    $this->PersonId = $personId;
    return $this;
}

To conclude, if you're certain of the values you're passing (which can cause the SOAP Web Service to return you an error), you can avoid the validations rules to be generated by disabling this option.

Command line option name: validation
Methods names:
- $options->setValidation(bool $validation)
- $generator->setOptionValidation(bool $validation)

Gather operations methods

Generate tutorial

Generation options

Optional operation gathering method, if you have getList, getUsers, getData and setUser as operations:
- --gathermethods:
  - start (default): you'll have one Get class that contains the getList, getUsers and getData methods and another class Set that contains only the setUser method
  - none: you'll have only one class that contains all the methods getList, getUsers, getData and setUser methods
  - end, you'll have 4 classes:
    - List that contains the getList method,
    - User that contains the setUser method,
    - Users that contains the getUsers method,
    - Data that contains the getData method
Optional generated classes namespace and inheritance:
- --namespace: prefix classes' main namespace with your namespace
- --standalone (default: true): enables/disables the installation of the PackageBase package that contains the base class from which StructType, ArrayType and ServiceType classes inherit. If enabled, you MUST provide the composer-name option
Optional various other options:
- --gentutorial (default: true): enables/disables the tutorial file generation
- --validation (default: true): enables/disables the generation of validation rules in every setter
- --genericconstants (default: false): enables/disables the naming of the constants (enumerations) with the constant value or as a generic name:
  - true: const VALUE_DEFAULT = 'Default'
  - false: const ENUM_VALUE_0 = 'Default'
- --addcomments: allow to add PHP comments to classes' PHP DocBlock (mulitple values allowed)
- --composer-settings: allow to add settings to the generated composer.json file (mulitple values allowed)
Optional configuration file to use. It loads it first, then take into account the option you pass in the command line. By default, it uses:
- --config: the path to any configuration file you want anywhere you want
- the wsdltophp.yml.dist (provided with the source code) file located under the root folder OTHERWISE
- the wsdltophp.yml file (your own file) located under the root folder OTHERWISE
- the default configuration file located at src/resources/config/generator_options.yml

FAQ