From 7dd6cc26b269fb519b03cef10388344b49bb7416 Mon Sep 17 00:00:00 2001 From: Ivan Kamkin Date: Thu, 9 Apr 2026 14:59:34 +0500 Subject: [PATCH 1/3] Add skill --- skills/aspose-barcode-cloud-php/SKILL.md | 170 ++++++++++++++++++ .../agents/openai.yaml | 4 + .../references/repo-workflow.md | 70 ++++++++ .../references/snippet-map.md | 40 +++++ 4 files changed, 284 insertions(+) create mode 100644 skills/aspose-barcode-cloud-php/SKILL.md create mode 100644 skills/aspose-barcode-cloud-php/agents/openai.yaml create mode 100644 skills/aspose-barcode-cloud-php/references/repo-workflow.md create mode 100644 skills/aspose-barcode-cloud-php/references/snippet-map.md diff --git a/skills/aspose-barcode-cloud-php/SKILL.md b/skills/aspose-barcode-cloud-php/SKILL.md new file mode 100644 index 0000000..908dc72 --- /dev/null +++ b/skills/aspose-barcode-cloud-php/SKILL.md @@ -0,0 +1,170 @@ +--- +name: aspose-barcode-cloud-php +description: Write or update PHP code that uses the Aspose.BarCode Cloud SDK (`Aspose\BarCode\...`; Composer package `aspose/barcode-cloud-php`) to generate, recognize, or scan barcodes through Aspose's cloud REST API. Use this skill whenever the user wants barcode work in PHP, touches files under `submodules/php`, or mentions `GenerateApi`, `RecognizeApi`, `ScanApi`, `Configuration`, `GenerateRequestWrapper`, `GenerateBodyRequestWrapper`, `RecognizeBase64Request`, or `ScanMultipartRequestWrapper`. The PHP SDK has several easy-to-miss idioms, including constructing APIs as `new ...Api(null, $config)`, wrapping every call in a request-wrapper object, treating generate results as `SplFileObject` streams, using public `file_url` values for GET recognize and scan methods, and base64-encoding body payloads yourself. +--- + +# Aspose.BarCode Cloud SDK for PHP + +Use this skill to write PHP code against the generated Aspose.BarCode Cloud SDK or to maintain the PHP SDK inside `submodules/php`. Most tasks boil down to choosing the right API class, choosing the right request wrapper, and using the correct transport shape for the data you have. + +The Composer package name and PHP namespace differ. Install `aspose/barcode-cloud-php`, then import classes from `Aspose\BarCode\...`. + +## Quick start + +Use these imports in most PHP examples: + +```php +use Aspose\BarCode\Configuration; +use Aspose\BarCode\GenerateApi; +use Aspose\BarCode\RecognizeApi; +use Aspose\BarCode\ScanApi; +``` + +Prefer creating one `Configuration` instance and passing it into each API class: + +```php +$config = new Configuration(); +$config->setClientId($clientId); +$config->setClientSecret($clientSecret); + +$generateApi = new GenerateApi(null, $config); +$recognizeApi = new RecognizeApi(null, $config); +$scanApi = new ScanApi(null, $config); +``` + +If the task edits SDK source, tests, snippets, or generated files in `submodules/php`, read `references/repo-workflow.md`. If the task needs the closest existing example or snippet, read `references/snippet-map.md`. + +## Authenticate correctly + +Use one of these two patterns: + +1. Let the SDK fetch an access token lazily from client credentials. + +```php +$config = new Configuration(); +$config->setClientId($clientId); +$config->setClientSecret($clientSecret); +``` + +2. Inject a pre-fetched bearer token. + +```php +$config = new Configuration(); +$config->setAccessToken($token); +``` + +The runtime defaults are: + +- `Host`: `https://api.aspose.cloud` +- `BasePath`: `/v4.0` +- `AuthUrl`: `https://id.aspose.cloud/connect/token` + +Inside this repo, tests load `tests/Configuration.json` first and then fall back to `TEST_CONFIGURATION_*` environment variables. Snippets usually check `TEST_CONFIGURATION_ACCESS_TOKEN` first and otherwise rely on client credentials. Mirror the surrounding file when editing existing repo code. + +## Choose the right API shape + +Pick the operation first: + +- `GenerateApi`: create a barcode image. +- `RecognizeApi`: decode one or more known barcode types and optionally tune recognition. +- `ScanApi`: auto-detect barcode types with the smallest API surface. + +Then pick the transport variant based on what the caller has: + +- Public internet URL to an image: use `recognize()` or `scan()`. `file_url` must be publicly reachable, not a local path. +- Local file on disk: use `recognizeMultipart()` or `scanMultipart()` with `new SplFileObject(..., 'rb')`. +- Raw bytes already in memory: call `base64_encode()` yourself and use `recognizeBase64()` or `scanBase64()`. +- Simple text plus query parameters for generation: use `generate()`. +- Structured generate payload: use `generateBody()`. +- Multipart-form generation: use `generateMultipart()` when the caller explicitly needs that shape. + +Key method names: + +- `generate` +- `generateBody` +- `generateMultipart` +- `recognize` +- `recognizeBase64` +- `recognizeMultipart` +- `scan` +- `scanBase64` +- `scanMultipart` + +## Follow the PHP-specific SDK rules + +1. Instantiate APIs as `new GenerateApi(null, $config)` and the equivalent `RecognizeApi` or `ScanApi` constructors. The first constructor argument is the optional Guzzle client, not the `Configuration`. +2. Pass a request-wrapper object for every endpoint. Examples include `GenerateRequestWrapper`, `GenerateBodyRequestWrapper`, `RecognizeMultipartRequestWrapper`, and `ScanBase64RequestWrapper`. +3. Treat `generate()`, `generateBody()`, and `generateMultipart()` results as `\SplFileObject`. Read them with `getSize()` and `fread()`, save them to disk, or pass them directly into `ScanMultipartRequestWrapper`. +4. Build base64-body requests in two layers: create `RecognizeBase64Request` or `ScanBase64Request`, then wrap that model in the matching `...RequestWrapper`. +5. Call `base64_encode()` yourself before `recognizeBase64()` or `scanBase64()`. The SDK does not encode raw bytes for you. +6. Use one `DecodeBarcodeType` for `RecognizeRequestWrapper` and `RecognizeMultipartRequestWrapper`. Use a list in `RecognizeBase64Request(['barcode_types' => [...]])` when the request body should search multiple types. +7. Use GET-based recognize and scan methods only for public URLs. For local files, use multipart or base64 instead. +8. Expect `BarcodeResponseList` from recognize and scan methods. Iterate `getBarcodes()` and read `getBarcodeValue()`, `getType()`, `getRegion()`, and `getChecksum()`. +9. Let the SDK fetch a token automatically when `AccessToken` is empty but `ClientId` and `ClientSecret` are present. On `401`, the generated clients refresh the token and retry once. +10. Turn on `setDebug(true)` when request and response logging would help, and use `setUserAgent()` when a custom user agent is required. +11. Catch `Aspose\BarCode\ApiException` for API failures. For many `4xx` failures, `getResponseObject()` contains a parsed `ApiErrorResponse`. + +## Reuse the common patterns + +Generate and save a QR code: + +```php +use Aspose\BarCode\Model\BarcodeImageFormat; +use Aspose\BarCode\Model\CodeLocation; +use Aspose\BarCode\Model\EncodeBarcodeType; +use Aspose\BarCode\Requests\GenerateRequestWrapper; + +$request = new GenerateRequestWrapper(EncodeBarcodeType::QR, 'hello from PHP'); +$request->image_format = BarcodeImageFormat::Png; +$request->text_location = CodeLocation::None; + +$file = $generateApi->generate($request); +$file->rewind(); +file_put_contents('qr.png', $file->fread($file->getSize())); +``` + +Recognize a local file stream: + +```php +use Aspose\BarCode\Model\DecodeBarcodeType; +use Aspose\BarCode\Requests\RecognizeMultipartRequestWrapper; + +$file = new SplFileObject('qr.png', 'rb'); +$result = $recognizeApi->recognizeMultipart( + new RecognizeMultipartRequestWrapper(DecodeBarcodeType::QR, $file) +); + +foreach ($result->getBarcodes() as $barcode) { + echo $barcode->getBarcodeValue() . PHP_EOL; +} +``` + +Auto-scan bytes already in memory: + +```php +use Aspose\BarCode\Model\ScanBase64Request; +use Aspose\BarCode\Requests\ScanBase64RequestWrapper; + +$payload = base64_encode(file_get_contents('unknown.png')); +$result = $scanApi->scanBase64( + new ScanBase64RequestWrapper( + new ScanBase64Request(['file_base64' => $payload]) + ) +); +``` + +## Work inside this repo + +Read `references/repo-workflow.md` when the task changes SDK source, tests, snippets, package metadata, or generated code in `submodules/php`. + +Read `references/snippet-map.md` when the task needs example code, README-aligned snippets, or the closest existing pattern for a generate, recognize, or scan scenario. + +## Final checklist + +1. Use the correct package and namespace pair: Composer `aspose/barcode-cloud-php`, namespace `Aspose\BarCode\...`. +2. Construct API classes as `new ...Api(null, $config)`. +3. Pass the matching request-wrapper object into every SDK call. +4. Use GET only for public URLs, multipart for local files, and base64-body requests for bytes already in memory. +5. Base64-encode request payloads yourself before `recognizeBase64()` or `scanBase64()`. +6. Treat generate responses as `SplFileObject` streams and recognize or scan responses as `BarcodeResponseList`. +7. When changing the repo, validate with the submodule workflow in `references/repo-workflow.md`. diff --git a/skills/aspose-barcode-cloud-php/agents/openai.yaml b/skills/aspose-barcode-cloud-php/agents/openai.yaml new file mode 100644 index 0000000..3ca5391 --- /dev/null +++ b/skills/aspose-barcode-cloud-php/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Aspose.BarCode Cloud PHP" + short_description: "Write PHP barcode code with Aspose Cloud" + default_prompt: "Use $aspose-barcode-cloud-php to write or update PHP code that generates, recognizes, or scans barcodes with Aspose.BarCode Cloud." diff --git a/skills/aspose-barcode-cloud-php/references/repo-workflow.md b/skills/aspose-barcode-cloud-php/references/repo-workflow.md new file mode 100644 index 0000000..46a4c4d --- /dev/null +++ b/skills/aspose-barcode-cloud-php/references/repo-workflow.md @@ -0,0 +1,70 @@ +# PHP submodule workflow + +Use this reference when the task edits SDK source, tests, snippets, package metadata, or generated files inside `submodules/php`. + +## Layout + +- `src/Aspose/BarCode`: generated API clients, `Configuration`, `ApiException`, serializer, and transport helpers. +- `src/Aspose/BarCode/Model`: generated request and response models plus enums. +- `src/Aspose/BarCode/Requests`: request-wrapper objects for every SDK endpoint. +- `tests`: PHPUnit coverage for configuration, generate, recognize, scan, exceptions, end-to-end flows, and serialization. +- `snippets`: runnable documentation snippets grouped by `generate/*` and `read/*` scenarios. +- `scripts`: snippet runners and post-generation helpers such as credential insertion, example insertion, and deprecation-warning injection. +- `README.md` and `index.php`: user-facing usage examples. +- `composer.json` and `Makefile`: local validation and automation entry points. + +## Validation + +On Windows, run repo scripts and Make targets through WSL. + +From `submodules/php`: + +- `make init` +- `make format` +- `make lint` +- `make test` +- `make after-gen` + +What these targets do: + +- `make init`: run `composer install`. +- `make format`: run `php-cs-fixer fix index.php src/Aspose/ tests/ snippets/ --config=php-cs-fixer.conf`. +- `make lint`: run `phpstan analyse index.php src/ tests/ --level=3`. +- `make test`: run `composer test` (`phpunit`) and then `./scripts/run_snippets.sh`. +- `make after-gen`: run `format`, `insert-example`, and `./scripts/add-deprecation-warnings.bash`. + +`run_snippets.sh` does more than execute samples: + +- creates `snippets_test` +- symlinks the local `src` tree into that temp folder +- copies each snippet through `scripts/insert-credentials.py` +- executes each generated temp snippet with `php` + +Treat snippet failures as consumer-facing regressions, not just sample breakage. + +## Test configuration + +- Tests load `tests/Configuration.json` first and then fall back to `TEST_CONFIGURATION_*` environment variables via `TestConfiguration::fromFileOrEnv()`. +- Useful names include `TEST_CONFIGURATION_CLIENT_ID`, `TEST_CONFIGURATION_CLIENT_SECRET`, `TEST_CONFIGURATION_ACCESS_TOKEN`, `TEST_CONFIGURATION_HOST`, `TEST_CONFIGURATION_AUTH_URL`, and `TEST_CONFIGURATION_DEBUG`. +- `tests/Configuration.example.json` only contains placeholder client credentials. The runtime defaults still use `https://api.aspose.cloud` plus `/v4.0` and `https://id.aspose.cloud/connect/token`. +- Snippets embed placeholder dashboard credentials and optionally prefer `TEST_CONFIGURATION_ACCESS_TOKEN`. Mirror the surrounding file when editing repo code. + +## Regenerated code workflow + +If you change generated SDK code in this mono-repo: + +1. Make the intended SDK edit in `submodules/php` so the target behavior is clear. +2. Mirror the change in the matching template under `codegen/Templates/php` when the file is generated. +3. Stage the PHP submodule changes. +4. From the repo root, run `make php` through WSL. +5. Ensure `submodules/php` has no new unstaged diffs after regeneration. +6. If regeneration reintroduces old code, keep fixing templates or post-generation helpers until the generated output matches the intended SDK change. + +## Useful anchors + +- `src/Aspose/BarCode/Configuration.php`: auth defaults, debug flags, and user-agent behavior. +- `src/Aspose/BarCode/Requests/*.php`: the wrapper shapes every endpoint expects. +- `tests/TestConfiguration.php`: how tests discover config from JSON and environment variables. +- `tests/EndToEndTest.php`: generate a barcode stream, then pass it directly into `ScanMultipartRequestWrapper`. +- `scripts/run_snippets.sh` and `scripts/run_snippet.sh`: snippet execution harness. +- `Makefile`: the local validation and post-generation entry points. diff --git a/skills/aspose-barcode-cloud-php/references/snippet-map.md b/skills/aspose-barcode-cloud-php/references/snippet-map.md new file mode 100644 index 0000000..31c6081 --- /dev/null +++ b/skills/aspose-barcode-cloud-php/references/snippet-map.md @@ -0,0 +1,40 @@ +# Snippet and example map + +Use this reference when you want the closest existing PHP pattern before writing new SDK code or when updating docs, snippets, and examples. + +## Small end-user examples + +- `index.php`: compact generate-and-stream example suitable for quick starts. +- `snippets/ManualFetchToken.php`: manual OAuth client-credentials token fetch without using the SDK. + +## Generate patterns + +- `snippets/generate/save/GenerateGet.php`: simple `generate()` and save-to-file flow. +- `snippets/generate/save/GenerateBody.php`: `generateBody()` with `GenerateParams`. +- `snippets/generate/save/GenerateMultipart.php`: multipart generation flow. +- `snippets/generate/set-text/*`: `EncodeData` and `EncodeDataType` examples. +- `snippets/generate/set-size/*`: width, height, resolution, and units examples. +- `snippets/generate/set-colorscheme/*`: foreground and background color examples. +- `snippets/generate/appearance/*`: richer `BarcodeImageParams` examples. + +## Recognize and scan patterns + +- `snippets/read/set-source/RecognizeGet.php`: recognize from a public URL. +- `snippets/read/set-source/RecognizeMultipart.php`: recognize from a local `SplFileObject`. +- `snippets/read/set-source/RecognizeBody.php`: recognize from base64 bytes. +- `snippets/read/set-source/ScanGet.php`: auto-scan from a public URL. +- `snippets/read/set-source/ScanMultipart.php`: auto-scan from a local `SplFileObject`. +- `snippets/read/set-source/ScanBody.php`: auto-scan from base64 bytes. +- `snippets/read/set-target-types/*`: choosing a single `DecodeBarcodeType` or a list for `RecognizeBase64Request`. +- `snippets/read/set-quality/*`: `RecognitionMode` examples. +- `snippets/read/set-image-kind/*`: `RecognitionImageKind` examples. + +## Tests worth copying + +- `tests/EndToEndTest.php`: generate a barcode stream, then scan that same stream end to end. +- `tests/GenerateApiTest.php`: generate via GET, body, and multipart variants. +- `tests/RecognizeApiTest.php`: recognize via base64 body, multipart, and public URL. +- `tests/ScanApiTest.php`: scan via base64 body, multipart, and public URL. +- `tests/ConfigurationTest.php`: configuration defaults, JSON serialization, and environment-variable loading. +- `tests/ExceptionTest.php`: expected API failures and parsed error behavior. +- `tests/ObjectSerializerTests.php`: serializer behavior if model or date formatting changes. From 66a64cc97d227d8216baf6069cf088b5ce6835c7 Mon Sep 17 00:00:00 2001 From: Ivan Kamkin Date: Thu, 9 Apr 2026 16:02:06 +0500 Subject: [PATCH 2/3] Add AI agent skill section to README --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index 9c860e3..3d8094a 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,10 @@ To use these SDKs, you will need Client Id and Client Secret which can be looked You can either directly use it in your project via source code or get [Packagist distribution](https://packagist.org/packages/aspose/barcode-cloud-php) (recommended). +## AI Agent Skills + +This repository includes an AI-agent skill in [`skills/aspose-barcode-cloud-php/SKILL.md`](skills/aspose-barcode-cloud-php/SKILL.md). Point your coding agent to it when working with this SDK so it follows the repo workflow and SDK-specific API patterns. + ## Installation ### Via Composer From e282df545163c13d4f8df257713877c7946c7890 Mon Sep 17 00:00:00 2001 From: Ivan Kamkin Date: Fri, 10 Apr 2026 13:46:06 +0500 Subject: [PATCH 3/3] Rename PHP skill to generate-and-scan-barcode --- README.md | 3 +-- skills/aspose-barcode-cloud-php/agents/openai.yaml | 4 ---- .../SKILL.md | 4 ++-- skills/generate-and-scan-barcode-php/agents/openai.yaml | 4 ++++ .../references/repo-workflow.md | 0 .../references/snippet-map.md | 0 6 files changed, 7 insertions(+), 8 deletions(-) delete mode 100644 skills/aspose-barcode-cloud-php/agents/openai.yaml rename skills/{aspose-barcode-cloud-php => generate-and-scan-barcode-php}/SKILL.md (99%) create mode 100644 skills/generate-and-scan-barcode-php/agents/openai.yaml rename skills/{aspose-barcode-cloud-php => generate-and-scan-barcode-php}/references/repo-workflow.md (100%) rename skills/{aspose-barcode-cloud-php => generate-and-scan-barcode-php}/references/snippet-map.md (100%) diff --git a/README.md b/README.md index 3d8094a..8a143e3 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,7 @@ You can either directly use it in your project via source code or get [Packagist ## AI Agent Skills -This repository includes an AI-agent skill in [`skills/aspose-barcode-cloud-php/SKILL.md`](skills/aspose-barcode-cloud-php/SKILL.md). Point your coding agent to it when working with this SDK so it follows the repo workflow and SDK-specific API patterns. +This repository includes an AI-agent skill in [`skills/generate-and-scan-barcode-php/SKILL.md`](skills/generate-and-scan-barcode-php/SKILL.md). Point your coding agent to it when working with this SDK so it follows the repo workflow and SDK-specific API patterns. ## Installation @@ -140,4 +140,3 @@ Class | Method | HTTP request | Description - [RegionPoint](docs/Model/RegionPoint.md) - [ScanBase64Request](docs/Model/ScanBase64Request.md) - diff --git a/skills/aspose-barcode-cloud-php/agents/openai.yaml b/skills/aspose-barcode-cloud-php/agents/openai.yaml deleted file mode 100644 index 3ca5391..0000000 --- a/skills/aspose-barcode-cloud-php/agents/openai.yaml +++ /dev/null @@ -1,4 +0,0 @@ -interface: - display_name: "Aspose.BarCode Cloud PHP" - short_description: "Write PHP barcode code with Aspose Cloud" - default_prompt: "Use $aspose-barcode-cloud-php to write or update PHP code that generates, recognizes, or scans barcodes with Aspose.BarCode Cloud." diff --git a/skills/aspose-barcode-cloud-php/SKILL.md b/skills/generate-and-scan-barcode-php/SKILL.md similarity index 99% rename from skills/aspose-barcode-cloud-php/SKILL.md rename to skills/generate-and-scan-barcode-php/SKILL.md index 908dc72..7461877 100644 --- a/skills/aspose-barcode-cloud-php/SKILL.md +++ b/skills/generate-and-scan-barcode-php/SKILL.md @@ -1,9 +1,9 @@ --- -name: aspose-barcode-cloud-php +name: generate-and-scan-barcode-php description: Write or update PHP code that uses the Aspose.BarCode Cloud SDK (`Aspose\BarCode\...`; Composer package `aspose/barcode-cloud-php`) to generate, recognize, or scan barcodes through Aspose's cloud REST API. Use this skill whenever the user wants barcode work in PHP, touches files under `submodules/php`, or mentions `GenerateApi`, `RecognizeApi`, `ScanApi`, `Configuration`, `GenerateRequestWrapper`, `GenerateBodyRequestWrapper`, `RecognizeBase64Request`, or `ScanMultipartRequestWrapper`. The PHP SDK has several easy-to-miss idioms, including constructing APIs as `new ...Api(null, $config)`, wrapping every call in a request-wrapper object, treating generate results as `SplFileObject` streams, using public `file_url` values for GET recognize and scan methods, and base64-encoding body payloads yourself. --- -# Aspose.BarCode Cloud SDK for PHP +# Generate and scan barcode in PHP Use this skill to write PHP code against the generated Aspose.BarCode Cloud SDK or to maintain the PHP SDK inside `submodules/php`. Most tasks boil down to choosing the right API class, choosing the right request wrapper, and using the correct transport shape for the data you have. diff --git a/skills/generate-and-scan-barcode-php/agents/openai.yaml b/skills/generate-and-scan-barcode-php/agents/openai.yaml new file mode 100644 index 0000000..472bc03 --- /dev/null +++ b/skills/generate-and-scan-barcode-php/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Generate and scan barcode in PHP" + short_description: "Use Aspose.BarCode Cloud from PHP" + default_prompt: "Use $generate-and-scan-barcode-php to write or update PHP code that generates, recognizes, or scans barcodes with Aspose.BarCode Cloud." diff --git a/skills/aspose-barcode-cloud-php/references/repo-workflow.md b/skills/generate-and-scan-barcode-php/references/repo-workflow.md similarity index 100% rename from skills/aspose-barcode-cloud-php/references/repo-workflow.md rename to skills/generate-and-scan-barcode-php/references/repo-workflow.md diff --git a/skills/aspose-barcode-cloud-php/references/snippet-map.md b/skills/generate-and-scan-barcode-php/references/snippet-map.md similarity index 100% rename from skills/aspose-barcode-cloud-php/references/snippet-map.md rename to skills/generate-and-scan-barcode-php/references/snippet-map.md