Feature/issue 124

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: bug
+assignees: mikaelcom
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is. Ideally the WSDL URL. If not public, feel free to send it to [email protected].
+
+**To Reproduce**
+Steps to reproduce the behavior:
+- During the package generation?
+- During the usage of the generated package?
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: mikaelcom
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is.
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/workflows/release.yml

@@ -19,7 +19,6 @@ jobs:
     strategy:
       matrix:
         php-version:
-          - 5.6
           - 7.4
 
     steps:
@@ -71,7 +70,7 @@ jobs:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         with:
           tag_name: ${{ env.GITHUB_REF_NAME }}
-          release_name: ${{ env.GITHUB_REF_NAME }} - PHP ${{ matrix.php-version }}
+          release_name: ${{ env.GITHUB_REF_NAME }}
           draft: true
           body: TODO
 
@@ -82,7 +81,7 @@ jobs:
         with:
           upload_url: ${{ steps.create_release.outputs.upload_url }}
           asset_path: ./bin/wsdltophp.phar
-          asset_name: wsdltophp-${{ env.GITHUB_REF_NAME_SLUG }}-${{ matrix.php-version }}.phar
+          asset_name: wsdltophp-${{ env.GITHUB_REF_NAME_SLUG }}.phar
           asset_content_type: application/octet-stream
 
       - name: Configure GPG key and sign phar
@@ -103,22 +102,19 @@ jobs:
         with:
           upload_url: ${{ steps.create_release.outputs.upload_url }}
           asset_path: ./wsdltophp.phar.asc
-          asset_name: wsdltophp-${{ env.GITHUB_REF_NAME_SLUG }}-${{ matrix.php-version }}.phar.asc
+          asset_name: wsdltophp-${{ env.GITHUB_REF_NAME_SLUG }}.phar.asc
           asset_content_type: application/octet-stream
 
       - name: Setup Buildx
-        if: startsWith(matrix.php-version, '7')
         uses: docker/setup-buildx-action@v1
 
       - name: Login to DockerHub
-        if: startsWith(matrix.php-version, '7')
         uses: docker/login-action@v1
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_SECRET }}
 
       - name: Build and push to Docker
-        if: startsWith(matrix.php-version, '7')
         uses: docker/build-push-action@v2
         with:
           context: .

.gitignore

@@ -1,7 +1,9 @@
-vendor/
+vendor
 composer.lock
 composer.phar
 phpunit.xml
 wsdltophp.yml
-bin/
+bin
 tests/resources/generated
+coverage
+.phpunit.result.cache

.php_cs

@@ -8,14 +8,6 @@ $finder = PhpCsFixer\Finder::create()
 return PhpCsFixer\Config::create()
     ->setUsingCache(false)
     ->setRules(array(
-        '@PSR2' => true,
-        'array_syntax' => [
-            'syntax' => 'short',
-        ],
-        'binary_operator_spaces' => true,
-        'no_whitespace_in_blank_line' => true,
-        'ternary_operator_spaces' => true,
-        'cast_spaces' => true,
-        'trailing_comma_in_multiline_array' => true
+        '@PhpCsFixer' => true,
     ))
     ->setFinder($finder);

.travis.yml

@@ -2,27 +2,6 @@ language: php
 
 jobs:
   include:
-    - name: 'Tests under PHP 5.4'
-      php: '5.4'
-      dist: trusty
-    - name: 'Tests under PHP 5.5'
-      php: '5.5'
-      dist: trusty
-    - name: 'Tests under PHP 5.6'
-      php: '5.6'
-      dist: trusty
-    - name: 'Tests under PHP 7.0'
-      php: '7.0'
-      dist: xenial
-    - name: 'Tests under PHP 7.1'
-      php: '7.1'
-      dist: bionic
-    - name: 'Tests under PHP 7.2'
-      php: '7.2'
-      dist: bionic
-    - name: 'Tests under PHP 7.3'
-      php: '7.3'
-      dist: bionic
     - name: 'Tests under PHP 7.4'
       php: '7.4'
       dist: bionic
@@ -42,14 +21,14 @@ cache:
     - $HOME/.composer/cache
 
 install:
-    - composer install
+  - composer install
 
 script:
-    - php -dmemory_limit=-1 ./vendor/phpunit/phpunit/phpunit --coverage-text --coverage-clover=coverage.clover
+  - php -dmemory_limit=-1 -dxdebug.mode=coverage ./vendor/bin/phpunit --coverage-text --coverage-clover=coverage.clover
 
 after_script:
-    - wget https://scrutinizer-ci.com/ocular.phar
-    - php -dmemory_limit=-1 ocular.phar code-coverage:upload --format=php-clover coverage.clover
+  - wget https://scrutinizer-ci.com/ocular.phar
+  - php -dmemory_limit=-1 ocular.phar code-coverage:upload --format=php-clover coverage.clover
 
 after_success:
