State Decoded comes with a command line tool, statedecoded. This
tool provides a non-web method to perform common actions, such as importing data
and managing editions.
Note: to use this tool, the PHP CLI will need to be
installed. (This is installed by default on most systems that have PHP.) On
linux/unix systems, the tool should be set to be executable to be able to run it
directly, but it may also be run as a normal PHP script (php statedecoded
arguments); the examples below assume it is being run as a
standalone executable. Due to path resolution, you'll probably need to run it
with the path prefix as well – if you're in the root of the statedecoded
directory, it will be ./statedecoded.
All commands are run with the statedecoded command. You can run
statedecoded help to see all available commands, and you can use
statedecoded help command to see an explanation of a
specific command along with all available options for it.
Many commands use the -v=# option to change the output
verbosity. Messages are weighted by importance, so a verbosity of 1 will show
all message, up to a maximum of 10 for only important messages. Any number above
10 should silence most, if not all messages.
Instead of having to use the admin area of The State Decoded to parse data
files to import legal codes, the command line tool can be run. This is helpful
if the data is provided on a regular basis, allowing the script to be run as
part of a cron job, scheduled task, or similar.
The default import command (statedecoded import) will import
data from the files in the directory specified in the config file as
IMPORT_DATA_DIR. You may override this to use a different directory
with the -d=directory option.
By default, the data is imported into the current edition. You may specify a
different edition to update with the --edition=slug option
by specifying the edition slug. Note that you cannot create a new edition using
the import command, you must use the
Create Edition command first.
You may make the selected edition current by using the --current
option.
You may clear the metadata associated with laws via the
statedecoded clear-metadata command. By default this removes all
metadata associated with laws for all editions. You may specify a specific
edition to clear with the --edition=slug option, and/or
a particular field to clear out with the --field=field
option. For instance, to clear out all court decisions (which is a good thing
to do every few months to remove stale data), you may run the command
statedecoded --field=court_decisions
You can test whether your environment is setup properly to run The State
Decoded by running the statedecoded test-env command. This test
is also run automatically before attempting to import data. If the environment
is not sufficient, errors will be listed, and the command will return with an
error code of 1.
When writing new code for The State Decoded, you may need to modify the database - to create tables, modify existing ones, or manipulate data. To do this in a way that is repeatable without modifying our base database definitions, we use database migrations.
These are scripts that describe the changes to the database in a way that can easily be reproduced.
To run all migrations that have not been run yet, use the statedecoded
migrate command. To "roll back" (undo) all of the migrations, use the
statedecoded migrate --down option.
To generate a new database migration file, run the statedecoded
generate-migration command. This command will print out the name of the
newly-generated migration file.
Inside of this file, you will find a class with two methods: an
up method for making changes to the database, and a
down method for undoing those changes when rolling back. You
should fill out both methods when creating a migration, if all changes are able
to be undone. In general, MySQL will not let you modify a database table such
that data is truncated, such as when chaning the size of a field or index – so
for those operations you should not provide a down
method.
Migrations use standard SQL queries, wrapped by our database wrapper into a
single database transaction. The $this->queue() method is used
to queue up queries, and these must be run by the $this->execute()
method. Please have a look at the existing migration files in the
includes/migrations/ directory for examples.
Note:Migrations are run in the order of their file names. These files are timestamped to avoid collisions. Unlike some other migration tools, we keep track of which migrations have been run and execute all migrations that have not been run, so you shouldn't need to worry out-of-order migrations being lost from merging branches.
You can manipulate editions with several builtin commands.
Note: As of now, you cannot make an edition current with these commands, you must do that at the time you are importing data. This is due to the complex changes to permalinks that must occur when an edition is made current.
To get the name of the current edition, you can use the statedecoded
edition command. To get a list of all editions, use the
statedecoded edition list command. For both of these commands, you
may add the -v (verbose) flag to receive all of the data about the
editions as a JSON-formatted string.
To create a new edition, use the statedecoded edition create
--name=name command. You may optionally specify a slug for the
edition with the --slug=slug flag, otherwise the slug will
be generated based on the name provided. Note that if your name has spaces in
it, you must provide the name in quotes, e.g. statedecoded
edition create --name="My New Edition".
You may delete an edition by its slug with the statedecoded edition
delete --slug=slug command.