Gravity PDF
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 (affiliate link). 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
Prerequisites
Setup for Docker
The Docker setup will create a fully functionality development environment preconfigured for Gravity PDF.
- Clone the repository using
git clone https://github.com/GravityPDF/gravity-pdf/
from the terminal - Copy and rename
.env.example
to.env
, then replace00000000000000000000000000000000
with a valid Gravity Forms license key - Run
yarn prebuild
andyarn build:production
- Start Docker Desktop (or run
docker-machine start && eval $(docker-machine env)
if using Docker Toolbox) - Run
yarn env:install
, then wait for the Docker environment to start-up - If successful, you will now have a fully-functional development environment setup with Gravity Forms and Gravity PDF. The URL and login details will be shown in the terminal.
If you shutdown Docker and want to fire up the environment later, use yarn env start
. You can also reset the database back to its original state with yarn env:reset
.
Enable X-Debug
For Windows users:
To enable X-Debug in the containers. You need to set the environmental variables before starting up Docker:
export LOCAL_PHP_XDEBUG=true
- If running Docker Toolbox you'll need to manually set the host IP address:
export XDEBUG_HOST_IP=10.0.0.1
NOTE: Change the IP10.0.0.1
to the value of$_SERVER['REMOTE_ADDR']
when you load up the Docker-powered site.
If you’ve brought up the containers already, run yarn env stop
and yarn env start
to reboot after setting the variable.
For Linux users:
Run the command ip a
and find the docker0
network interface. Copy the inet value. e.g. inet 172.17.0.1/16
, and then include these variables when you start your docker machine.
- e.g
LOCAL_PHP_XDEBUG=true XDEBUG_HOST_IP=172.17.0.1 yarn env start
.
When you do your Path Mappings in your IDE, make sure to name your server localhost
to do CLI debugging (including PHPUnit via yarn test:php
).
- NOTE: Set the server path mapping to the following:
/path/to/gravity-pdf/folder/* => /var/www/src/wp-content/plugins/gravity-forms-pdf-extended
/path/to/gravity-pdf/folder/wordpress/ => var/www
Switch PHP Versions
By default, the latest stable version of PHP will be used when you start the Docker environment. To switch, set the environmental variable LOCAL_PHP
to one of the following:
7.3-fpm
7.4-fpm
For example, to swap to PHP 7.4 run export LOCAL_PHP=7.4-fpm
and then stop and start your container with yarn env stop
and yarn env start
.
Setup without Docker
If you would rather use your own development environment, you can build Gravity PDF using the following commands.
- Clone the repository using
git clone https://github.com/GravityPDF/gravity-pdf/
- Run
yarn prebuild
andyarn build:production
- Run
composer install
- Run
bash ./bin/vendor-prefix.sh
Linting
To lint your JS code, use yarn lint:js
.
To lint your PHP code with Docker use:
yarn env docker-run php composer compat
yarn env docker-run php composer lint
yarn env docker-run php composer lint:errors
To automatically fix PHP lint errors, use yarn env docker-run php composer format
If you aren't using docker, omit yarn env docker-run php
from the beginning of each command.
Automated Tests
The automated test suite can only be run using Docker.
E2E
Useful commands include:
yarn test:e2e
yarn test:e2e:headless
PHPUnit
To successfully run all PHPUnit tests you will need an Elite Gravity Forms license so the Survey, Poll, and Quiz plugins can be automatically installed and downloaded. To install these plugins, run yarn env:install:phpunit
.
You can then run full suite of tests using yarn test:php
or yarn test:php:multisite
JavaScript
The JavaScript unit tests can be run with yarn test:js
Building JS
If you are making changes to any of the JavaScript or CSS, run yarn build:watch:js
or yarn build:watch:css
respectively to ensure the files automatically gets built when you make changes on the file system.
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:
- Adhere to the existing code standard which follows WordPress standards, with the exception of Yoda conditionals.
- All PRs must be to the
development
branch. - Modifications of the existing codebase must pass unit tests.
- Additions to the plugin must have appropriate E2E/unit tests written.
- PRs that don't pass existing unit testing or do not have the proper tests to accompany the changes will not be merged.
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.