A simple, easy to use interface for reporting shared metrics on WMF wikis
GPL-3.0 License
A Wikimedia Foundation tool that provides event organizers and grantees a simple, easy to use interface for reporting their shared metrics, removing the need for any manual counting.
Prerequisites:
After cloning the repository:
.env.local
and fill in the necessary values:
DATABASE_
values are for the Event Metrics database.DATABASE_REPLICA_USER
and DATABASE_REPLICA_PASSWORD
can be found inreplica.my.cnf
file in the home directory of your account on Toolforge.APP_LOGGED_IN_USER
is used to mock the current user, instead of going through OAuth.composer install
.symfony console toolforge:ssh
.symfony server start
to start the server.The web interface is hopefully straightforward to use. However, developers can also do some functionality via the console. In the same directory as the application:
symfony console app:process-event <eventId>
- will generate EventStat
s for the Event<eventId>
.symfony console app:spawn-jobs
- queries the Job queue and runs app:process-event
Event Metrics uses the Symfony framework.
Models are Doctrine ORM entities
that directly correlate to tables in the eventmetrics
database. Database interaction should generally be done with
Doctrine's EntityManager
.
Repositories are responsible for querying the replicas, MediaWiki API, file system, etc., wherever external data lives. They do not do any post-processing. Repositories should automatically be assigned to the models, and can be injected wherever they're required (via type-hinted parameters).
Assets are managed by Webpack Encore.
The entry point is assets/js/application.js, and the output is in public/build/
.
Compiled assets must be committed to the repository.
npm run build
- compiles assets for production.npm run watch
- compiles assets for development and watches for changes.npm run dev
- compiles assets for development without watching.All messages live in the i18n/ directory.
For PHP, Intuition is used. Within the views,
you can access a message using the msg('message-key', ['arg1', 'arg2', ...])
function.
Intuition is not available outside the views, but you probably don't need it in those cases anyway.
When working with model validations, you'll provide the message key and parameters that will in
turn get passed into the view. For basic constraints, just put the key name.
For instance @UniqueEntity("title", message="error-program-title-dup")
for a duplicate program title.
The name of the program is automatically passed in as the first parameter in the message. If you need to
pass a variable, use the payload
options, e.g. @Assert\NotNull(message="error-invalid", payload={"0"="start-date"})
.
For custom callbacks, use the validation builder and set the parameters accordingly. For instance, to validate that a program title is not reserved:
if ( in_array( $this->title, [ 'edit', 'delete' ] ) ) {
$context->buildViolation( 'error-program-title-reserved' )
->setParameter( 0, '<code>edit</code>, <code>delete</code>' )
->atPath( 'title' )
->addViolation();
}
In JavaScript, we use jquery.i18n.
The syntax is $.i18n( 'message-key', 'arg1', 'arg2', … )
.
Use composer test
to run the full test suite. The individual commands that it runs are as follows:
composer migrate-test
– Creates and migrates the test database.composer lint
– tests for linting errors in PHP, Twig and YAML files, and uses MinusX to ensure files have the correct permissions.composer unit
– Runs unit and integration tests with PHPUnit.composer phan
– Runs static analysis with Phan.Most CodeSniffer and MinusX errors can be fixed automatically using composer fix
.
The basic fixture set is loaded by default. The extended set supplies a lot more test data, and is meant for testing beyond the workflow of creating events, etc., such as statistics generation.
Repository classes should not need tests. Add @codeCoverageIgnore
to the bottom of the class summary so that
coverage statistics are not affected.
Controller tests extend DatabaseAwareWebTestCase
, which loads
fixtures and ensures full stack traces are shown when there is an HTTP error. Some class properties must be set for
this to work:
$this->client
- the Symfony client.$this->container
- the DI container.$this->crawler
- the DOM crawler.$this->response
- response of any requests you make.See ProgramControllerTest
for an example.
For maintainer documentation, see https://wikitech.wikimedia.org/wiki/Nova_Resource:Eventmetrics
The application runs on the Wikimedia Cloud Services VPS environment at https://eventmetrics.wmcloud.org
Deployment happens automatically after a new version tag is created.