WP Awards Composer Plugin

The voting plugin encompasses the management of awards and the final selection of winners based on public submissions.

# Award States

There are 3 states for an award:

State	Description
Unpublished	(a.k.a draft) The award is not published but can still be modified.
Live	Only 1 award in award can be live at any one time
Archived	Past awards can be archived. There are no limits to the number of archived awards

# Lifecycle of An Award

An award goes through several phases. When wp-json/voting/v1/awards is called, the following API structure is returned:

[{
	"id": 1,
	"title": "ABC Awards",
	"year": "2017",
	"phase": "winnersAnnounced",
}]

The phase parameter has several options based on the configured dates:

Phase	Description
beforeNomination	Before nominations have begun
currentlyNominating	Nomination period is active, and nominations can be received.
nominationClosed	Nominations have closed based
currentlyVoting	The voting period is active where finalists can be voted against.
votingClosed	The voting period has closed.
winnersAnnounced	Winners announcement period

# API

All routes are prefaced by: /wp-json/voting/v1/. As an example the awards route would be /wp-json/voting/v1/awards.

Route	Description
/awards	Gets a collection of awards. Each award object contains a winners, finalists and categories collection
/award/:id	Gets a single award by id
/award/:id/categories	Gets all categories for an award
/award/:id/finalists	Gets all finalists for an award
/award/:id/winners	Gets all winners for an award
/categories	Gets all categories
/category/:id	Gets a category by category id

# Workflow Setup

composer install

yarn install

yarn run production

To note, all require-dev packages will not be installed in the parent project. However, require packages will be installed by parent project, so double check package version requirements will not break in parent.

# Database Migrations

These run with the Wordpress plugin activation hook. Deactivate and reactivate plugin to add any migrations.

# Tests

There are two sets of tests. PHP and javascript.

npm run php:test

npm run test

npm run test:watch

# Workflow

Upon a git commit, git hooks will run test scripts. If the code fails, then the tests will need to be fixed before you can commit the code again.

Whilst I do not suggest the following; you can remove this pre-commit check, especially in the event of an emergency. In fact, typicode/husky#169 solves this issue quite nicely.

git commit -m "some message" --no-verify

Automatic Builds On Commit

The project will automatically build on commit.

# Project Structure

|-- root
 |-- assets # This has the source code for the javascript and sass files.
 |
 |-- coverage # Is autogenerated by jest which is the front end utility
 |
 |-- dist # All distribution files are built there
 |
 |-- features # Contains use cases needed to be built
 |
 |-- src # Contains the source PHP files
 |
 |-- tests # Has both PHP and javascript tests
 |
 |-- vendor # Autogenerated by composer
 |
 |-- view # PHP view templates

# Continuing Work

Site agnosticism

This plugin is site agnostic, and so to aid more specific front end requirements, it maybe helpful to build plugins that bridge functionality. For example, if a front end developer wants colors associated with categories and he uses acf, you can build an ACF Field Type plugin.

Also, front end developers will have access to any of the classes including Eloquent models via the plugin namespace.

Domain Driven Design

Portions of the PHP code implements DDD. This allows for more complex behaviours to be modelled in an easy to read, write, and testable way. See src/Domain folder for code.

Functional and OOP On Front End

The use of maybe is to decrease the number of unexpected undefined/null errors and bugs that get thrown. This article shows how it's done: https://oliverjash.me/2017/04/10/why-use-a-maybe-type-in-javascript. However, the library in use is https://github.com/alexanderjarvis/maybe.