seb86 / coil-wordpress-plugin

Coil's Wordpress Web Monetization Plugin

Coil Web Monetization

This is the source code repository for the official Coil Web Monetization WordPress plugin. Coil's Web Monetization plugin allows you to easily monetize some or all of the content on your site. All you need to do is fill in a payment pointer, then whenever a Coil member visits your monetized content you will receive a stream of micropayments from Coil for every second that they view your content.

As well as monetizing content you can also set some or all of your content to be exclusive to Coil members.

---

• Local Development Environment
• Development Process
• Issues
• Installing The Plugin
• Production Build

---

Local Development Environment

It's recommended that you use Local by Flywheel for your local development environment.

The nature of this project (a plugin) means that it is environment-agnostic, so if you prefer to install and administer WordPress using another method, then please do so.

Setting up the Development Environment using Flywheel

Ensure you have the prerequisite software installed:

• PHP 7.2+
• Composer 2.0+, installed globally.
• Local By Flywheel 6.4.0
• Node 14.0.0
• An account on Coil.com.

Install the development environment:

1. Set up a new site in Flywheel:
   • Name the new site coil.
   • You can keep the preferred settings.
   • This project does not require a specific Web Server or MySQL version; if in doubt, choose nginx and MySQL.
2. After Flywheel has created the site, from inside the root of where you chose to create the site, clone this repository into the plugins folder (make sure to add SSH key to Github plugin repo):
   • git clone [e-mail]:coilhq/coil-wordpress-plugin.git app/public/wp-content/plugins/coil-web-monetization
3. When the machine has finished provisioning, install the development dependencies:
   • cd app/public/wp-content/plugins/coil-web-monetization && composer install && npm install
4. To configure Flywheel for PHPUnit:
   • Download the following script to the base of yourapp/ folder:
     • curl -o setup-phpunit.sh https://gist.githubusercontent.com/keesiemeijer/a888f3d9609478b310c2d952644891ba/raw/
   • In Flywheel, right-click your "Coil" site and select "Open Site Shell". This will open a new terminal, and inside it, do: bash /app/setup-phpunit.sh
   • The script will take several minutes to install PHPUnit. Once it's done, you can close the terminal.

There is no sample database to import.

Flywheel will give you the URL of where you can access your environment, and you'll have supplied the initial user account's username and password during Flywheel set up.

Development Process

Development happens in feature branches, which are merged into develop for deployment to production. When making changes, a feature branch should be created that branches from develop (and the corresponding merge request on Github should use develop as the target branch).

Plugin Structure

This plugin maintains a basic file structure:

• plugin.php – The main plugin file.
• includes/ – The plugin's backend/PHP code.
• assets/ – Directory containing any static assets:
  • css/ – Compiled CSS to be served to the frontend.
  • fonts/ – Web fonts, if any.
  • images/ – Images.
  • js/ – JavaScript files.
  • scss/ – SCSS source files.
• README.md – Plugin developer readme.

Within the includes/ directory, files should be organized hierarchically based on namespaces. If a namespace only contains functions, the filename should be functions.php.

If a namespace also contains classes, group those classes together with the namespace file in a {sub-namespace}/ directory. The main functions file for this namespace would be{sub-namespace}/functions.php, while classes should be in a file prefixed with class- with a "slugified" class name.

This plugin also has some complex JavaScript frontends, so there is additional structure to better match the ecosystem tooling:

• src/ – Source JavaScript and CSS files.
• dist/ – Built assets, typically generated by Webpack and Babel

Assets (CSS & JS)

Some of the tooling for this plugin came from the create-guten-block project, so we have two different ways to manage CSS and JS.

Block Assets (src/)

npm start

• Used to compile and run the block in development mode.
• Watches for any changes and reports back any errors in your code.

npm run build

• Use to build production code for your block inside the dist/ folder.
• Runs once and reports back the gzip file sizes of the produced code.

Other Assets (assets/{js,scss}/)

npx grunt watch

• Used to compile and run the assets in development mode.
• Watches for any changes and reports back any errors in your code.

npx grunt build

• Use to build production code for your assets inside the assets/{css,js} folders.

Functional Tests

New tests should be written where it makes sense. With Flywheel, the PHPUnit tests have to be run inside the Flywheel environment. To do this:

• In Flywheel, right-click your "Coil" site and select "Open Site Shell". This will open a new terminal.
• Inside it, change into the plugin folder: cd /app/public/wp-content/plugins/coil-web-monetization.
• To run all tests, simply do: ./vendor/bin/phpunit.

End-to-end Cypress Tests

Cypress is used for end-to-end testing. To run the tests you will need to:

• Make sure all steps under Setting up the Development Environment Using Flywheel have been completed.
• The tests can be run from the terminal.
  • To open the Cypress GUI and run all the tests: npx cypress open --project ./tests --config baseUrl="http://example.local/" - where example.local is set to the actual URL provided for your site by Local.
  • Alternatively all the tests can be run headlessly in the terminal by running, npx cypress run --project ./tests --config baseUrl="http://example.local/" - where example.local is set to the actual URL provided for your site by Local.

Continuous Integration Tests

We use CircleCI to automatically run the functional PHPUnit tests and the Cypress end-to-end tests every time code is pushed to the repository.

Issues

We'd love to hear feedback so please feel free to post an issue on our GitHub project if you have found a bug or there is a new feature you'd like to see us implement. We will review these issues and be in touch.

Installing The Plugin

• for testing, the Github repo can be zipped up and the zip used to install the Coil plugin on WordPress
  • on Github, go to the front page and click on "Clone or download"
  • choose "Download ZIP"
• for production, use command line grunt zip to create a zip in the /resources/ folder. This removes development files such as composer.json and the tests folder.

Production Build

The zip and the tag are different builds -- the tag is obviously the source version, and the zip has some build files removed. So, to generate the versions you'll want to distribute:

1. composer install && npm install
2. npm run build && npx grunt build
3. If you want to change the version number, update it in package.json and run npx grunt version
4. Commit changes from above steps
5. npx grunt zip -- it will make a zip and put it in the releases/ folder.
6. Take that zip, unzip the file, and commit it to SVN that way and then get it onto WordPress.org Plugins SVN.