Merge pull request #1 from WBerredo/development

First stable version merge

README.md

@@ -3,11 +3,107 @@ Use wordpress nonce functions in a object oriented environment.
 
 ## Installation
 
-TODO: Describe the installation process
+Add this package as requirement at your composer.json file and
+then run 'composer update'
+```json
+"wberredo/nonce": "1.0.*"
+```
+
+Or directly run
+```bash
+composer require wberredo/nonce
+```
+
+## Setup
+
+If you want to change some configs before you start to generate
+nonces, you will use *NonceConfig* class.
+```php
+// set lifetime for 4 hours
+NonceConfig::setNonceLifetime(4 * HOUR_IN_SECONDS);
+
+// set message showed when showAys is called
+NonceConfig::setErrorMessage("Are you sure");
+```
 
 ## Usage
+To create a nonce you have to use the *NonceGenerator* class and
+to verify a nonce already created you will need the *NonceVerifier*
+class.
+
+### NonceGenerator
+To generate a nonce
+```php
+$nonceGen = new NonceGenerator("default-action");
+$nonce = $nonceGen->generateNonce();
+```
+
+To generate a URL nonce
+```php
+// you can also set parameters with set functions
+$nonceGen = new NonceGenerator();
+$completeUrl = $nonceGen
+                    ->setUrl("https://github.com/WBerredo")
+                    ->setAction("default_action")
+                    ->generateNonceUrl();
+```
+
+To retrieve a nonce field.
+```php
+$nonceGen = new NonceGenerator();
+$nonceField = $nonceGen
+                    ->setAction("default_action")
+                    ->generateNonceField("nonce", true, false);
+
+// to print the nonce field you have to set the last param as true
+$nonceGen
+    ->generateNonceField("nonce", true, true);
+```
+
+To  Display 'Are you sure you want to do this?' message
+(or the new message set with NonceConfig#setErrorMessage)
+to confirm the action being taken.
+```php
+NonceGenerator::showAys('action');
+```
+### NonceVerifier
+To verify a nonce
+```php
+if(NonceVerifier::verify($nonce, $defaultAction)) {
+// if is valid
+} else {
+// if is not valid
+}
+```
 
-TODO: Write usage instructions
+To verify a URL nonce
+```php
+if(NonceVerifier::verifyUrl($completeUrl, $defaultAction)) { 
+// if is valid
+} else {
+// if is not valid
+}
+```
+
+To tests either if the current request carries a valid nonce,
+or if the current request was referred from an administration screen
+```php
+if(NonceVerifier::verifyAdminReferer($defaultAction)) {
+// if is valid
+} else {
+// if is not valid
+}
+```
+
+To verify the AJAX request, to prevent any processing of
+requests which are passed in by third-party sites or systems.
+```php
+if(NonceVerifier::verifyAjaxReferer($defaultAction)) {
+// if is valid
+} else {
+// if is not valid
+}
+```
 
 ## Contributing
 
@@ -19,7 +115,49 @@ TODO: Write usage instructions
 
 ## Tests
 
-TODO: Write history
+1. **Install PHPUnit.** WordPress uses PHPUnit, the standard for unit 
+testing PHP projects. Installation instructions can be found in
+[the PHPUnit manual](https://phpunit.de/manual/current/en/installation.html) 
+or on the [PHPUnit Github repository](https://github.com/sebastianbergmann/phpunit#readme).
+
+2. **Check out the test repository.** The WordPress tests live in 
+the core development repository, 
+at https://develop.svn.wordpress.org/trunk/:
+  ```bash
+  svn co https://develop.svn.wordpress.org/trunk/ wordpress-develop
+  cd wordpress-develop
+  ```
+
+3. **Create an empty MySQL database.** The test suite will delete all 
+data from all tables for whichever MySQL database it is configured.
+Use a separate database.
+
+4. **Set up a config file.** Copy wp-tests-config-sample.php 
+to wp-tests-config.php, and enter your database credentials.
+Use a separate database.
+
+5. **Change the path of Wordpress project** in the bootstrap.php file of the plugin
+  ```php
+  /**
+  * The path to the WordPress tests checkout.
+  */
+  define('WP_TESTS_DIR', '/home/berredo/Documents/repository/wordpress/wordpress-develop/tests/phpunit/');
+  ```
+
+6. **Go to plugin's folder**
+ 
+  ```bash
+  cd vendor/wberredo/nonce
+  ```
+7. **Run phpunit** to test
+  
+  ```bash
+  phpunit 
+  ```
+
+## Thanks to
+* [Wordpress Nonces Documentation](https://codex.wordpress.org/WordPress_Nonces)
+* [Wordpress Automated Testing Documentation](https://make.wordpress.org/core/handbook/testing/automated-testing/)
 
 ## License
 

bootstrap.php

@@ -9,6 +9,31 @@
  */
 define('WP_TESTS_DIR', '/home/berredo/Documents/repository/wordpress/wordpress-develop/tests/phpunit/');
 
+/**
+ * The WordPress tests functions.
+ *
+ * We are loading this so that we can add our tests filter
+ * to load the plugin, using tests_add_filter().
+ */
+require_once WP_TESTS_DIR . 'includes/functions.php';
+
+/**
+ * Manually load the plugin main file.
+ *
+ * The plugin won't be activated within the test WP environment,
+ * that's why we need to load it manually.
+ *
+ * You will also need to perform any installation necessary after
+ * loading your plugin, since it won't be installed.
+ */
+function _manually_load_plugin() {
+    require 'src/NonceGenerator.php';
+    require 'src/NonceVerifier.php';
+    require 'src/NonceConfig.php';
+}
+tests_add_filter( 'muplugins_loaded', '_manually_load_plugin' );
+
+
 /**
  * The WordPress tests functions.
  *

composer.json

@@ -1,5 +1,5 @@
 {
-    "name": "wberredo/wp-nonce",
+    "name": "wberredo/nonce",
     "homepage": "https://github.com/wberredo/nonce",
     "description": "Use wordpress nonce functions in a object oriented environment.",
     "keywords": ["wp", "nonce", "OOP", "wordpress"],

src/NonceConfig.php

@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * Configurations for Nonces
+ *
+ * User: berredo
+ * Date: 2/25/17
+ * Time: 3:14 AM
+ */
+class NonceConfig
+{
+    /**
+     * @var int $nonceLifetimeInSeconds
+     */
+    private static $nonceLifetimeInSeconds;
+
+    /**
+     * @var string $nonceErrorMessage
+     */
+    private static $nonceErrorMessage;
+
+    public static function setNonceLifetime($seconds) {
+        self::$nonceLifetimeInSeconds = $seconds;
+
+        add_filter( 'nonce_life',  function () { return NonceConfig::$nonceLifetimeInSeconds; });
+    }
+
+    /**
+     * Set message to be used when the method showAys is called
+     *
+     * @param string $message
+     */
+    public static function setErrorMessage($message) {
+        self::$nonceErrorMessage = $message;
+
+        add_filter('gettext', function($translation) { return self::$nonceErrorMessage; });
+    }
+}

src/NonceGenerator.php

@@ -0,0 +1,114 @@
+<?php
+
+/**
+ * Generator for Wordpress Nonces
+ * User: berredo
+ * Date: 2/25/17
+ * Time: 1:14 AM
+ */
+class NonceGenerator
+{
+    /**
+     * @var $action
+     */
+    protected $action;
+
+    /**
+     * @var $url
+     */
+    protected $url;
+
+    public static $defaultParamName;
+
+    /**
+     * Nonce constructor.
+     * @param $action
+     */
+    public function __construct($action = -1)
+    {
+        $this->action = $action;
+    }
+
+    /**
+     * set action to generate nonces
+     *
+     * @param string $action
+     * @return $this
+     */
+    public function setAction($action)
+    {
+        $this->action = $action;
+
+        return $this;
+    }
+
+    /**
+     * set url to generate nonce url
+     *
+     * @param $url
+     * @return $this
+     */
+    public function setUrl($url)
+    {
+        $this->url = $url;
+
+        return $this;
+    }
+
+    /**
+     * Retrieves a nonce url
+     *
+     * @param string (optional) $keyName . Nonce param name. Default is _wpnonce
+     *
+     * @return string
+     */
+    public function generateNonceUrl($keyName = '_wpnonce')
+    {
+        if (!$this->url) return null;
+
+        return wp_nonce_url($this->url, $this->action, $keyName);
+    }
+
+    /**
+     * Retrieves the nonce hidden form field.
+     *
+     * @param string $name
+     * @param bool $referer
+     * @param bool $echo
+     *
+     * @return string
+     */
+    public function generateNonceField($name = '_wpnonce', $referer = true, $echo = false)
+    {
+        return wp_nonce_field($this->action, $name, $referer, $echo);
+    }
+
+    /**
+     * Retrieves a general nonce
+     *
+     * @return string
+     */
+    public function generateNonce()
+    {
+        return wp_create_nonce($this->action);
+    }
+
+    /**
+     * Retrieves or displays the referer hidden form field.
+     *
+     * @param $echo
+     * @return string
+     */
+    public function generateRefererField($echo) {
+        return wp_referer_field( $echo );
+    }
+
+    /**
+     * Display 'Are you sure you want to do this?' message to confirm the action being taken.
+     *
+     * @param $action
+     */
+    public static function showAys($action) {
+        wp_nonce_ays($action);
+    }
+}