Download the PHP package gbhorwood/gander without Composer
On this page you can find all versions of the php package gbhorwood/gander. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Informations about the package gander
Gander
Gander is an inspector and logger for restful Laravel apis. Gander allows logging of request/responses, as well as optional logging of events in your source code. Gander reports are viewed with an exported javascript client which can be hosted anywhere. Gander was developed as an internal-use tool for fruitbat studios/cloverhitch technologies/kludgetastic implementations.
Install
Gander is installed via composer:
Installing Gander will add a middleware to your api middleware group, create tables to store Gander events and access keys, expose the gbhorwood:gander
artisan command, and write the gander config file to your config
directory.
Quickstart
The shortest path to getting Gander working after install is to create a client in your api's root directory with:
Then load the html file in a browser, either by hosting it on any http server or by opening it as a file in your browser.
Configuration
Gander has four configuration values that can be added to your .env
file:
GANDER_ENABLE
: Setting GANDER_ENABLE
to false
will turn off Gander completely. Gander is on by default.
GANDER_ENABLE_STACK_TIMERS
: Setting GANDER_ENABLE_STACK_TIMERS
to false will disable the elapsed time value on all log writes you have added to your code using Gander::track()
. Stack timers are on by default.
GANDER_PASSWORD_KEYS
: Gander attempts to sanitize password data from request bodies before writing to the database by removing a value if its key matches one of the keys listed in GANDER_PASSWORD_KEYS
. If you accept password data keyed with something not in the GANDER_PASSWORD_KEYS
list, add it.
GANDER_HEADERS_TO_LOG
: Gander can log a subset of request headers. Header names to log are listed here as a comma-separated list. If no headers are listed, only X-Authorization
and User-Agent
are stored.
A short note on timer configuration
Timing of the elapsed seconds of a request is done internally using php's hrtime()
for performance reasons. However, hrtime()
is unreliable when called across function calls. For this reason, calculating the elapsed time when writing log calls made by Gander::track()
is done using microtime()
. However, microtime()
may be slow in some virtual environments who's vDSO does not allow access to the clock. For this reason, Gander allows you to turn off the use of microtime()
by setting GANDER_ENABLE_STACK_TIMERS
to false
.
Writing logs
Gander logs requests and responses automatically. In addition, you can also add log writes for a given request in your endpoint's source code with:
This method takes a message as an optional string argument.
The track method can be called anywhere in your executed code, for example:
Here, the call to Gander::track()
in both getNumber()
and generateNumber()
is logged. The client will display them in the order they were written.
If GANDER_ENABLE_STACK_TIMERS
is set to true
, each call to Gander::track()
will log the elapsed time, in seconds, since the last call to track
.
Since logs written using track()
are tied to the current request, extra steps are needed to write logs after the request has completed, ie. when using queued jobs. See 'Writing logs from a queued job' below.
Generating a client
Data logged by Gander can be viewed with a javascript client that runs in your browser. A client can be created by calling the gander artisan command in the root directory of your api.
The client file will be saved in your api's root directory and will be named using the format:
This client will work only for the api in which it was generated and can be hosted anywhere that has network access to your api.
The client file will access your api using a unique access key. If you wish to revoke access to a client, you can do so by removing its api key (see 'Managing client keys').
If you wish to specify the file name and location of the the client at creation, you can do so with the --outfile=
option:
Gander will not overwrite client files that already exist.
If you want to specify the name of your access key, you can use the --key-name=
option:
Using the client
A Gander client can be hosted on any http server or opened in a web browser as a file.
The client will only work for the api where it was generated. Each client uses a unique api key to get reports on the api (see 'Managing client keys').
Gander reports on activity that ocurred during a time frame defined as a certain point in the past, ie. '2 hours ago', until now.
There are two types of reports:
- Stats: Aggregate statistics on all the activity in the time period
- Logs: A list of all the api requests during the time period
The 'stats' tab
The Stats tab will show all of the routes called during the time period, along with the total number of requests for each route and their success rate. Clicking on a stats line will show a breakdown of the number of requests to that route by returned status code.
Note that the number of time units is an editable input box.
The domain of the api being reported on and the name of the api key are shown in the top-right corner.
The 'logs' tab
The logs tab shows all request activity during the time period. The logs are shown from most recent to least recent.
Clicking on one log entry will display details about that request.
Seeing log details
Log details are shown by clicking on a log line. Basic information about the request and response is displayed:
The 'permalink' button and url at the bottom can be used to refer back to the log details at any time.
Managing client keys
The Gander client gets statistics and logs about your api by calling it's own api endoints. These endpoints require api keys to access.
Gander api keys are identified by their name; a unique, somewhat-readable string.
To get a list of the Gander api keys your api has, run
This will display names and creation times of all keys.
To delete a given key
When creating a client, you can assign it a custom key name to make key management easier:
Writing logs from a queued job
Gander logs are tied to requests. However, logs can still be written to a request after the request terminates, ie. in a queued job, by passing the request id to track()
.
The request id can be retrieved using the method:
The call to track()
can accept the request id as an optional argument:
To use this method to write logs in queued jobs, the request id must be retrieved in the controller and passed to the job. For instance:
In the controller, harvest the request id and pass as a constructor argument to the job class.
In the job, accept the request id as an argument and use it when calling Gander::track()
.
Writing your own client
If you wish to create your own client, OpenApi documentation on the Gander api is located in the swagger/
directory of the package.