Cleanup

README.md

@@ -1,10 +1,71 @@
 # RegDom - Registered Domain Check in PHP
 
-This is an adaptation of the regdom-lib (lineage detailed below) to an OO approach, complete with unit testing.
+Object oriented adaptation of Florian Sager's regdom library for querying
+Mozilla's Public Suffix List,  complete with unit testing.
 
-Proper documentation will be added when complete.
+For more information of public suffixes, and why you may want to query
+the list, please see [publicsuffix.org](https://publicsuffix.org/)
 
----
+# Installation
+
+> composer require geekwright/regdom
+
+# Usage
+
+## Class Geekwright\RegDom\PublicSuffixList
+This class handles all direct interaction with the public suffix list (PSL.)
+This includes, fetching the list from a source URL, caching that list
+locally, converting that list to a tree form to facilitate rapid lookup,
+and caching that tree in a serialized form.
+
+### $psl = new PublicSuffixList(*$url*)
+Creates a new PublicSuffixList object that will use the specified URL as
+the source of the PSL. If no *$url* is specified, it will default to
+https://publicsuffix.org/list/public_suffix_list.dat
+
+### $psl->setURL(*$url*)
+Resets the current PSL, and uses the specified URL as the source.
+
+### $psl->getTree()
+Returns the tree of the current PSL. `Geekwright\RegDom\RegisteredDomain`
+uses this tree form for all lookups.
+
+### $psl->clearDataDirectory(*$cacheOnly*)
+By default, this will clear all cached PSL data, including local copies
+of remotely accessed PSL data. Pass *true* for `$cacheOnly` to clear only
+the serialized tree data.
+
+## Class Geekwright\RegDom\RegisteredDomain
+This class can be used to determine the registrable domain portion of a
+URL, respecting the public suffix list conventions.
+
+### $regdom = new RegisteredDomain(PublicSuffixList *$psl*)
+Creates a new RegisteredDomain object that will use *$psl* to access the
+PSL. If no *$psl* is specified, a new PublicSuffixList object will be
+instantiated using default behaviors.
+
+### $regdom->getRegisteredDomain(*$host*)
+Returns the shortest registrable domain portion of the supplied *$host*,
+or *null* if the host could not be validly registered.
+
+Examples:
+`echo $regdom->getRegisteredDomain('https://www.google.com/');`
+Outputs:
+> google.com
+
+`echo $regdom->getRegisteredDomain('theregister.co.uk');`
+Outputs:
+> theregister.co.uk
+
+`echo null === $regdom->getRegisteredDomain('co.uk');`
+Outputs:
+> 1
+
+## script bin\reloadpsl
+This script can be used to load a fresh copy of the PSL. It may be useful
+in cron job, or other scripted updates.
+
+# License
 
     # Licensed to the Apache Software Foundation (ASF) under one or more
     # contributor license agreements.  See the NOTICE file distributed with
@@ -21,11 +82,10 @@ Proper documentation will be added when complete.
     # See the License for the specific language governing permissions and
     # limitations under the License.
 
+# Credits
 
 Reg-dom was written by Florian Sager, 2009-02-05, [email protected]
 
 Original code was published at http://www.dkim-reputation.org/regdom-lib-downloads/
 
 Marcus Bointon's adapted code is here http://github.com/Synchro
-
----

bin/reloadpsl

@@ -4,7 +4,7 @@
 /*
  * This file is part of https://github.com/geekwright/RegDom
  *
- * Clear all Public Sufix Data and load a fresh copy from publicsuffix.org
+ * Clear all Public Suffix Data and load a fresh copy from publicsuffix.org
  */
 
 function includeIfExists($file)
@@ -14,7 +14,9 @@ function includeIfExists($file)
     }
 }
 
-if ((!$loader = includeIfExists(__DIR__.'/../vendor/autoload.php')) && (!$loader = includeIfExists(__DIR__.'/../../autoload.php'))) {
+if ((!$loader = includeIfExists(__DIR__.'/../vendor/autoload.php'))
+    && (!$loader = includeIfExists(__DIR__.'/../../../autoload.php')))
+{
     die("You must set up the project dependencies, run composer install\n");
 }
 

src/PublicSuffixList.php

@@ -61,7 +61,9 @@ protected function setFallbackURL()
     /**
      * load the PSL tree, automatically handling caches
      *
-     * return void (results in $this->tree)
+     * @return void (results in $this->tree)
+     *
+     * @throws \RuntimeException
      */
     protected function loadTree()
     {
@@ -89,7 +91,7 @@ protected function loadTree()
      *
      * @param string $fileData the PSL data
      *
-     * return void (results in $this->tree)
+     * @return void (results in $this->tree)
      */
     protected function parsePSL($fileData)
     {
@@ -121,8 +123,12 @@ protected function startsWith($search, $startString)
     }
 
     /**
-     * @param array $node tree array by reference
-     * @param $tldParts
+     * Add domains to tree
+     *
+     * @param array    $node     tree array by reference
+     * @param string[] $tldParts array of domain parts
+     *
+     * @return void - changes made to $node by reference
      */
     protected function buildSubDomain(&$node, $tldParts)
     {
@@ -254,6 +260,7 @@ protected function saveLocalPSL($fileContents)
      * Set localPSL name based on URL
      *
      * @param null|string $url the URL for the PSL
+     *
      * @return void (sets $this->localPSL)
      */
     protected function setLocalPSLName($url)

src/RegisteredDomain.php

@@ -35,6 +35,7 @@ public function __construct(PublicSuffixList $psl = null)
      * and converting to lower case
      *
      * @param string $url URL or host name
+     *
      * @return string
      */
     protected function normalizeHost($url)
@@ -52,7 +53,7 @@ protected function normalizeHost($url)
     /**
      * Determine the registered domain portion of the supplied host string
      *
-     * @param string $host
+     * @param string $host a host name or URL containing a host name
      *
      * @return string|null shortest registrable domain portion of the supplied host or null if invalid
      */