[PHP] DateTime should be DateTimeImmutable

[SunMar]

Description

Response strings with format: date and format: date-time are cast to a \DateTime object, but I think they should be a \DateTimeImmutable. The problem with a regular \DateTime is that it can be modified, then if the same response object instance is used in multiple places in the code you can not trust any of the returned \DateTime objects, if they are modified it may produce unexpected results. This can be fixed by using \DateTimeImmutable instead which after creation can no longer be modified. Any modifications are returned in a new \DateTimeImmutable instance that doesn't affect the original instance in the response.

Swagger-codegen version

I'm using the latest 2.3.0 snapshot (swagger-codegen-cli-2.3.0-20170921.031930-142.jar).

Swagger declaration file content or url

test.yaml

---
swagger: '2.0'

info:
  title: 'Test Codegen DateTimeImmutable'
  version: '1.0'
  
paths:
  '/foo':
    get:
      responses:
        200:
          description: 'Success'
          schema:
            type: object
            properties:
              timestamp:
                type: string
                format: 'date-time'

client.php

<?php

require 'vendor/autoload.php';

use Swagger\Client\Api\DefaultApi;

$api = new DefaultApi(
    new \GuzzleHttp\Client(),
    (new \Swagger\Client\Configuration())->setHost('http://localhost')
);

$response = $api->fooGet();

echo '$response->getTimestamp() value before add: ' . $response->getTimestamp()->format(DateTime::ATOM) . PHP_EOL;

$response->getTimestamp()->add(new DateInterval('P1W'));

echo '$response->getTimestamp() value after add:  ' . $response->getTimestamp()->format(DateTime::ATOM) . PHP_EOL;

index.php

<?php

echo json_encode([ 'timestamp' => date(DATE_ATOM) ]);

Command line used for generation

java -jar swagger-codegen-cli-2.3.0-20170921.031930-142.jar generate -i test.yaml -l php

Steps to reproduce

I am assuming $PWD is your current working directory where you are testing this. Replace of course as you like with a directory of your choice.

1. Save the sample test.yaml in $PWD.
2. Create a directory $PWD/foo and place in that directory the sample index.php.
3. In $PWD run php -S 127.0.0.1:80 to start a quick web server.
4. Generate the client library from $PWD: java -jar swagger-codegen-cli-2.3.0-20170921.031930-142.jar generate -i test.yaml -l php
5. Go into the directory $PWD/SwaggerClient-php.
6. Run composer update --no-dev
7. Save the sample client.php in $PWD/SwaggerClient-php.
8. Run the client: php client.php
9. Check the output:

$response->getTimestamp() value before add: 2017-09-21T12:39:21+00:00
$response->getTimestamp() value after add:  2017-09-28T12:39:21+00:00

It should not have been possible to modify the response.

Related issues/PRs

This applies to both format: date and format: date-time, but see #6533 where I made a comment on whether a date should just be a string and not a \DateTime.

Suggest a fix/enhancement

\DateTime should be replaced with \DateTimeImmutable. Also any code that checks if a variable is a \DateTime should check not for the class but for the interface \DateTimeInterface (ObjectSerializer->toString()).

[wing328]

@SunMar thanks for the suggestion.

cc @jebentier @dkarlovi @mandrean @jfastnacht @ackintosh

[dkarlovi]

@SunMar very much agree, nice catch. Can you attach a PR for this?

[SunMar]

@dkarlovi I can try to make a PR some time this week, but my Java knowledge is limited to a couple basic courses I had 15 years ago. This could be easy enough though to not really require knowledge of Java. Since I'm also not familiar with the Codegen code base it'd come down to doing a search for DateTime in the code base and changing the references where applicable. I assume I can also use PR #6510 as a reference, but is there anything else I need to take into account?

[dkarlovi]

You need almost no Java knowledge (I'd expect you won't need literally any here), you'd do this by editing template files which generate code here.

[SunMar]

I think your "here" is missing a link or something :). Where are the template files?

[dkarlovi]

@SunMar here.

[wing328]

https://github.com/swagger-api/swagger-codegen/blob/master/modules/swagger-codegen/src/main/java/io/swagger/codegen/languages/PhpClientCodegen.java#L120-L122 is a good starting point for type mapping.

After making changes, please run "mvn clean package" to rebuild the JAR.

[dkarlovi]

@wing328 this might be a feature request on the type mapping feature itself, as (from this issue):

1. you'd want to type hint on DateTypeInterface (so, an interface)
2. you'd want to USE DateTimeImmutable (a class implementing DateTimeInterface)

Type mapping which you've linked might provide a way to differentiate between the two which might be used in ObjectSerializer without it being hardcoded everywhere.