Snuze, a (fledgling) PHP client for the Reddit API
About Snuze
Snuze is a PHP client interface for Reddit's API.
Snuze is designed to help you quickly build bots or other applications that interact with the Reddit service, without having to learn much about how Reddit's API works. Some of Snuze's key features include:
- Retrieve data about subreddits, submissions, and users (interactive features are on the way)
- Entity classes for working with Reddit "thing" objects:
Subreddit
,Link
,Account
, etc. - Supports OAuth authentication for Reddit "script application" apps
- Automatic tracking of Reddit's API rate limit state; can auto pause as needed
- Includes basic MySQL persistence to store data fetched from the API
You can use one installed copy of Snuze to power multiple bots or scripts that interact with Reddit under different accounts.
Preview Release Phase
Snuze is in a preview release phase with limited functionality. The current version supports some common read-only actions while the overall design is being stabilized. Use this release to spider Reddit data for analysis, scan your favorite subreddits for new links, or other tasks that don't involve posting/submitting data. See the feature roadmap for details about what's coming next.
Overview Contents:
- Usage Overview
- Persistence Overview
- Requirements
- Installing Snuze
- Configuration
- Feature Roadmap
- Reporting Bugs and Getting Help
Usage Overview
Snuze is object-oriented, and comes with a set of classes that encapsulate common
Reddit entities. You configure and interact with a Snuze
object, and it returns other objects for accessing the underlying data.
For example, when you fetch a subreddit, Snuze will give you
a Subreddit
object:
$sub = $snuze->fetchSubreddit('funny'); echo 'I got a subreddit called ' . $sub->getDisplayName() . PHP_EOL; echo 'It has ' . $sub->getSubscribers() . ' subscribers!' . PHP_EOL;
I got a subreddit called funny It has 25802523 subscribers!
When you fetch some links from a subreddit, Snuze returns an iterable collection of
Link
objects:
foreach ($snuze->fetchLinksHot('jokes', 3) as $link) { echo 'I found a joke: ' . $link->getTitle() . PHP_EOL; }
I found a joke: Why don't blind people skydive? I found a joke: How do you get Dick from Richard? I found a joke: My doctor told me today that I was too sweet.
You can also get the raw JSON, if you want to. Snuze exposes it through a toJson()
method:
PHP code
$userJson = $snuze->fetchUser('shaunc')->toJson();
See the Using Snuze page for a closer look at some common activities.
A complete class and method reference is available to see what each type of object can do.
Persistence Overview
If you want to save what you fetch, Snuze supports persisting some Reddit data. Two storage providers are built in:
- SQLite:
The SQLite storage provider lets Snuze keep track of API authentication tokens in a small data file. This reduces requests to Reddit's servers, making you a more polite API user. The SQLite storage provider requires no setup and no database server, but is limited to storing auth tokens only. This is the default storage provider.
- MySQL:
In addition to storing authentication tokens, the MySQL storage provider lets you persist certain objects (subreddits, links, comments etc.) from within your application. This can be useful if you want to perform some analysis on the Reddit data you retrieve. Using the MySQL persistence requires a MySQL server.
Each storage provider implements Mapper
objects that let you save or load
objects from storage. You get a Mapper
of the desired type from the Snuze
instance, and use it to store or retrieve an object. For example,
//Save the 100 newest posts from /r/pics to the database foreach ($snuze->fetchLinksNew('pics', 100) as $link) { $snuze->getLinkMapper()->persist($link); } //Load /r/memphis from the database, if it exists there if ($sub = $snuze->getSubredditMapper()->retrieve('memphis')) { echo "{$sub->getDisplayNamePrefixed()}: {$sub->getPublicDescription()}" . PHP_EOL; }
r/memphis: The Reddit community of Memphis, TN.
Of course, you can ignore these storage providers altogether, and have your application save data on its own.
Requirements
Snuze has the following hard requirements:
- PHP 7.2 or newer, capable of running from the command line
- Composer to handle installation and create the autoloader
- A Reddit account
While not absolutely necessary, it's also useful to have:
- PHP's
pdo_sqlite
extension, version 3.20.1 or newer; this is enabled by default in modern PHP installs - PHP's
pdo_mysqli
extension, only if you want to use the MySQL storage provider
Installing Snuze
Snuze source code is available directly from GitHub and via Packagist.
It's strongly encouraged that you use Composer to install Snuze. This is the only supported installation method.
Create a directory where you want to develop your Reddit bot(s) or
script(s), then run composer require --dev snuze/snuze
to pull in Snuze:
[user@host ~]$ mkdir mybot && cd mybot [user@host ~/mybot]$ composer require --dev snuze/snuze
The --dev
is important, as the current release version is < 1.0. This will
install Snuze inside of Composer's standard vendor
directory structure.
Now you're ready to create your first Snuze script! Visit the Getting Started
page to get a basic script up and running in just a few minutes.
Configuration
All configuration for Snuze is controlled by an array you pass into the
SnuzeFactory
.
To see an example, check out the Getting Started page.
For a complete list of options, see the Configuration page.
Feature Roadmap
Snuze is being actively developed, but the current "zero branch" is a preview release and has limited functionality. It can handle the following types of objects:
- Fetch and persist
Subreddit
entities - Fetch and persist
Link
entities (aka posts or submissions) - Fetch and persist
Account
entities
Future releases will adhere to the following milestones, give or take:
- 0.8: (current)
- 0.9: Fetch and persist
Comment
entities -
- 1.0: Implement search endpoints to find links by user-defined criteria
- 1.1: Retrieve user submission and comment history
- 1.2: Submit links
- 1.3: Post comments
- 1.4: Fetch and persist
Message
entities - 1.5: Send and reply to messages
- 1.?: ???
- 1.n: Begin introducing moderation capabilities?
There's no particular time frame for any given milestone.
Reporting Bugs and Getting Help
If you find a bug in Snuze and you have a GitHub account, the best way to report it is to open a new GitHub issue. Describe what happened, and if Snuze threw an exception, please include it in your report. If the bug can be intentionally reproduced, try to add a snippet of code that will trigger it.
To report a bug without a GitHub account, or for general questions, suggestions, and other discussions, check out /r/snuze on Reddit.