Download the PHP package minhyung/mybox without Composer

php-mybox

A framework-agnostic PHP SDK for the Naver MYBOX Open API.

한국어 문서는 README.ko.md를 참고하세요.

• Covers all 20 published endpoints, one typed method each
• PSR-18 / PSR-17 based — brings no HTTP client of its own
• Readonly models and backed enums instead of associative arrays
• Transparent cursor pagination, streaming uploads and downloads
• Automatic backoff on the statuses that deserve it, and a typed exception per error code

Requirements

PHP 8.2 or newer.

Installation

The SDK talks to whatever PSR-18 HTTP client your project already has, and finds it through php-http/discovery — no wiring needed. If you do not have one yet, any of these will do:

Getting a personal access token

1. Sign in to MYBOX on the web with your Naver account.
2. Go to 설정 → 계정 및 개인 액세스 토큰 관리 and click 토큰 생성.
3. Give the token a name and an expiry of 30, 60, 90, or 180 days.
4. Copy it immediately — it is shown exactly once.

An account can hold at most five tokens. Treat one like a password: anybody holding it has full access to your drive.

Quick start

Endpoints

Everything is grouped the way the official documentation groups it.

drive() — reading and favourites

listRootAll() and listFolderAll() return a paginator over the same data.

files() — mutations and transfer URLs

search() — the search index

filesAll() and foldersAll() page through the results.

trash()

listAll() pages through the trash.

Listing and sorting

MYBOX always lists folders before files, whatever you sort by.

Pagination

Uploading

Each returns an UploadResult carrying the stored file's resourceId, name and fileSize. Uploads stream — a 10 GB file uses no more memory than a 10 KB one.

The declared size must match the payload exactly; MYBOX reserves the upload against it and answers 500 on a mismatch. maxFileBytes from storage() is the per-file ceiling.

Sending the bytes is a second call to a separate storage host, and its wire format is not part of the published documentation. It was established against the live service and is written up in docs/transfer-protocol.md.

resume: true asks MYBOX whether it kept part of an earlier, interrupted transfer and continues from there. Two quirks are worth knowing, both handled for you: MYBOX identifies the interrupted upload by the modifiedTime string and only recognises the KST spelling, so the SDK always sends KST whatever timezone you are in; and isOverwrite suppresses the offset, so do not combine the two.

Downloading

Each call issues a fresh URL. MYBOX documents these as single-use and valid for ten minutes. Downloads stream too, so toFile() is bounded by disk rather than by memory.

Searching

A search needs at least one of q, category, or a date bound — the SDK rejects an empty query locally rather than spending one of your quota slots on it. Page size is 20–200 here, not 1–1000.

Paths

MYBOX addresses everything by id. To start from a path instead:

A folder normally resolves in a single search call; when the index has not caught up the resolver walks down from the root instead. Results are memoised per client — call clearCache() after renaming or moving something.

Error handling

Every failure is a MyboxException. The API's own errors are ApiException subclasses carrying the requestId you would quote to support:

Connection failures and unparseable responses raise TransportException; arguments rejected before any request raise InvalidArgumentException.

Retries

429, 502, and 503 are retried three times with exponential backoff and full jitter, honouring Retry-After when the server sends one. 500 is not retried — MYBOX returns it for genuine faults rather than congestion.

Rate limits

Quotas come from the account's MYBOX plan and are enforced per API, not in aggregate. Daily counters reset each day, per-minute counters each minute.

MYBOX also states that bursts it reads as abuse can restrict an account without prior warning.

Behaviour worth knowing

• Trashing does not hide a resource from get(). After delete() the id stays readable and only its parentId changes. Check a listing, not get(), to tell whether something was deleted.
• Purging is eventually consistent. Right after trash()->purge() the id answers for well under a second before it starts returning 404.
• An interrupted upload locks the file. Reserving another upload for it answers 423 LockedException until the server releases the transfer.

What the API does not cover

• Password-protected folders (암호 폴더, available on 180GB and larger plans) and folders shared with you are not reachable through the Open API at all; they only appear in the desktop and mobile apps.
• An account that is over quota or under sanction cannot use its tokens.
• Calling the API with a token belonging to a dormant account reactivates it.

Custom HTTP wiring

Discovery finds your PSR-18 client automatically, but you can pass one in — useful for proxies, custom timeouts, or logging middleware:

Flysystem

minhyung/flysystem-mybox wraps this SDK in a Flysystem v3 adapter, so MYBOX can be used through League\Flysystem\Filesystem or as a Laravel Storage disk. It passes Flysystem's adapter conformance suite.

Use it when you want portable filesystem code, and this SDK directly when you want the parts Flysystem has no vocabulary for — the trash, favourites, storage quota, search, and resumable uploads.

Contributing

CONTRIBUTING.md covers the layout, the conventions, how to add an endpoint, and the rules for the integration suite — which talks to a real account and is excluded from composer test.

Changelog

See CHANGELOG.md.

License

MIT. See LICENSE.