/gravity-pdf

Gravity PDF is a GPLv2-licensed WordPress plugin that allows you to automatically generate, email and download PDF documents using Gravity Forms.

Primary LanguagePHP

Gravity PDF

Build Status codecov

Gravity PDF is a GPLv2-licensed WordPress plugin that allows you to automatically generate, email and download PDF documents using the popular form-builder plugin, Gravity Forms. Find out more about Gravity PDF at https://gravitypdf.com.

About

This Git repository is for developers who want to contribute to Gravity PDF. Don't use it in production. For production use, download Gravity PDF from the WordPress Plugin Directory.

The development branch is considered our bleeding edge branch, with all new changes pushed to it. The master branch is our latest stable version of Gravity PDF.

Installation

Before beginning, ensure you have Git, Composer and Yarn installed and their commands are globally accessible via the command line.

  1. Clone the repository using git clone https://github.com/GravityPDF/gravity-pdf/
  2. Open your terminal / command prompt to the Gravity PDF root directory and run composer install. This command will automatically download all the PHP and JS packages, and run the build tools.
  3. Copy the plugin to your WordPress plugin directory (if not there already) and active through your WordPress admin area

Setup Local Docker Environment

A test site with Gravity PDF pre-configured can be automatically be built locally if you've Docker installed on available via the CLI. To setup:

  1. Start Docker. Note: if running Local By Flywheel (or you need to start Docker manually), first run docker-machine start, then eval $(docker-machine env).
  2. Copy .env.example to .env and replace 0000000000000000 with a valid Elite license key in .env
  3. Run ./bin/setup-local-env.sh from the command line
  4. Access test site at http://localhost:8888, or the domain shown in the CLI if different. The username is admin and the password is password

Documentation

All documentation can be found at https://gravitypdf.com/documentation/.

Contributions

You are more than welcome to contribute to Gravity PDF but we recommend you open a new issue on GitHub and discuss your use-case before creating a pull request.

There are a few guidelines that need to be followed to ensure a smooth pull request. These include:

  1. Adhere to the existing code standard which follows WordPress standards, with the exception of Yoda conditionals.
  2. All PRs must be to the development branch.
  3. Modifications of the existing codebase must pass all unit tests.
  4. Any additions to the plugin must have appropriate unit tests written.
  5. PRs that don't pass existing unit testing or do not have the proper tests to accompany the changes will not be merged.
  6. Once our team is happy with the PR we'll ask you to squash your branch into a single commit, rebase it onto the development branch and push the changes to GitHub. This ensures we keep a clean Git history.

If you are uncertain whether your PR meets all these requirements, don't worry! If there are problems our friendly team will guide you in the right direction.

Run Unit Tests

PHPUnit (PHP)

We use PHPUnit to test out all the PHP we write. The tests are located in tests/phpunit/unit-tests/

Installing the testing environment is best done using a flavour of Vagrant (try Varying Vagrant Vagrants).

  1. From your terminal SSH into your Vagrant box using the vagrant ssh command
  2. cd into the root of your Gravity PDF directory
  3. Run bash tests/bin/install.sh gravitypdf_test root root localhost where root root is substituted for your mysql username and password (VVV users can run the command as is).
  4. Upon success you can run vendor/bin/phpunit, vendor/bin/phpunit --group ajax and vendor/bin/phpunit --group slow-pdf-processes.

Mocha (JS)

We use the JS libaries, Mocha, Chai and Sinon to test our Javascript and use Karma to run those tests in a variety of browsers. We also use Enzyme to help test ReactJS.

The tests are located in tests/mocha/unit-tests/.

Running the tests can easily be done with one of the following commands:

  • yarn run test – runs all the tests once in PhantomJS
  • yarn run test:watch – watches for changes to the tests and runs in PhantomJS
  • yarn run test:all – runs all tests in Firefox, Chrome and Internet Explorer

Building JS

We use Webpack to compile our Javascript from ES6 to ES5. If you want to modify the Javascript then take advantage of yarn run watch to automatically re-build the JS when changes are made.