-    - bash <(curl -s https://codecov.io/bash)
+  - bash <(curl -s https://codecov.io/bash)

CHANGELOG.md

@@ -1,5 +1,18 @@
 # CHANGELOG
 
+## 4.0.0 - 2021-xx-xx
+- issue #124 - PHP >= 7.4 tasks
+  - Code requires PHP >= 7.4
+  - Generated code requires PHP >= 7.4
+  - Code cleaning
+  - Update README
+  - Add [MANIFEST.md](/MANIFEST.md) explaining how files are generated and how they should be used
+  - Update Travis CI settings
+  - Update PHPUnit settings
+  - Update LICENSE file
+  - BC: read [UPGRADE-4.0.md](/UPGRADE-4.0.md)
+  - Version 2.0 is no more maintained
+
 ## 3.3.4 - 2021-01-25
 - issue #230 - Avoid repeated meta value within generated meta documentation
 - issue #217 - Inherited struct methods should not be overwritten

MANIFEST.md

@@ -0,0 +1,135 @@
+# 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):
+
+```markdown
+{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](https://github.com/WsdlToPhp/PhpGenerator) library. The [PhpGenerator](https://github.com/WsdlToPhp/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`.
+  - Read the [src folder option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#src-dirname) for more information.
+  - Read the [destination option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#destination) for more information.
+  - Read the [category option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#category) for more information.
+- Classes are not namespaced by default.
+  - Read the [namespace option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#namespace) for more information.
+- Classes are **named after the element name** all with respecting the **PHP class naming constraints**. Generated names can be prefixed and suffixed if needed.
+  - Read the [prefix option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#prefix) for more information.
+  - Read the [suffix option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#suffix) for more information.
+- Classes are generated with predefined comments and annotations. You can add your proper annotations.
+  - Read the [classes comments option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#classes-comments) for more information.
+- 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.
+  - Read the [structs folder option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#structs-folder) for more information.
+- Classes extend the [AbstractStructBase](https://github.com/WsdlToPhp/PackageBase#abstractstructbase) class from the [PackageBase](https://github.com/WsdlToPhp/PackageBase) dependency in order to benefit from [generic methods](https://github.com/WsdlToPhp/PackageBase#abstractstructbase).
+  - Read the [struct option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#struct) for more information.
+- 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.
+      - Read the [xsd types option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#xsd-types-mapping) for more information.
+    - **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](https://www.php.net/manual/en/class.invalidargumentexception.php) exception is thrown with an explicit message if you made a mistake.
+      - Read the [validation option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#validation) for more information.
+    - **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](https://www.php.net/manual/en/class.domdocument.php) 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](https://www.php.net/manual/en/class.domdocument.php) 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.
+  - Read the [arrays folder option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#arrays-folder) for more information.
+- Classes extend the [AbstractStructArrayBase](https://github.com/WsdlToPhp/PackageBase#abstractstructarraybase) class from the [PackageBase](https://github.com/WsdlToPhp/PackageBase) dependency in order to benefit from [generic methods](https://github.com/WsdlToPhp/PackageBase#abstractstructarraybase).
+  - Read the [struct array option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#structarray) for more information.
+- Classes are **empowered** thanks to [AbstractStructArrayBase](https://github.com/WsdlToPhp/PackageBase#abstractstructarraybase) class:
+  - They are [Traversable](https://www.php.net/manual/en/class.traversable.php), [Countable](https://www.php.net/manual/en/class.countable.php) and they also implement the [ArrayAccess](https://www.php.net/manual/en/class.arrayaccess.php) 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](https://github.com/WsdlToPhp/PackageBase#abstractstructarraybase) methods):
+  - **current(): ?{childElementType}**: returns the [current](https://www.php.net/manual/en/iterator.current.php) iteration element.
+  - **item($index): ?{childElementType}**: returns the item at the given position (alias of [offsetGet](https://www.php.net/manual/en/arrayaccess.offsetget.php)).
+  - **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.
+  - Read the [constants naming option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#constants-naming) for more information.
+- Classes are generated under the `src/StructEnumType` folder by default.
+  - Read the [enums folder option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#enums-folder) for more information.
+- Classes extend the [AbstractStructEnumBase](https://github.com/WsdlToPhp/PackageBase#abstractstructenumbase) class from the [PackageBase](https://github.com/WsdlToPhp/PackageBase) dependency in order to benefit from [generic methods](https://github.com/WsdlToPhp/PackageBase#abstractstructenumbase).
+  - Read the [struct enum option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#structenum) for more information.
+- Classes are **empowered** thanks to [AbstractStructEnumBase](https://github.com/WsdlToPhp/PackageBase#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.
+  - Read the [gather operations option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#gather-operations-methods) for more information.
+- Classes are generated under the `src/ServiceType` folder by default.
+  - Read the [services folder option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#services-folder) for more information.
+- Classes extend the [AbstractSoapClientBase](https://github.com/WsdlToPhp/PackageBase#abstractsoapclientbase) class from the [PackageBase](https://github.com/WsdlToPhp/PackageBase) dependency in order to benefit from [generic methods](https://github.com/WsdlToPhp/PackageBase#abstractsoapclientbase).
+  - Read the [soapclient option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#soapclient) for more information.
+- 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](https://www.php.net/manual/en/class.soapfault.php) 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`](https://www.php.net/manual/en/soapclient.construct.php#refsect1-soapclient.construct-parameters) option for the SoapClient class.
+
+## composer.json
+- composer.json file is generated when `standalone` option is enabled under the `destination` folder.
+  - Read the [standalone option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#standalone) for more information.
+- composer.json `name` can be set.
+  - Read the [composer name option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#composer-name) for more information.
+- composer.json settings can be customized.
+  - Read the [composer settings option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#composer-settings) for more information.
+
+## tutorial.php
+- tutorial.php file is generated under the `destination` folder if it is enabled (`true` by default).
+  - Read the [tutorial option](https://github.com/WsdlToPhp/PackageGenerator/wiki/Options#generate-tutorial) for more information.
+- 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.