From d9f86879d673a5fc059f44b3ecde59b141178967 Mon Sep 17 00:00:00 2001 From: jrfnl Date: Sat, 15 Sep 2018 04:18:53 +0200 Subject: [PATCH] :books: Documentation: Add README.md --- README.md | 115 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 115 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 00000000..49857744 --- /dev/null +++ b/README.md @@ -0,0 +1,115 @@ + + + +# WPThemeReview Standard for PHP_CodeSniffer + +* [Introduction](#introduction) +* [Requirements](#requirements) +* [Installation](#installation) + + [Installing WPThemeReview globally](#installing-wpthemereview-globally) + + [Installing WPThemeReview as a project dependency](#installing-wpthemereview-as-a-project-dependency) + + [Checking your installation was successful](#checking-your-installation-was-successful) +* [Using the WPThemeReview standard](#using-the-wpthemereview-standard) +* [Contributing](#contributing) +* [License](#license) + +## Introduction + +WordPress Themes for which a hosting application has been made for the theme to be hosted in the theme repository on [wordpress.org](https://wordpress.org/themes/) have to comply with [a set of requirements](https://make.wordpress.org/themes/handbook/review/required/) before such an application can be approved. +Additionally, there are also [recommendations](https://make.wordpress.org/themes/handbook/review/recommended/) for best practices for themes. + +This project attempts to automate the code analysis part of the [Theme Review Process](https://make.wordpress.org/themes/handbook/review/) as much as possible using static code analysis. + +[PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) is the base tool upon which this project is build and is a PHP command-line tool. + +**_This project is a work in progress and passing the checks is no guarantee that your theme will be approved._** + + +## Requirements + +The WPThemeReview Standard requires: +* PHP 5.4 or higher. +* [PHP_CodeSniffer](https://github.com/squizlabs/PHP_CodeSniffer) version **3.3.0** or higher. +* [WordPress Coding Standards](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards) version **1.0.0** or higher. + + +## Installation + +The only supported installation method is via [Composer](https://getcomposer.org/). + +1. Make sure you have PHP installed on your system. +2. If not installed yet, install [Composer](https://getcomposer.org/download/). + +### Installing WPThemeReview globally + +If you would like to have the WPThemeReview standard available to all projects on your system, you can install it in a central location. + +From the command-line, run the following command: +```bash +$ php composer.phar global require wptrt/wpthemereview dealerdirect/phpcodesniffer-composer-installer +``` + +### Installing WPThemeReview as a project dependency + +If you use Composer to manage dependencies from your project anyway or are considering using it, you can also choose to install the WPThemeReview standard for an individual project. + +From the command-line, run the following command from the root directory of your project: + +```bash +$ php composer.phar require --dev wptrt/wpthemereview:* dealerdirect/phpcodesniffer-composer-installer:^0.4.4 +``` + +> Note: +> * The `--dev` means that WPThemeReview will be installed as a development requirement, not as a requirement for using the Theme. +> * The second package - `dealerdirect/phpcodesniffer-composer-installer` -, is a Composer plugin which will automatically sort out that PHP_CodeSniffer recognizes the WPThemeReview standard and the various WordPress standards. + +### Checking your installation was successful + +```bash +# For a global install: +$ phpcs -i + +# For a project install: +$ vendor/bin/phpcs -i +``` + +If everything went well, the output should look something like this: +``` +The installed coding standards are MySource, PEAR, PSR1, PSR12, PSR2, Squiz, Zend, WordPress, WordPress-Core, WordPress-Docs, WordPress-Extra, WordPress-VIP and WPThemeReview +``` + + +## Using the WPThemeReview standard + +You can now test your theme code against the WPThemeReview standard by running the following command from the root directory of your theme: +```bash +# For a global install: +$ phpcs -p . --standard=WPThemeReview + +# For a project install: +$ vendor/bin/phpcs -p . --standard=WPThemeReview +``` + +If any issues are found, PHP_CodeSniffer will display a report with all the errors (must fix) and warnings (recommended to fix) for each file. + +More information about running PHP_CodeSniffer can be found in the [PHP_CodeSniffer Wiki](https://github.com/squizlabs/PHP_CodeSniffer/wiki). + + +## Contributing + +See [CONTRIBUTING](.github/CONTRIBUTING.md), including information about [unit testing](.github/CONTRIBUTING.md#unit-testing) the standard. + +## License + +See [LICENSE](LICENSE) (MIT).