Improved PHP Code Samples

The generated PHP code samples are now idiomatic with no errors. This improves the developer experience by allowing developers to run the code samples without any error in their applications and to get started quickly.

Details

This release introduces significant improvements to the code samples provided for your API. We've made several updates to the code samples to ensure that they are up-to-date, easier to understand, and more user-friendly. The new code samples are designed to help developers get started with your API quickly and easily, without having to spend a lot of time reading documentation or trying to figure out how to use the API.

What Has Changed?

Following major improvements are now made part of the PHP code samples:

• Updated code samples using PHP's phan analyzer checks and guidelines.

• Simplified code samples using phpcs linter with PSR12 standards and ruleset to make them easier to read and understand using the publically available configuration.

• Removed unused imports from generated code samples.

• Added comments and explanations to the code samples to provide more context and help developers understand how to use the API.

• Fixed bugs and errors in the code samples to ensure that they work as expected.

Parameters Initialization Section Improvements

Model Initialization

Made the model's field initialization in-line which ensures that the object structure is intact, enhancing the code readability.

Before

$employee_name = 'John';
$employee_age = 22;
$employee_boss_name = 'Doe';
$employee_boss_age = 32;
$employee_boss = new Models\Person(
    $employee_boss_name,
    $employee_boss_age
);
$employee = new Models\Employee(
    $employee_name,
    $employee_age,
    $employee_boss
);
$employee_hiredAt = DateTimeHelper::fromRfc1123DateTime('Mon, 15 Jun 2009 20:45:30 GMT');
$employee->setHiredAt($employee_hiredAt);

After

$employee = EmployeeBuilder::init(
    'John',
    22,
    PersonBuilder::init(
        'Doe',
        32
    )->build()
)
    ->hiredAt(DateTimeHelper::fromRfc1123DateTime('Mon, 15 Jun 2009 20:45:30 GMT'))
    ->build();

Array Initialization

Made Array initialization more idiomatic and readable by writing it in multiple lines instead of cluttering it in the same line.

Before

$stringArray = ['Bob', 'Alice', 'John'];

After

$stringArray = [
    'Bob',
    'Alice',
    'John'
];

Take another example of nested map inside arrays. Array of Map initialization is now more idiomatic and readable.

Before

$stringArrayOfMap = [['key0' => 'Bob'], ['key0' => 'Alice', 'key1' => 'John']];

After

$stringArrayOfMap = [
    [
        'key0' => 'Bob'
    ],
    [
        'key0' => 'Alice',
        'key1' => 'John'
    ]
];

Map Initialization

Made Map initialization more readable by writing it in multiple lines instead of cluttering it in the same line.

Before

$stringMap = ['key0' => 'Bob', 'key1' => 'Alice', 'key2' => 'John'];

After

$stringMap = [
    'key0' => 'Bob',
    'key1' => 'Alice',
    'key2' => 'John'
];

Take another example of nested array inside maps. Map of Array initialization is now more readable and idiomatic.

Before

$stringMapOfArray = ['key0' => ['Bob','Alice'], 'key1' => ['Bob','Alice','John'], 'key2' => ['Doe']];

After

$stringMapOfArray = [
    'key0' => [
        'Bob',
        'Alice'
    ],
    'key1' => [
        'Bob',
        'Alice',
        'John'
    ],
    'key2' => [
        'Doe'
    ]
];

Multi Dimensional Array Initialization

We are now also supporting code samples for Multi dimensional arrays.

$string2dArray = [
    [
        'Bob',
        'Alice'
    ],
    [
        'John',
        'Doe'
    ]
];

Imports Section Improvements

Replaced Fully Qualified Names with imports

Previously, Models and Utility Classes were referred by their full paths in the Parameters Declaration section but we have now resolved this issue by using the proper imports for these utility classes.

Before

// parameters initialization section
$param = TesterLib\ApiHelper::deserialize('{"key1":"val1","key2":"val2"}');

After

// imports section
use TesterLib\ApiHelper;

// parameters initialization section
$param = ApiHelper::deserialize('{"key1":"val1","key2":"val2"}');

Unused imports

Previously, imports were added even if they were not required in any other sections, but now we are adding imports on demand for optional parameters:

// imports section
use TesterLib\Models\Builders\ModelBuilder;

// parameters initialization section
$model = ModelBuilder::init()->build();
$nativeString = 'some string value';

Without the model parameter, the above code sample would look like:

// empty imports section

