From fb3175f1265eda6a72d85322f20f09e1e7c33301 Mon Sep 17 00:00:00 2001 From: achyutkneupane Date: Wed, 29 Oct 2025 02:05:36 +0545 Subject: [PATCH 1/2] docs: updates README with installation, configuration, and usage instructions --- README.md | 212 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 212 insertions(+) diff --git a/README.md b/README.md index ee5d047..a72b5b5 100644 --- a/README.md +++ b/README.md @@ -2,3 +2,215 @@ [![Lint & Test PR](https://github.com/HamroCDN/php-sdk/actions/workflows/prlint.yml/badge.svg)](https://github.com/HamroCDN/php-sdk/actions/workflows/prlint.yml) [![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=HamroCDN_php-sdk&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=HamroCDN_php-sdk) + +> **Official PHP SDK for HamroCDN** β€” a simple, typed, and framework-agnostic way to upload, fetch, and manage files from your HamroCDN account. + +--- + +## πŸ“¦ Installation + +Install via [Composer](https://getcomposer.org/): + +```bash +composer require hamrocdn/sdk +``` + +That’s it. +No Laravel dependencies, no magic β€” just pure PHP. + +--- + +## βš™οΈ Configuration + +You can pass your API key directly, or rely on environment/config values if available. + +```php +use HamroCDN\HamroCDN; + +$cdn = new HamroCDN('your-api-key'); +``` + +Alternatively, if your environment has them: + +```bash +export HAMROCDN_API_KEY="your-api-key" +``` + +the SDK automatically detects and uses them. + +--- + +## πŸš€ Usage + +### 1. List Uploads (Paginated) + +The `index()` method returns paginated results. +You can provide pagination parameters such as `page` and `per_page`. + +```php +$uploads = $cdn->index(page: 1, per_page: 10); + +foreach ($uploads->all() as $upload) { + echo $upload->getNanoId() . ' - ' . $upload->getOriginal()->getUrl() . PHP_EOL; +} +``` + +> Returns an object containing `data` (array of `Upload` models) and `meta` (pagination info). + +Example of returned metadata: +```json +{ + "meta": { + "total": 120, + "per_page": 10, + "page": 1 + } +} +``` + +--- + +### 2. Fetch a Single Upload + +```php +$upload = $cdn->fetch('abc123'); + +echo $upload->getOriginal()->getUrl(); // https://hamrocdn.com/abc123/original +``` + +--- + +### 3. Upload a File + +```php +$upload = $cdn->upload('/path/to/image.png'); + +echo $upload->getNanoId(); // nano ID of the uploaded file +``` + +--- + +### 4. Upload by Remote URL + +```php +$upload = $cdn->uploadByURL('https://example.com/image.png'); + +echo $upload->getOriginal()->getUrl(); +``` + +--- + +## 🧱 Models + +### πŸ—‚ `HamroCDN\Models\Upload` + +| Property | Type | Description | +|------------|--------------------|--------------------------------------| +| `nanoId` | `string` | Unique identifier of the upload | +| `user` | `User` or `null` | Owner of the file (if authenticated) | +| `deleteAt` | `string` or `null` | Deletion timestamp if temporary | +| `original` | `File` | File information (URL, size) | + +#### Methods +- `getNanoId()`: `string` +- `getUser()`: `?User` +- `getDeleteAt()`: `?string` +- `getOriginal()`: `File` +- `toArray()`: `array` + +--- + +### πŸ‘€ `HamroCDN\Models\User` + +| Property | Type | Description | +|----------|----------|-----------------------| +| `name` | `string` | Name of the uploader | +| `email` | `string` | Email of the uploader | + +#### Methods +- `getName()`: `string` +- `getEmail()`: `string` +- `toArray()`: `array` + +--- + +### 🧾 `HamroCDN\Models\File` + +| Property | Type | Description | +|----------|----------|--------------------| +| `url` | `string` | Public CDN URL | +| `size` | `int` | File size in bytes | + +#### Methods +- `getUrl()`: `string` +- `getSize()`: `int` +- `toArray()`: `array` + +--- + +## ⚑ Error Handling + +All SDK errors extend `HamroCDN\Exceptions\HamroCDNException`. + +Example: + +```php +use HamroCDN\Exceptions\HamroCDNException; + +try { + $cdn->upload('/invalid/path.jpg'); +} catch (HamroCDNException $e) { + echo 'Upload failed: ' . $e->getMessage(); +} +``` + +The SDK automatically wraps: +- Network issues (`GuzzleException`) +- Invalid JSON responses +- Missing API key or misconfiguration + +--- + +## πŸ§ͺ Testing + +The SDK is fully covered with [Pest](https://pestphp.com/) tests. + +Run tests locally: + +```bash +composer test +``` + +--- + +## πŸͺ„ Framework Integrations + +This SDK is **framework-agnostic**. If you’re using **Laravel**, check out the companion package: + +πŸ‘‰ [**hamrocdn/laravel**](https://packagist.org/packages/hamrocdn/laravel) + +It provides service providers, configuration publishing, and automatic Facade binding. + +--- + +## 🧩 Type Safety/Static Analysis + +- Fully typed with PHPStan annotations +- 100% PHP 8.0+ compatible +- Pint with `laravel` preset for code style +- Rector for automated refactoring +- SonarCloud integration for code quality + +--- + +## πŸ“„ License + +This package is open-sourced software licensed under the [MIT license](LICENSE.md). + +## 🀝 Contributing + +Contributions are welcome! Please create a pull request or open an issue if you find any bugs or have feature requests. + +## ⭐ Support + +If you find this package useful, please consider starring the repository on GitHub to show your support. From 8f4606a0cbb2d85528bc50d0f0733cd154f6a4d7 Mon Sep 17 00:00:00 2001 From: achyutkneupane Date: Wed, 29 Oct 2025 02:12:38 +0545 Subject: [PATCH 2/2] docs: updates README with requirements and quick start example --- README.md | 37 ++++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a72b5b5..32d1dc8 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,10 @@ Install via [Composer](https://getcomposer.org/): composer require hamrocdn/sdk ``` +### Requirements +- PHP **8.0+** +- [GuzzleHTTP](https://github.com/guzzle/guzzle) 7.10+ + That’s it. No Laravel dependencies, no magic β€” just pure PHP. @@ -40,12 +44,34 @@ the SDK automatically detects and uses them. --- +## ⚑ Quick Start + +Here’s a quick example showing upload and fetch in action: + +```php +use HamroCDN\HamroCDN; + +$cdn = new HamroCDN('your-api-key'); + +// Upload a file +$upload = $cdn->upload('/path/to/image.jpg'); + +echo "Uploaded: " . $upload->getOriginal()->getUrl() . PHP_EOL; + +// Fetch it again +$fetched = $cdn->fetch($upload->getNanoId()); + +echo "Fetched: " . $fetched->getOriginal()->getUrl() . PHP_EOL; +``` + +--- + ## πŸš€ Usage ### 1. List Uploads (Paginated) The `index()` method returns paginated results. -You can provide pagination parameters such as `page` and `per_page`. +You can provide pagination parameters such as `page` and `per_page`: ```php $uploads = $cdn->index(page: 1, per_page: 10); @@ -173,7 +199,8 @@ The SDK automatically wraps: ## πŸ§ͺ Testing -The SDK is fully covered with [Pest](https://pestphp.com/) tests. +This SDK is built with [Pest](https://pestphp.com/) and supports **real API integration tests**. +A dedicated testing environment is configured within the HamroCDN infrastructure, ensuring safe, production-like validations. Run tests locally: @@ -193,7 +220,7 @@ It provides service providers, configuration publishing, and automatic Facade bi --- -## 🧩 Type Safety/Static Analysis +## 🧩 Type Safety / Static Analysis - Fully typed with PHPStan annotations - 100% PHP 8.0+ compatible @@ -207,10 +234,14 @@ It provides service providers, configuration publishing, and automatic Facade bi This package is open-sourced software licensed under the [MIT license](LICENSE.md). +--- + ## 🀝 Contributing Contributions are welcome! Please create a pull request or open an issue if you find any bugs or have feature requests. +--- + ## ⭐ Support If you find this package useful, please consider starring the repository on GitHub to show your support.