Configuring Snuze

How it Works

All configuration for Snuze is controlled by an array you pass into the SnuzeFactory. Each element in the array corresponds to a configuration parameter. Some of these options control authentication, some control persistence, and others modify how Snuze behaves when it's running.

The first part of any Snuze bot/script will look something like this:

<?php
require_once __DIR__ . '/vendor/autoload.php';

/* Set authentication and configuration parameters */
$config = [
   'auth.client_id'     => 'your-client-id-from-reddit',
   'auth.client_secret' => 'your-secret-from-reddit',
   'auth.username'      => 'your-reddit-username',
   'auth.password'      => 'your-reddit-password',
   'auth.user_agent'    => 'php:YourAwesomeBot 1.2.3 (by /u/your-reddit-username)',
];

/* Pass the config array to a SnuzeFactory to get a Snuze object */
$snuze = (new \snuze\SnuzeFactory($config))->getSnuze();

/* Now do something with Snuze */
$links = $snuze->fetchLinksNew('funny', 10);
//...

In the above example, the $config array contains only the mandatory authentication parameters. These don't have default values; you must set all five of them, or Snuze won't run.

Other parameters are optional and have default settings. To override a default value, just add a new element to your $config array with the appropriate key name and your desired setting. The full selection of options is outlined below.

Configuration Parameter List

auth.client_id

Default value: none. Setting this parameter is required.

This must be set to the unique client ID you received from Reddit (see the "First Steps" listed here).

auth.client_secret

Default: none. Setting this parameter is required.

This must be set to the client secret you received from Reddit (see the "First Steps" listed here).

auth.password

Default value: none. Setting this parameter is required.

This must be set to the password for the Reddit account specified in auth.username.

auth.user_agent

Default value: none. Setting this parameter is required.

This must be set to a string of your choosing that uniquely identifies your bot, script, or application. Make sure to use an identifier that complies with Reddit's API Rules. In particular, it should contain a name and version number for your bot, as well as your Reddit username.

auth.username

Default value: none. Setting this parameter is required.

This must be set to the username of the Reddit account your bot/script will be running as.

It's recommended that you create a separate Reddit account for your Snuze scripts, even if they're just doing read-only operations. That way, if your scripts or server are ever compromised, no one gets the password to your main Reddit account.

autosleep

Default value: true

Reddit's API is rate limited, allowing a maximum of 600 requests in any given ten-minute period. Snuze keeps track of the current rate limit state. When autosleep is true, Snuze will automatically pause as necessary whenever your application exceeds the rate limit. When autosleep is false, busting the rate limit will cause Snuze to throw a RateLimitException instead.

log.filename

Default value: snuze.log

Unless you explicitly tell it not to (see log.severity), Snuze will write log messages to a text file on disk. This parameter defines the location of the log file. The default is to use a file named snuze.log in the current working directory. You can specify either a filename or a fully-qualified path like /tmp/mybot.log.

If you use Snuze for multiple bots/scripts, it's recommended that you configure each one to use a different log file. This will make debugging easier if something goes wrong.

log.label

Default value: none

All Snuze log messages begin with a preamble that includes the date and time, the severity of the log entry, and the Snuze internal version number. If you like, you can add an additional label by setting a value for log.label.

log.severity

Default value: WARNING

This must be set to one of the literal strings NONE, ERROR, WARNING, INFO, or DEBUG. These become increasingly verbose:

Log Level	What's logged?
NONE	Nothing. Snuze won't even attempt to create the log file.
ERROR	All exceptions thrown by Snuze, even if you catch them.
WARNING	ERROR, plus warnings when something looks wrong but isn't fatal.
INFO	WARN, plus information about many Snuze actions. This gets chatty.
DEBUG	Everything, right down to objects being instantiated.

The 'DEBUG' severity should be used for temporary troubleshooting only. It generates copious amounts of large log entries including all HTTP traffic, JSON responses, etc.

Warning! In DEBUG log mode, your Reddit username and password will be written to the log file!

storage.enabled

Default value: true

Whether or not you want to use any of the persistence features in Snuze. The default setting is to enable storage via the SQLite storage provider (see storage.namespace), so that API authentication tokens can be stored and re-used. If you set this to false, that feature will stop working, and no other persistence capability will be available.

storage.namespace

Default value: \snuze\Persistence\SQLite

When storage.enabled is true, this must be set to the PHP namespace corresponding to a valid Snuze storage provider. Snuze comes with two built-in storage providers:

Provider	Namespace
SQLite	\snuze\Persistence\SQLite
MySQL	\snuze\Persistence\MySQL

The default setting is to enable storage using the SQLite provider. This will work out of the box in most cases, but only supports persisting API authentication tokens.

Switching to the MySQL storage provider involves some extra setup. See the Persistence documentation for details.

storage.parameters

Default value: ['filename' => 'snuze.sqlite']

When storage.enabled is true, this must be set to an array containing any parameters expected by the storage provider. The default setting tells the SQLite storage provider to save authentication tokens in a file named snuze.sqlite.