// parameters initialization section
$nativeString = 'some string value';

Client Initialization Section Improvements

Proximity Principle

Client initialization section now follows Principle of Proximity, as it is now declared close to API Call Section, where it is being used.

Before

// client initialization section
$client = TesterLib\TesterClientBuilder::init()
    ->environment('production')
    ->port('8080')
    ->suites(Models\SuiteCode::CLUBS)
    ->build();

$param1 = 'string value 1';

$param2 = 'string value 2';

// API call section
$queryParamController = $client->getQueryParamController();
$queryParamController->sendData($param1, $param2);

After

$param1 = 'string value 1';

$param2 = 'string value 2';

// client initialization section
$client = TesterClientBuilder::init()
    ->environment('production')
    ->port('8080')
    ->suites(SuiteCode::CLUBS)
    ->build();

// API call section
$client->getQueryParamController()->sendData(
    $param1,
    $param2
);

Default Configuration Setup

We have now followed the style guideline of calling the build() method on the same line when no other configurations are customized.

Before

$client = TesterLib\TesterClientBuilder::init()
    ->build();

After

$client = TesterClientBuilder::init()->build();

API Call Section Improvements

Multi line arguments

Following the style guideline of PHP, we have addressed the styling of an API call method with multiple parameters and converted them into multi-lines to have a better readability of an endpoint call.

Before

$queryParamController = $client->getQueryParamController();
$queryParamController->sendData($param1, $param2, $param3);

After

$client->getQueryParamController()->sendData(
    $param1,
    $param2,
    $param3
);

Elimination of controller's reference

We removed the initialization of the controller instance variable and gave direct access to it using the $client variable.

Before

$queryParamController = $client->getQueryParamController();
$queryParamController->sendData($data);

After

$client->getQueryParamController()->sendData($data);

Full Code Sample Comparison

The following code shows the complete comparison between the code sample generation for initializing an employee model as an input parameter for Query Param Controller endpoint Send Employee.

Employee Model

{
  "name": "John",
  "age": 23,
  "boss": {
    "name": "Doe",
    "age": 32,
  },
  "hiredAt": "Mon, 15 Jun 2009 20:45:30 GMT"
}

Generated code samples

Before

<?php

require_once "vendor/autoload.php";

use TesterLib\Models;
use TesterLib\Utils\DateTimeHelper;

$client = TesterLib\TesterClientBuilder::init()
    ->environment('production')
    ->port('8080')
    ->suites(Models\SuiteCode::CLUBS)
    ->build();

$queryParamController = $client->getQueryParamController();

$employee_name = 'John';
$employee_age = 22;
$employee_boss_name = 'Doe';
$employee_boss_age = 32;
$employee_boss = new Models\Person(
    $employee_boss_name,
    $employee_boss_age
);
$employee = new Models\Employee(
    $employee_name,
    $employee_age,
    $employee_boss
);
$employee_hiredAt = DateTimeHelper::fromRfc1123DateTime('Mon, 15 Jun 2009 20:45:30 GMT');
$employee->setHiredAt($employee_hiredAt);


try {
    $result = $queryParamController->sendEmployee($employee);
} catch (TesterLib\Exceptions\ApiException $e) {
    echo 'Caught ApiException: ',  $e->getMessage(), "\n";
}

After

<?php

require_once "vendor/autoload.php";

use TesterLib\TesterClientBuilder;
use TesterLib\Exceptions\ApiException;
use TesterLib\Models\Builders\EmployeeBuilder;
use TesterLib\Models\Builders\PersonBuilder;
use TesterLib\Utils\DateTimeHelper;
use TesterLib\Models\SuiteCode;

$employee = EmployeeBuilder::init(
    'John',
    22,
    PersonBuilder::init(
        'Doe',
        32
    )->build()
)
    ->hiredAt(DateTimeHelper::fromRfc1123DateTime('Mon, 15 Jun 2009 20:45:30 GMT'))
    ->build();

$client = TesterClientBuilder::init()
    ->environment('production')
    ->port('8080')
    ->suites(SuiteCode::CLUBS)
    ->build();

try {
    $result = $client->getQueryParamController()->sendEmployee($employee);
    var_dump($result);
} catch (ApiException $e) {
    echo 'Caught ApiException: ',  $e->getMessage(), "\n";
}

Bugs fixed

• Fixed multiple Indentation issues in parameters initialization section
• Removed trailing comma from the endpoint call
• Fixed issues with File and Binary request parameters