v13.0.26

Author: xinyuwen2

README.md

@@ -1,179 +1,76 @@
-# msads-rest
+# BingAdsApiSDK PHP REST OpenAPI Generator
 
-This project provides the PHP client library for the REST-based Bing Ads API at Microsoft.
+This project provides a PHP SDK for the Microsoft Bing Ads API, generated from OpenAPI specifications. It enables developers to interact with Bing Ads services using RESTful APIs in a modern, type-safe, and convenient way.
 
-For documentation visit the [Bing Ads API Getting Started Page](https://learn.microsoft.com/en-us/advertising/guides/get-started).
+## Features
 
-## Installation & Usage
+- **Auto-generated PHP client** for Bing Ads REST APIs using OpenAPI specs.
+- Generator Installation: [OpenAPI Generator CLI](https://openapi-generator.tech/docs/installation)
+- Currently available Bing Ads services:
+  - CustomerManagementService
+  - CustomerBillingService
+  - CampaignManagementService
+  - BulkService
+  - ReportingService
+- Includes authentication helpers for OAuth2 flows.
+- PSR-compliant, compatible with modern PHP frameworks.
+- Unit tests and example usage included.
 
-### Requirements
+## Project Structure
 
-PHP 7.4 and later.
-Should also work with PHP 8.0.
-
-### Composer
-
-To install the bindings via [Composer](https://getcomposer.org/), run the following command:
-
-```bash
-composer require microsoft/msads
 ```
-
-Then run `composer install`
-
-### Manual Installation
-
-Download the files and include `autoload.php`:
-
-```php
-<?php
-require_once('/path/to/msads-rest/vendor/autoload.php');
+php_rest_openapi_gen/
+├── OpenApiSpecs/                 # OpenAPI JSON specs for each Bing Ads service
+├── php_templates/                # Mustache templates used for code generation
+├── php-rest/                     # Generated PHP SDK (src/api, src/model, etc.)
+│   ├── src/                      # SDK source code
+│   │   ├── Api/                  # API client classes for each service
+│   │   ├── Auth/                 # Authentication classes (OAuth2)
+│   │   ├── Model/                # Data models for requests/responses and other entities
+│   │   ├── Configuration.php     # API configuration and setup
+│   │   └── ObjectSerializer.php  # Serializer for API requests/responses
+│   ├── test/                     # Unit test and sample code
+│   ├── LICENSE.md                # License file
+│   ├── composer.json             # Composer configuration
+│   ├── composer.lock             # Composer lock file
+│   ├── phpunit.xml               # PHPUnit configuration
+│   └── README.md                 # SDK usage documentation
+├── openapitools.json             # OpenAPI Generator config
+├── php-config.yaml               # PHP codegen config specific to php generator
+├── generate-all.ps1              # PowerShell script to generate sdks for all specs in a folder
+└── README.md                     # This file
 ```
 
-## Getting Started
-
-Please follow the [installation procedure](#installation--usage) and then run the following:
-
-```php
-<?php
-require_once(__DIR__ . '/vendor/autoload.php');
-
-$config = \Microsoft\MsAds\Rest\Configuration::getDefaultConfiguration();
-
-$authentication = (new \Microsoft\MsAds\Rest\Auth\OAuthDesktopMobileAuthCodeGrant())
-    ->withEnvironment(\Microsoft\MsAds\Rest\Auth\ApiEnvironment::SANDBOX)
-    ->withClientId(self::CLIENT_ID)  // Replace with your client ID
-    ->withOAuthScope(\Microsoft\MsAds\Rest\Auth\OAuthScope::MSADS_MANAGE);
-
-$config->setAuthorizationData((new \Microsoft\MsAds\Rest\Auth\AuthorizationData())
-    ->withAuthentication($authentication)
-    ->withDeveloperToken('BBD37VB98'));  // For sandbox use 'BBD37VB98'
-
-// To set the auth key manually
-// $config = $config->setApiKey('Authorization', 'YOUR_API_KEY');
-// $config = $config->setApiKey('UserName', 'YOUR_API_KEY');
-// $config = $config->setApiKey('CustomerAccountId', 'YOUR_API_KEY');
-// $config = $config->setApiKey('CustomerId', 'YOUR_API_KEY');
-// $config = $config->setApiKey('DeveloperToken', 'YOUR_API_KEY');
-// $config = $config->setApiKey('Password', 'YOUR_API_KEY');
-
-
-$apiInstance = new \Microsoft\MsAds\Rest\Api\CampaignManagementServiceApi(
-    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
-    // This is optional, `GuzzleHttp\Client` will be used as default.
-    new \GuzzleHttp\Client(),
-    $config,
-    null,
-    \Microsoft\MsAds\Rest\Auth\ApiEnvironment::SANDBOX
-);
-$request = new \Microsoft\MsAds\Rest\Model\CampaignManagementService\AddAdExtensionsRequest();
-$request->setAdExtensions([
-    new \Microsoft\MsAds\Rest\Model\CampaignManagementService\ImageAdExtension([
-        'Name' => 'Test Image Ad Extension',
-    ])
-]);
+## Code Generation
 
-try {
-    $result = $apiInstance->addAdExtensions($request);
-    print_r($result);
-} catch (Exception $e) {
-    echo 'Exception when calling CampaignManagementServiceApi->addAdExtensions: ', $e->getMessage(), PHP_EOL;
-}
+To regenerate the SDK from updated OpenAPI specs, select the right spec json and `modelPackage` name, for example:
 
+```powershell
+openapi-generator-cli generate -g php -o .\php-rest `
+    -i .\OpenApiSpecs\CustomerBillingService.json `
+    -c .\php-config.yaml `
+    -p modelPackage="Model\CustomerBillingService" `
+    --global-property="models,apis,supportingFiles,apiDocs=false,modelDocs=false,apiTests=false,modelTests=false";
 ```
 
-## Handling Responses and Exceptions
-- The API uses standard HTTP response codes to indicate the success or failure of an API request. In general, `2xx` codes indicate success, while `4xx` and `5xx` codes indicate errors.
-- In certain cases, the API will return an `ApplicationFault` response with an error message and an error code. The error message will provide more details about the error.
-- If there is an error with the API call itself, the SDK will throw an `ApiException` with the error message and code. You can catch this exception and handle it accordingly.
+Repeat for each service spec as needed.
 
-Example of handling responses:
-```php
-try {
-    $response = $apiInstance->addAdExtensions($AddAdExtensionsRequest);
-    if ($response instanceof ApplicationFault) {
-        echo 'Handle the ApplicationFault response here';
-    } else {
-        echo 'Handle the AddAdExtensionsResponse response here';
-    }
-} catch (ApiException $e) {
-    echo 'Exception when calling AdExtensionService->addAdExtensions: ', $e->getMessage(), PHP_EOL;
-}
-```
-
-## Flag Enums
-The SDK uses `Flag Enums` to represent various options and settings.
-- These `Flag Enums` allow you to combine multiple options. For example, you can use the `CampaignManagementService\AdExtensionsTypeFilter` enum to specify multiple AdExtensionTypeFilters using an array of values OR comma-separated string.
-- To check if an Enum class is a `Flag Enum`, you can look for the `$isFlags` property in the class definition. If it is set to `true`, you can use the enum as a `Flag Enum`.
-- When a `Flag Enum` is returned from the API in deserialization, it will be represented as a string with the values separated by commas.
+Or, you can use the provided powershell script to generate **all services** at once:
 
-```php
-use \Microsoft\MsAds\Rest\Model\CampaignManagementService\AdExtensionsTypeFilter;
-// To represent multiple AdExtensionTypeFilters:
-$filter = [AdExtensionsTypeFilter::ACTION_AD_EXTENSION, AdExtensionsTypeFilter::APP_AD_EXTENSION];
-// or
-$filter = 'ActionAdExtension,AppAdExtension';
-// or
-$filter = AdExtensionsTypeFilter::ACTION_AD_EXTENSION . ',' . AdExtensionsTypeFilter::APP_AD_EXTENSION;
-// or
-$filter = new AdExtensionsTypeFilter($filter);
+```powershell
+.\generate-all.ps1 # uses default paths below, or you can specify custom paths
+# .\generate-all.ps1 -specsFolder "./OpenApiSpecs" -outputFolder "./php-rest" -configFile "./php-config.yaml"
 ```
 
-## Authorization
-You can use the OAuth 2.0 authorization flow to obtain the necessary tokens for accessing the Bing Ads API. The SDK supports both web-based and desktop-based OAuth flows.
-You can find more information on how to obtain these tokens in the [Bing Ads API documentation](https://learn.microsoft.com/en-us/advertising/guides/authentication-oauth).
-- Classes are provided in the SDK to help you with the OAuth 2.0 flow, within the folder [src/Auth](src/Auth).
-- Sample code can be found in the `test` directory, specifically in the [test/WebAuthentication](test/WebAuthentication) directory for webpage auth, and [test/RestApiTestBase.php](test/RestApiTestBase.php) for OAuth Desktop auth.
-
-Authentication schemes defined for the API:
-### Authorization
-- **Type**: API key
-- **API key parameter name**: Authorization
-- **Location**: HTTP header
-
-### UserName
-- **Type**: API key
-- **API key parameter name**: UserName
-- **Location**: HTTP header
-
-### Password
-- **Type**: API key
-- **API key parameter name**: Password
-- **Location**: HTTP header
-
-### CustomerAccountId
-- **Type**: API key
-- **API key parameter name**: CustomerAccountId
-- **Location**: HTTP header
-
-### CustomerId
-- **Type**: API key
-- **API key parameter name**: CustomerId
-- **Location**: HTTP header
-
-### DeveloperToken
-- **Type**: API key
-- **API key parameter name**: DeveloperToken
-- **Location**: HTTP header
-
-## Samples and Tests
-
-There are some samples included in the [test](test) directory showing examples of how to use the SDK.
-
-The samples are written using PHPUnit. To run the tests, you need to have PHPUnit installed. You can install it globally or use Composer to install it as a dependency.
-
-> **Warning**: Before running the tests, make sure to set up your environment variables for the API keys. You can do this by editing the CONSTANTS in the [RestApiTestBase.php](test/RestApiTestBase.php) file, going through the auth flow to get the `CODE_URL` and then replacing that constant.
-
-To run the tests, use an IDE or run the following command in the terminal:
-
-```bash
-composer install
-vendor/bin/phpunit
-```
+## Resources
+- [Bing Ads API Documentation](https://learn.microsoft.com/en-us/advertising/guides/)
+- OpenAPI Generator Documentation:
+  - [CLI Installation](https://openapi-generator.tech/docs/installation)
+  - [Using Templates](https://openapi-generator.tech/docs/templating)
+  - [Customizing Code Generation](https://openapi-generator.tech/docs/customization)
+  - [Configuration Options](https://openapi-generator.tech/docs/generators/php#configuration-options)
 
-Logs will be generated in the base directory of the project with the request and response data for further analysis.
+---
 
-## About this package
+*Generated with OpenAPI Generator and custom templates.*
 
-- SDK Package version: `13.0.25.1`
-- Generated date: `2025-07-31T13:28:36.717081200+08:00[Asia/Shanghai]`