Download the PHP package avansaber/php-reddit-api without Composer

avansaber/php-reddit-api

Modern, fluent, framework-agnostic Reddit API client for PHP (PSR-18/PSR-7/PSR-3).

Features

• PSR-18 HTTP client and PSR-7/17 factories (bring your own client)
• Typed DTOs: Link, Comment, User, Subreddit, Message, Flair
• Resources: me, search, subreddit (with listings), user, comments, messages, moderation, flair
• Write actions: vote, reply, submit posts, edit, delete, save/unsave, hide/unhide
• Private messages: inbox, sent, unread, compose, markRead
• Moderation: approve, remove, lock/unlock, sticky, distinguish, NSFW/spoiler marking
• Token storage with optional SQLite + sodium encryption
• CSRF protection helpers for OAuth (state parameter validation)
• Auto-refresh tokens on 401
• Retries/backoff for 429/5xx

Requirements

• PHP 8.1+
• Any PSR-18 HTTP client and PSR-7/17 factories (auto-discovered via php-http/discovery)

Installation

To run the examples, install a PSR-18 client implementation (discovery will find it):

Getting Reddit API credentials

• Log in to Reddit, open https://www.reddit.com/prefs/apps.
• Click “create another app”.
• For app-only reads, choose type “script”. For end-user auth, choose “web app” (Authorization Code) and set a valid redirect URI.
• Fill name and description, then create.
• Copy:
  • Client ID: the short string directly under your app name (next to the app icon). For “personal use script” apps this is a 14‑character string shown under the app name.
  • Client Secret: the value labeled “secret” on the app page (not present for “installed” apps).
• Provide a descriptive User-Agent per Reddit policy, e.g. yourapp/1.0 (by yourdomain.com; contact [email protected]).

Quickstart

Authentication

• App-only (client credentials) for read endpoints like search:

• Using an existing user token:
  • Set REDDIT_ACCESS_TOKEN and run examples/me.php. Authorization Code + PKCE (with CSRF protection)
• Generate PKCE pair, state parameter, and build the authorize URL. Validate state on callback:

Temporary manual Authorization Code exchange (for testing)

Scopes

• Reddit uses space-separated scopes when requesting tokens. Common scopes used by this package:

Common usage

• Search posts:

• Pagination helper example:

• User history (comments/submitted):

• Subreddit info: $sr = $client->subreddit()->about('php');
• User info: $u = $client->user()->about('spez');

• Voting and replying (requires user-context token with proper scopes):

• Submit a text post:

• Get comments on a post:

• Subreddit listings (hot, new, top, rising):

• Subscribe/unsubscribe:

• Private messages:

• Moderation:

• Flair management:

Rate limiting and retries

• Reddit returns x-ratelimit-remaining, x-ratelimit-used, x-ratelimit-reset headers.
• The client parses these headers and exposes the latest via $client->getLastRateLimitInfo().
• The client retries 429/5xx with exponential backoff and respects Retry-After when present.

Error handling

• Methods throw Avansaber\RedditApi\Exceptions\RedditApiException on non-2xx.
• You can inspect getStatusCode() and getResponseBody() for details.

HTTP client setup

• By default we use discovery to find a PSR-18 client and PSR-7/17 factories.
• Alternatively, install and wire your own (e.g., Guzzle + Nyholm PSR-7) and pass them to the constructor.

Framework integration (Laravel, CodeIgniter, etc.)

• Works in any framework as long as a PSR-18 client and PSR-7/17 factories are available (use discovery):

• Laravel bridge (first-class)

  • Repository: https://github.com/avansaber/avansaber-laravel-reddit-api

  • Install:

  • Publish config and migrations:

  • OAuth routes provided: /reddit/connect, /reddit/callback
  • Env keys to set: REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET, REDDIT_REDIRECT_URI, REDDIT_USER_AGENT, REDDIT_SCOPES
  • After connecting, tokens are stored in reddit_tokens. Resolve Avansaber\RedditApi\Http\RedditApiClient from the container and call APIs.

• Laravel (manual wiring, if not using the bridge)

  • In App\Providers\AppServiceProvider → register():

  • In config/services.php:

  • Example usage in a controller:

  • For user-context (vote/reply), obtain a user access token (e.g., Socialite Providers: Reddit, or README’s temporary curl step) and call $client->withToken($userAccessToken).
• CodeIgniter 4
  • Create a service in app/Config/Services.php that returns RedditApiClient using discovery (same as above), then type-hint it in controllers.
  • Provide env keys: REDDIT_USER_AGENT, REDDIT_CLIENT_ID, REDDIT_CLIENT_SECRET.

Examples

• App-only + Search: examples/app_only_search.php
• Me endpoint with existing token: examples/me.php
• PKCE OAuth flow with CSRF: examples/pkce_auth.php
• Voting on posts/comments: examples/voting.php
• Pagination through results: examples/pagination.php
• Auto-refresh token handling: examples/auto_refresh.php
• Moderation actions: examples/moderation.php

Laravel

• See the Laravel bridge package for first-class Laravel support.

Troubleshooting (403 "whoa there, pardner!")

• Reddit may block requests based on IP/UA policies (common with VPN/DC IPs or generic UAs).
• Use a descriptive UA including your Reddit username, e.g. macos:avansaber-php-reddit-api:0.1 (by /u/YourRedditUsername).
• Run from a residential network; avoid VPN/corporate IPs. Add small delays between calls.
• If still blocked, file a ticket with Reddit and include the block code from the response page.

Security notes

• Treat client secrets and access tokens as sensitive. Use environment variables and do not commit them.
• Rotate secrets if they were exposed during testing.

Contributing

• See CONTRIBUTING.md

Changelog

• See CHANGELOG.md. We follow Conventional Commits and tag releases.

Security

• See SECURITY.md

License

• MIT