refs #5820 improved generators and added a command to generate an update file. Added possibility to copy methods from one class into another including use statements and documentation, added possibility to directly make a translation and modify or create a language file during generation

1 files changed, 119 insertions, 19 deletions

diff --git a/core/Development.php b/core/Development.php
index c0d34f11e9..60d3dcd81c 100644
--- a/core/Development.php
+++ b/core/Development.php
@@ -12,17 +12,21 @@ namespace Piwik;
 use \Exception;
 
 /**
- * Development related checks and tools
+ * Development related checks and tools. You can enable/disable development using `./console development:enable` and
+ * `./console development:disable`. The intention of the development mode and this class is to support the developer
+ * as much as possible by doing some additional checks if the development mode is enabled. For instance if a developer
+ * has to register any class/method we can make sure whether they actually exist and if not display a useful error
+ * message. This helps the user to find for instance simple typos and makes sure it will actually work even if he
+ * forgets to test it.
  */
 class Development
 {
     private static $isEnabled = null;
 
     /**
-     * Returns `true` if segmentation is allowed for this user, `false` if otherwise.
+     * Returns `true` if development mode is enabled and `false` otherwise.
      *
      * @return bool
-     * @api
      */
     public static function isEnabled()
     {
@@ -33,50 +37,110 @@ class Development
         return self::$isEnabled;
     }
 
-    public static function methodExists($classOrInstance, $method)
+    /**
+     * Verifies whether a className of object implements the given method. It does not check whether the given method
+     * is actually callable (public).
+     *
+     * @param string|object $classOrObject
+     * @param string $method
+     *
+     * @return bool true if the method exists, false otherwise.
+     */
+    public static function methodExists($classOrObject, $method)
     {
-        if (is_string($classOrInstance)) {
-            return class_exists($classOrInstance) && method_exists($classOrInstance, $method);
+        if (is_string($classOrObject)) {
+            return class_exists($classOrObject) && method_exists($classOrObject, $method);
         }
 
-        return method_exists($classOrInstance, $method);
+        return method_exists($classOrObject, $method);
     }
 
-    public static function formatMethodCall($classOrInstance, $method)
+    /**
+     * Formats a method call depending on the given class/object and method name. It does not perform any checks whether
+     * does actually exists.
+     *
+     * @param string|object $classOrObject
+     * @param string $method
+     *
+     * @return string Formatted method call. Example: "MyNamespace\MyClassname::methodName()"
+     */
+    public static function formatMethodCall($classOrObject, $method)
     {
-        if (is_object($classOrInstance)) {
-            $classOrInstance = get_class($classOrInstance);
+        if (is_object($classOrObject)) {
+            $classOrObject = get_class($classOrObject);
         }
 
-        return $classOrInstance . '::' . $method . '()';
+        return $classOrObject . '::' . $method . '()';
     }
 
-    public static function checkMethodIsCallable($classOrInstance, $method, $prefixMessageIfError)
+    /**
+     * Checks whether the given method is actually callable on the given class/object if the development mode is
+     * enabled. En error will be triggered if the method does not exist or is not callable (public) containing a useful
+     * error message for the developer.
+     *
+     * @param string|object $classOrObject
+     * @param string $method
+     * @param string $prefixMessageIfError You can prepend any string to the error message in case the method is not
+     *                                     callable.
+     */
+    public static function checkMethodIsCallable($classOrObject, $method, $prefixMessageIfError)
     {
         if (!self::isEnabled()) {
             return;
         }
 
-        if (!self::methodExists($classOrInstance, $method)) {
-            self::error($prefixMessageIfError . ' "' . self::formatMethodCall($classOrInstance, $method) .  '" does not exist. Please make sure to define such a method.');
+        self::checkMethodExists($classOrObject, $method, $prefixMessageIfError);
+
+        if (!self::isCallableMethod($classOrObject, $method)) {
+            self::error($prefixMessageIfError . ' "' . self::formatMethodCall($classOrObject, $method) .  '" is not callable. Please make sure to method is public');
         }
+    }
 
-        if (!self::isCallableMethod($classOrInstance, $method)) {
-            self::error($prefixMessageIfError . ' "' . self::formatMethodCall($classOrInstance, $method) .  '" is not callable. Please make sure to method is public');
+    /**
+     * Checks whether the given method is actually callable on the given class/object if the development mode is
+     * enabled. En error will be triggered if the method does not exist or is not callable (public) containing a useful
+     * error message for the developer.
+     *
+     * @param string|object $classOrObject
+     * @param string $method
+     * @param string $prefixMessageIfError You can prepend any string to the error message in case the method is not
+     *                                     callable.
+     */
+    public static function checkMethodExists($classOrObject, $method, $prefixMessageIfError)
+    {
+        if (!self::isEnabled()) {
+            return;
+        }
 
+        if (!self::methodExists($classOrObject, $method)) {
+            self::error($prefixMessageIfError . ' "' . self::formatMethodCall($classOrObject, $method) .  '" does not exist. Please make sure to define such a method.');
         }
     }
 
-    public static function isCallableMethod($classOrInstance, $method)
+    /**
+     * Verify whether the given method actually exists and is callable (public).
+     *
+     * @param string|object $classOrObject
+     * @param string $method
+     * @return bool
+     */
+    public static function isCallableMethod($classOrObject, $method)
     {
-        if (!self::methodExists($classOrInstance, $method)) {
+        if (!self::methodExists($classOrObject, $method)) {
             return false;
         }
 
-        $reflection = new \ReflectionMethod($classOrInstance, $method);
+        $reflection = new \ReflectionMethod($classOrObject, $method);
         return $reflection->isPublic();
     }
 
+    /**
+     * Triggers an error if the development mode is enabled. Depending on the current environment / mode it will either
+     * log the given message or throw an exception to make sure it will be displayed in the Piwik UI.
+     *
+     * @param  string $message
+     * @throws Exception
+     */
     public static function error($message)
     {
         if (!self::isEnabled()) {
@@ -91,6 +155,42 @@ class Development
         } else {
             throw new Exception($message);
         }
+    }
+
+    public static function getMethodSourceCode($className, $methodName)
+    {
+        $method = new \ReflectionMethod($className, $methodName);
+
+        $file   = new \SplFileObject($method->getFileName());
+        $offset = $method->getStartLine() - 1;
+        $count  = $method->getEndLine() - $method->getStartLine() + 1;
+
+        $fileIterator = new \LimitIterator($file, $offset, $count);
+
+        $methodCode = "\n    " . $method->getDocComment() . "\n";
+        foreach($fileIterator as $line) {
+            $methodCode .= $line;
+        }
+        $methodCode .= "\n";
+
+        return $methodCode;
+    }
+
+    public static function getUseStatements($className)
+    {
+        $class = new \ReflectionClass($className);
+
+        $file  = new \SplFileObject($class->getFileName());
+
+        $fileIterator = new \LimitIterator($file, 0, $class->getStartLine());
+
+        $uses = array();
+        foreach($fileIterator as $line) {
+            if (preg_match('/(\s*)use (.+)/', $line, $match)) {
+                $uses[] = trim($match[2]);
+            }
+        }
 
+        return $uses;
     }
 }