Skip to content

Latest commit

 

History

History
176 lines (141 loc) · 7.8 KB

cli.md

File metadata and controls

176 lines (141 loc) · 7.8 KB
title layout
Command Line Tool
default
<style> code { background-color: #ddd; white-space: nowrap; display: inline-block; margin: 0 3px; padding: 1px 4px; border-radius: 5px; } </style>

Overview

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.

Import

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.

Clear Metadata

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

Environment Test

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.

Migrations

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.

Migrate the Database

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.

Writing Migrations

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.

Editions

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.

List Editions

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.

Create Editions

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".

Delete Editions

You may delete an edition by its slug with the statedecoded edition delete --slug=slug command.