Tumblr Laravel Package

Getting Started

1. Install: composer require jaapz/tumblr.
2. Get credentials at tumblr.com/oauth/apps. Read-only access needs just the consumer/API key.
3. Register it in config/services.php:

   'tumblr' => [
       'key'    => env('TUMBLR_API_KEY'),
       'secret' => env('TUMBLR_API_SECRET'),
   ],
   

4. First use case — fetch a public blog to validate without OAuth:

   $api  = new \Jaapz\Tumblr\API(config('services.tumblr.key'));
   $info = $api->getBlogInfo('staff.tumblr.com');
   $feed = $api->getBlogPosts('staff.tumblr.com', ['limit' => 20]);
   

Before wiring anything else, read vendor/jaapz/tumblr/src — the package is small, so the entire public surface fits on one screen. Method names, return shapes (stdClass vs array), and whether OAuth is included are the details you need before designing around it.

Implementation Patterns

• Bind once: register the client as a singleton in a TumblrServiceProvider and inject it into a TumblrService / TumblrRepository class. Controllers should never touch the raw client — you want a seam that makes it trivial to swap in raw Guzzle later.
• Cache reads aggressively: Cache::remember("tumblr:{$blog}:posts:{$offset}", 900, fn () => $api->getBlogPosts($blog, ['offset' => $offset, 'limit' => 20])); The rate limits justify it, and Tumblr responses are stable enough to cache for 10–15 minutes.
• Scheduled sync: a tumblr:sync artisan command (scheduled in Kernel/Console\Kernel) iterating configured blog hostnames, dispatching SyncTumblrBlogJob per blog. Use Bus::batch() so failures are isolated per blog.
• Multi-blog / multi-tenant: keep blog hostnames in a config array or blogs table, not scattered through code — mysite.tumblr.com is the API identifier, not the display name.
• Persistence: map responses into Eloquent models or DTOs immediately. Don't let stdClass blobs leak into views or Livewire payloads.
• Pagination: Tumblr returns total_posts and accepts offset + limit (max 20). Loop with offset += 20 until offset >= total_posts, but checkpoint the offset so a resumed job doesn't re-fetch everything.
• Write operations (post, reblog, queue, like): store OAuth 1.0a access tokens per user in a social_accounts-style table and sign requests yourself — the wrapper is primarily a read client.

Gotchas and Tips

• Read-only by default. The API key only allows public reads. Anything that mutates state needs full OAuth 1.0a (consumer key/secret + access token/secret). The package likely does not ship an OAuth flow — plan on league/oauth1-client or hand-rolled signing.
• Check meta.status, not just HTTP status. Tumblr returns { meta: { status: 200, ... }, response: { ... } }. A 200 HTTP response can still wrap a 404 or 401 in meta.
• Rate limits are 5,000/hour and 250/minute per consumer key. Batch jobs must throttle; a naive "sync 50 blogs on boot" command will burn the quota.
• Blog identifier is the hostname (myblog.tumblr.com), not the display name or slug. Passing the wrong form yields silent 404s.
• Two post shapes. Newer posts use NPF (content blocks, layout); older wrappers assume the legacy body / photos fields. Handle both, or rich content silently disappears.
• No Laravel auto-discovery worth relying on — register the provider and merge the config yourself.
• Test against staff.tumblr.com for the read path; it's public and stable. For the write path, isolate the client behind an interface and mock that rather than the cURL layer.
• Pin the version. Low stars and slow maintenance means a composer.lock is your friend; treat the package as a thin transport, not a domain layer.