Skip to content

Commit 9bfbbdd

Browse files
const-cloudinaryconst-cloudinary
committed
docs: add agent-readable documentation and repository metadata
Bring the repository up to the Cloudinary agent-readable documentation standard, following the structure shipped in cloudinary_npm (PRs #742 and #744). Documentation, shipped inside the Composer package so it is always version-matched to the installed code: - docs/ — 13 task pages with an index carrying the agent-rules banner. Every snippet was executed against a live cloud before being committed. - examples/ — 12 runnable files, one per task page, all verified green. Repository files: - README.md restructured: quick start, common tasks, when to use this SDK, compatibility, and a read path for coding agents. - AGENTS.md (six sections) plus CLAUDE.md; SECURITY.md with private vulnerability reporting; context7.json. Packaging: - .gitattributes decides what ships. docs/ and examples/ reach users at vendor/cloudinary/cloudinary_php/; tests/, tools/, samples/, apidocs/, and the lint/test configs no longer do. - The Sami API-doc tooling moves from docs/ to apidocs/ so that docs/ can hold the Markdown task docs, which is the path agents look for. tools/update_version.sh is updated to match. Corrections found by executing the documented calls rather than reading the source: - The API accessors are methods. The previous README documented $cloudinary->uploadApi->upload(...), which is a fatal error; it is $cloudinary->uploadApi()->upload(...). - ApiUtils is Cloudinary\Api\ApiUtils, although the file sits in src/Api/Utils/. - There is no uploadLarge(); upload() chunks automatically above chunk_size. - A partial configuration array replaces rather than merges, so passing only 'logging' discards credentials from CLOUDINARY_URL.
1 parent 4b989f4 commit 9bfbbdd

45 files changed

Lines changed: 2806 additions & 99 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.gitattributes‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Files excluded from the Composer distribution archive.
2+
#
3+
# Composer ships the whole repository minus these entries, so `docs/` and `examples/`
4+
# reach users at vendor/cloudinary/cloudinary_php/ where coding agents can read them.
5+
# Development, test, and API-doc build tooling is excluded to keep vendor/ lean.
6+
7+
/.github/ export-ignore
8+
/.code-generation/ export-ignore
9+
/apidocs/ export-ignore
10+
/tests/ export-ignore
11+
/tools/ export-ignore
12+
/samples/ export-ignore
13+
/.gitattributes export-ignore
14+
/.gitignore export-ignore
15+
/context7.json export-ignore
16+
/.htaccess export-ignore
17+
/phpcs.xml export-ignore
18+
/phpstan.neon export-ignore
19+
/phpunit.xml export-ignore
20+
/CONTRIBUTING.md export-ignore
21+
/DEVELOPER_GUIDELINE.md export-ignore
22+
/AGENTS.md export-ignore
23+
/CLAUDE.md export-ignore

‎.gitignore‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,9 +4,9 @@ tests/coverage
44
output/
55
.idea
66
composer.phar
7-
docs/sami.phar
8-
docs/cache/
9-
docs/build/
7+
apidocs/sami.phar
8+
apidocs/cache/
9+
apidocs/build/
1010
tools/dev/sanity/node_modules
1111
tools/dev/sanity/package-lock.json
1212
tools/dev/sanity/results.json

‎AGENTS.md‎

Lines changed: 109 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,109 @@
1+
# Contributor guide for coding agents
2+
3+
This file is for agents contributing to this repository. If you are *using* the installed
4+
`cloudinary/cloudinary_php` package in another project, read the bundled docs in
5+
`vendor/cloudinary/cloudinary_php/docs/` instead.
6+
7+
## Commands
8+
9+
```bash
10+
composer install # install dependencies
11+
vendor/bin/simple-phpunit --testsuite Unit # unit tests (mocked, no network)
12+
vendor/bin/simple-phpunit # full suite — needs a live cloud
13+
vendor/bin/phpcs # PSR-2 lint over src/ and tests/
14+
vendor/bin/phpcbf # auto-fix what phpcs can
15+
php examples/upload-image.php # run a documentation example
16+
```
17+
18+
Tests need a `CLOUDINARY_URL` in the environment. `bash tools/get_test_cloud.sh` prints a
19+
throwaway one, which is how CI does it:
20+
21+
```bash
22+
export CLOUDINARY_URL=$(bash tools/get_test_cloud.sh)
23+
```
24+
25+
`phpstan.neon` exists but PHPStan is not in `require-dev`; install it separately if you
26+
want to run it. `phpcs` currently reports pre-existing violations in `src/` and `tests/` —
27+
do not mass-fix them in an unrelated pull request.
28+
29+
## Testing
30+
31+
- `tests/Unit/` is mocked and must never perform network calls.
32+
- `tests/Integration/` requires a real or temporary cloud. Do not run it by default, and
33+
do not add tests there that consume paid add-ons without a skip guard.
34+
- Nondeterministic AI output (captions, tags, moderation verdicts) must be asserted by
35+
request shape, state transition, and response schema — never by exact output values.
36+
- Some operations are unavailable on throwaway sub-account clouds — folder renaming
37+
returns `AuthorizationRequired`. Do not build tests or examples that depend on them.
38+
- `examples/` are executable documentation. If you change one, run it against a live cloud
39+
before committing; they are expected to exit 0 on success and 1 with a readable message
40+
when credentials are missing.
41+
42+
## Project structure
43+
44+
- `src/Cloudinary.php` — entry point. `uploadApi()`, `adminApi()`, and `searchApi()` are
45+
**methods**, and `image()`/`video()`/`imageTag()`/`videoTag()` build URLs and tags.
46+
- `src/Api/` — `Admin/`, `Upload/`, `Search/`, `Provisioning/`, plus `Exception/`.
47+
- `src/Configuration/` — configuration objects; input keys are `snake_case`, properties
48+
are `camelCase`.
49+
- `src/Asset/`, `src/Tag/` — URL builders and HTML tag builders.
50+
- Transformations live in the separate `cloudinary/transformation-builder-sdk` package
51+
under the `Cloudinary\Transformation` namespace, not in this repo.
52+
- `docs/` — version-matched Markdown task docs shipped in the Composer package.
53+
- `examples/` — runnable task examples, one per docs page, shipped in the package.
54+
- `apidocs/` — Sami API-doc generation tooling. Not shipped. Sami is abandoned and fails
55+
on PHP 8; the checked-in `apidocs/build/` output is stale.
56+
- `samples/` — legacy sample pages; not part of the tested example set.
57+
- `tools/` — release and test-cloud shell scripts.
58+
59+
Namespaces do not always mirror directories: `src/Api/Utils/ApiUtils.php` declares
60+
`namespace Cloudinary\Api`. Autoloading is a classmap over `src`, so check the
61+
`namespace` line rather than inferring from the path.
62+
63+
## Code style
64+
65+
- PSR-2, enforced by `phpcs`. Four-space indent, one class per file.
66+
- Examples in `examples/` trip PSR-1's "side effects" warning by design — they declare a
67+
`main()` and call it. Zero errors is the bar there, not zero warnings.
68+
- Public API methods take an options array and return `Cloudinary\Api\ApiResponse`, which
69+
extends `ArrayObject`:
70+
71+
```php
72+
public function upload(mixed $file, array $options = []): ApiResponse
73+
{
74+
return $this->uploadAsync($file, $options)->wait();
75+
}
76+
```
77+
78+
- Async variants (`...Async`) return a Guzzle `PromiseInterface`; the sync method wraps it
79+
with `->wait()`. Add both when adding an API method.
80+
81+
## Git workflow
82+
83+
- Branch from `master`; keep changes focused; one topic per pull request.
84+
- Run `vendor/bin/simple-phpunit --testsuite Unit` before opening a PR.
85+
- Do not rewrite published changelog entries; add new entries at the top.
86+
- The version string lives in `composer.json`, `src/Cloudinary.php` (`const VERSION`), and
87+
`apidocs/sami_config.php`. `tools/update_version.sh` rewrites all three by exact string
88+
match — do not reformat those lines.
89+
- Never commit credentials, `.env` files, or generated output.
90+
91+
## Boundaries
92+
93+
**Always**
94+
- Keep `docs/` and `examples/` consistent with the code they document.
95+
- Execute a documentation snippet against a live cloud before committing it; reading the
96+
source and writing what it appears to do has produced wrong docs repeatedly.
97+
- Keep API secrets out of examples, docs, tests, and fixtures.
98+
99+
**Ask first**
100+
- Changing supported PHP versions, dependencies, or `.gitattributes` `export-ignore`
101+
entries — the latter decides what ships to users' `vendor/`.
102+
- Renaming or removing any public method or exported symbol.
103+
- Changing release, CI, or publishing configuration.
104+
105+
**Never**
106+
- Commit credentials or real account identifiers.
107+
- Perform live network calls in unit tests.
108+
- Document a Cloudinary platform capability as an SDK method unless this package
109+
implements it (see `docs/platform-capabilities.md`).

‎CLAUDE.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
@AGENTS.md

‎README.md‎

Lines changed: 109 additions & 93 deletions
Original file line numberDiff line numberDiff line change
@@ -1,130 +1,146 @@
1-
[![Tests](https://github.com/cloudinary/cloudinary_php/actions/workflows/test.yaml/badge.svg)](https://github.com/cloudinary/cloudinary_php/actions/workflows/test.yaml)
2-
[![license](https://img.shields.io/github/license/cloudinary/cloudinary_php.svg?maxAge=2592000)](https://github.com/cloudinary/cloudinary_php/blob/master/LICENSE)
3-
[![Packagist](https://img.shields.io/packagist/v/cloudinary/cloudinary_php.svg?maxAge=2592000)](https://packagist.org/packages/cloudinary/cloudinary_php)
4-
[![Packagist](https://img.shields.io/packagist/dt/cloudinary/cloudinary_php.svg?maxAge=2592000)](https://packagist.org/packages/cloudinary/cloudinary_php/stats)
5-
6-
Cloudinary PHP SDK
7-
==================
8-
9-
## About
1+
# Cloudinary PHP SDK
102

11-
The Cloudinary PHP SDK allows you to quickly and easily integrate your application with Cloudinary.
12-
Effortlessly optimize, transform, upload and manage your cloud's assets.
3+
Upload, transform, optimize, and manage images and videos with Cloudinary from PHP — the `cloudinary/cloudinary_php` package on Packagist.
134

14-
#### Note
15-
16-
This Readme provides basic installation and usage information.
17-
For the complete documentation, see the [PHP SDK Guide](https://cloudinary.com/documentation/php_integration).
5+
[![Tests](https://github.com/cloudinary/cloudinary_php/actions/workflows/test.yaml/badge.svg)](https://github.com/cloudinary/cloudinary_php/actions/workflows/test.yaml)
6+
[![Packagist](https://img.shields.io/packagist/v/cloudinary/cloudinary_php.svg)](https://packagist.org/packages/cloudinary/cloudinary_php)
7+
[![Downloads](https://img.shields.io/packagist/dm/cloudinary/cloudinary_php.svg)](https://packagist.org/packages/cloudinary/cloudinary_php/stats)
8+
[![License](https://img.shields.io/packagist/l/cloudinary/cloudinary_php.svg)](LICENSE)
189

19-
## Table of Contents
10+
## Install
2011

21-
- [Key Features](#key-features)
22-
- [Version Support](#Version-Support)
23-
- [Installation](#installation)
24-
- [Usage](#usage)
25-
- [Setup](#Setup)
26-
- [Transform and Optimize Assets](#Transform-and-Optimize-Assets)
12+
```bash
13+
composer require cloudinary/cloudinary_php
14+
```
2715

28-
## Key Features
16+
## Quick start
2917

30-
- [Transform](https://cloudinary.com/documentation/php_video_manipulation#video_transformation_examples) and
31-
[optimize](https://cloudinary.com/documentation/php_image_manipulation#image_optimizations) assets.
32-
- Generate [image](https://cloudinary.com/documentation/php_image_manipulation#deliver_and_transform_images) and
33-
[video](https://cloudinary.com/documentation/php_video_manipulation#php_video_transformation_code_examples) tags.
34-
- [Asset Management](https://cloudinary.com/documentation/php_asset_administration).
35-
- [Secure URLs](https://cloudinary.com/documentation/video_manipulation_and_delivery#generating_secure_https_urls_using_sdks).
18+
Set your API environment variable (Console > Settings > API Keys):
3619

37-
## Version Support
20+
```bash
21+
export CLOUDINARY_URL=cloudinary://<api_key>:<api_secret>@<cloud_name>
22+
```
3823

39-
| SDK Version | PHP 5.4 | PHP 5.5 | PHP 5.6 | PHP 7.x | PHP 8.0 - 8.3 | PHP 8.4 |
40-
|-------------|---------|---------|---------|---------|---------------|---------|
41-
| 3.x | ✘ | ✘ | ✘ | ✘ | ✔ | ✔ |
42-
| 2.x | ✘ | ✘ | ✔ | ✔ | ✔ | ✘ * |
43-
| 1.x | ✔ | ✔ | ✔ | ✔ | ✘ | ✘ |
24+
Upload an image and get an optimized delivery URL:
4425

45-
\* Deprecation warnings
26+
```php
27+
<?php
4628

47-
## Installation
29+
require 'vendor/autoload.php';
4830

49-
```bash
50-
composer require "cloudinary/cloudinary_php"
31+
use Cloudinary\Cloudinary;
32+
use Cloudinary\Transformation\Delivery;
33+
use Cloudinary\Transformation\Format;
34+
use Cloudinary\Transformation\Gravity;
35+
use Cloudinary\Transformation\Quality;
36+
use Cloudinary\Transformation\Resize;
37+
38+
try {
39+
$cloudinary = new Cloudinary();
40+
41+
// Upload a remote image (a local file path works the same way).
42+
$result = $cloudinary->uploadApi()->upload(
43+
'https://res.cloudinary.com/demo/image/upload/sample.jpg',
44+
['public_id' => 'quickstart-sample']
45+
);
46+
47+
echo 'Uploaded: ', $result['public_id'], PHP_EOL;
48+
49+
// Build a 400x400 auto-cropped URL with automatic format and quality.
50+
$url = $cloudinary->image($result['public_id'])
51+
->resize(Resize::fill(400, 400)->gravity(Gravity::auto()))
52+
->delivery(Delivery::format(Format::auto()))
53+
->delivery(Delivery::quality(Quality::auto()));
54+
55+
echo 'Optimized URL: ', $url, PHP_EOL;
56+
} catch (Throwable $e) {
57+
fwrite(STDERR, 'Quick start failed: ' . $e->getMessage() . PHP_EOL);
58+
fwrite(STDERR, 'Check that CLOUDINARY_URL is set (Console > Settings > API Keys).' . PHP_EOL);
59+
exit(1);
60+
}
5161
```
5262

53-
# Usage
54-
55-
### Migration
63+
Save as `quickstart.php` and run `php quickstart.php`. [Create a free account](https://cloudinary.com/users/register_free) if you don't have one — or run `npx @cloudinary/cloud` to [provision one without signing up](docs/get-credentials.md).
5664

57-
See the [Cloudinary PHP SDK Migration guide](https://cloudinary.com/documentation/php2_migration) for more information
58-
on migrating to this version of the PHP SDK.
65+
`uploadApi()`, `adminApi()`, and `searchApi()` are methods — call them with parentheses.
5966

60-
The previous (1.x) version of the SDK is located [here](https://github.com/cloudinary/cloudinary_php/tree/support/1.x).
67+
## Common tasks
6168

62-
### Setup
69+
- [Get Cloudinary credentials](docs/get-credentials.md)
70+
- [Import and call the SDK](docs/import-and-call.md)
71+
- [Configure Cloudinary](docs/configure-cloudinary.md)
72+
- [Upload an image](docs/upload-image.md)
73+
- [Upload a large video](docs/upload-large-video.md)
74+
- [Sign a browser upload](docs/sign-browser-upload.md)
75+
- [Transform and deliver an image](docs/transform-and-deliver-image.md)
76+
- [Transform and deliver a video](docs/transform-and-deliver-video.md)
77+
- [Search and manage assets](docs/search-and-manage-assets.md)
78+
- [Moderate an upload](docs/moderate-upload.md)
79+
- [Use structured metadata](docs/use-structured-metadata.md)
80+
- [Troubleshoot errors](docs/troubleshoot-errors.md)
6381

64-
```php
65-
use Cloudinary\Cloudinary;
82+
Runnable versions live in [`examples/`](examples/) — each is a complete file you can run directly.
6683

67-
$cloudinary = new Cloudinary();
68-
```
84+
## When to use this SDK
6985

70-
### Transform and Optimize Assets
86+
Use this package in **PHP server-side code**: uploads, signed operations, asset
87+
administration, search, moderation, and delivery URL generation. It works with any
88+
framework, and with none.
7189

72-
- [See full documentation](https://cloudinary.com/documentation/php_image_manipulation).
90+
For other jobs, better-fitting tools exist:
7391

74-
```php
75-
$cloudinary->image('sample.jpg')->resize(Resize::fill()->width(100)->height(150))->format(Format::auto());
76-
```
92+
- Laravel-native integration with facades and a storage driver: [`cloudinary-labs/cloudinary-laravel`](https://github.com/cloudinary-labs/cloudinary-laravel).
93+
- WordPress, Magento, and similar platforms: [platform integrations](https://cloudinary.com/documentation/integrations) ([md](https://cloudinary.com/documentation/integrations.md)).
94+
- Browser or frontend framework rendering: [frontend SDKs](https://cloudinary.com/documentation/frontend_sdks) ([md](https://cloudinary.com/documentation/frontend_sdks.md)).
95+
- Complete in-browser upload UI: [Upload Widget](https://cloudinary.com/documentation/upload_widget) ([md](https://cloudinary.com/documentation/upload_widget.md)).
96+
- Text-to-image generation and image-to-video: [platform APIs](https://cloudinary.com/documentation/image_generation_addon) ([md](https://cloudinary.com/documentation/image_generation_addon.md)), not wrapped by this package.
97+
- Multi-step media workflow automation: [MediaFlows](https://cloudinary.com/documentation/mediaflows_user_guide) ([md](https://cloudinary.com/documentation/mediaflows_user_guide.md)).
98+
- Interactive agent-driven asset operations: [Cloudinary MCP servers and Skills](https://cloudinary.com/documentation/cloudinary_llm_mcp) ([md](https://cloudinary.com/documentation/cloudinary_llm_mcp.md)).
7799

78-
### Upload
100+
The full capability map — plus the Skills, MCP servers, and CLI worth setting up first —
101+
is in [docs/platform-capabilities.md](docs/platform-capabilities.md).
79102

80-
- [See full documentation](https://cloudinary.com/documentation/php_image_and_video_upload).
81-
- [Learn more about configuring your uploads with upload presets](https://cloudinary.com/documentation/upload_presets).
103+
## Status and compatibility
82104

83-
```php
84-
$cloudinary->uploadApi->upload('my_image.jpg');
85-
```
105+
Stable, actively maintained. See [CHANGELOG.md](CHANGELOG.md).
86106

87-
### Security options
107+
| SDK version | PHP |
108+
|-------------|-----|
109+
| 3.x | 8.0 and later |
110+
| 2.x | 5.6 – 8.3 (no longer maintained) |
111+
| 1.x | 5.4 – 7.x (no longer maintained) |
88112

89-
- [See full documentation](https://cloudinary.com/documentation/solution_overview#security).
113+
The 1.x series lives on the [`support/1.x`](https://github.com/cloudinary/cloudinary_php/tree/support/1.x) branch. Moving from it? See the [migration guide](https://cloudinary.com/documentation/php2_migration) ([md](https://cloudinary.com/documentation/php2_migration.md)).
90114

91-
## Contributions
115+
## Documentation
92116

93-
- Ensure tests run locally
94-
- Open a PR and ensure Travis tests pass
117+
- [Bundled task docs](docs/README.md) — ship inside the package, version-matched.
118+
- [PHP SDK guide](https://cloudinary.com/documentation/php_integration) — the full documentation ([md](https://cloudinary.com/documentation/php_integration.md)).
119+
- [Transformation and API reference](https://cloudinary.com/documentation/cloudinary_references) ([md](https://cloudinary.com/documentation/cloudinary_references.md)).
95120

96-
## Get Help
121+
Documentation links in this README point at the browsable HTML page, with an `(md)`
122+
companion link that returns the same page as raw Markdown. Inside `docs/` and `examples/`
123+
the links are Markdown-only, since those files are written to be read by coding agents.
124+
Either form works for any page: add `.md` for Markdown, drop it for HTML.
97125

98-
If you run into an issue or have a question, you can either:
126+
## For AI coding agents
99127

100-
- Issues related to the SDK: [Open a GitHub issue](https://github.com/cloudinary/cloudinary_php/issues).
101-
- Issues related to your account: [Open a support ticket](https://cloudinary.com/contact)
128+
- Contributing to this repo: read [AGENTS.md](AGENTS.md).
129+
- Using the installed package: the docs in `vendor/cloudinary/cloudinary_php/docs/` match
130+
your installed version and are the source of truth; start with
131+
[platform-capabilities](docs/platform-capabilities.md) before assuming a feature exists.
102132

103-
## About Cloudinary
133+
## Support
104134

105-
Cloudinary is a powerful media API for websites and mobile apps alike, Cloudinary enables developers to efficiently
106-
manage, transform, optimize, and deliver images and videos through multiple CDNs. Ultimately, viewers enjoy responsive
107-
and personalized visual-media experiences—irrespective of the viewing device.
135+
- SDK bugs and feature requests: [GitHub issues](https://github.com/cloudinary/cloudinary_php/issues)
136+
- Account and platform questions: [Cloudinary support](https://support.cloudinary.com)
108137

109-
## Additional Resources
138+
## Security
110139

111-
- [Cloudinary Transformation and REST API References](https://cloudinary.com/documentation/cloudinary_references):
112-
Comprehensive references, including syntax and examples for all SDKs.
113-
- [MediaJams.dev](https://mediajams.dev/): Bite-size use-case tutorials written by and for Cloudinary Developers
114-
- [DevJams](https://www.youtube.com/playlist?list=PL8dVGjLA2oMr09amgERARsZyrOz_sPvqw): Cloudinary developer podcasts on
115-
YouTube.
116-
- [Cloudinary Academy](https://training.cloudinary.com/): Free self-paced courses, instructor-led virtual courses, and
117-
on-site courses.
118-
- [Code Explorers and Feature Demos](https://cloudinary.com/documentation/code_explorers_demos_index): A one-stop shop
119-
for all code explorers, Postman collections, and feature demos found in the docs.
120-
- [Cloudinary Roadmap](https://cloudinary.com/roadmap): Your chance to follow, vote, or suggest what Cloudinary should
121-
develop next.
122-
- [Cloudinary Facebook Community](https://www.facebook.com/groups/CloudinaryCommunity): Learn from and offer help to
123-
other Cloudinary developers.
124-
- [Cloudinary Account Registration](https://cloudinary.com/users/register/free): Free Cloudinary account registration.
125-
- [Cloudinary Website](https://cloudinary.com): Learn about Cloudinary's products, partners, customers, pricing, and
126-
more.
140+
See [SECURITY.md](SECURITY.md) for private vulnerability reporting. Keep your
141+
`api_secret` in server-side code; for client uploads, use the server-signed pattern in
142+
[Sign a browser upload](docs/sign-browser-upload.md).
127143

128-
## Licence
144+
## License
129145

130-
Released under the MIT license.
146+
Released under the MIT license — see [LICENSE](LICENSE). Copyright (c) Cloudinary Ltd.

0 commit comments

Comments
 (0)