Merge pull request #10 from robcaw/develop

1.0 Release

Author: rcwsr

.gitignore

@@ -0,0 +1,51 @@
+### Composer ###
+composer.phar
+composer.lock
+vendor/
+bin/
+
+### PhpStorm ###
+# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm
+
+/*.iml
+
+## Directory-based project format:
+.idea/
+# if you remove the above rule, at least ignore the follwing:
+
+# User-specific stuff:
+# .idea/workspace.xml
+# .idea/tasks.xml
+# .idea/dictionaries
+
+# Sensitive or high-churn files:
+# .idea/dataSources.ids
+# .idea/dataSources.xml
+# .idea/sqlDataSources.xml
+# .idea/dynamic.xml
+# .idea/uiDesigner.xml
+
+# Gradle:
+# .idea/gradle.xml
+# .idea/libraries
+
+# Mongo Explorer plugin:
+# .idea/mongoSettings.xml
+
+## File-based project format:
+*.ipr
+*.iws
+
+## Plugin-specific files:
+
+# IntelliJ
+out/
+
+# mpeltonen/sbt-idea plugin
+.idea_modules/
+
+# JIRA plugin
+atlassian-ide-plugin.xml
+
+# Crashlytics plugin (for Android Studio and IntelliJ)
+com_crashlytics_export_strings.xml

README.md

@@ -7,95 +7,114 @@ generates a new string.
 
 ## Install
 
-Add `"vivait/string-generator-bundle": "dev-master"` to your composer.json and run `composer update`
+Add `"vivait/string-generator-bundle": "~1.0"` to your composer.json and run `composer update`
 
 Update your `AppKernel`:
-
-    public function registerBundles()
-    {
-        $bundles = array(
-            ...
-            new Vivait\StringGeneratorBundle\VivaitStringGeneratorBundle(),
-    }
+```php
+public function registerBundles()
+{
+    $bundles = array(
+        ...
+        new Vivait\StringGeneratorBundle\VivaitStringGeneratorBundle(),
+}
+```  
+## Configure
+
+The default configuration is shown below:
+  
+```yaml
+vivait_string_generator:
+  generators:
+    string: vivait_generator.generator.string
+    secure_bytes: vivait_generator.generator.secure_bytes
+```
+### Bundled generators
+* `StringGenerator` generates a random string based on a pool or characters
+* `SecureBytesGenerator` generates a secure random string using the `Symfony\Component\Security\Core\Util\SecureRandom` class
+
+### Custom generators
+You can use your own generators by implementing `GeneratorInterface` and defining the generator in the configuration, 
+using either its service or classname.
 
 ## Basic usage
 
-Add the `@Vivait\StringGenerator()` annotation to an entity property
+Add the `@Generate(generator="generator_name")` annotation to an entity property 
+(where `generator_name` is the name of a generator defined in the configuration).
 
-    use Vivait\StringGeneratorBundle\Annotation as Vivait;
-    
+```php
+use Vivait\StringGeneratorBundle\Annotation\GeneratorAnnotation as Generate;
+
+/**
+ * Api
+ *
+ * @ORM\Table()
+ * @ORM\Entity()
+ */
+class Api
+{
     /**
-     * Api
+     * @var integer
      *
-     * @ORM\Table()
-     * @ORM\Entity()
+     * @ORM\Column(name="id", type="guid")
+     * @ORM\Id
+     * @ORM\GeneratedValue(strategy="UUID")
      */
-    class Api
-    {
-        /**
-         * @var integer
-         *
-         * @ORM\Column(name="id", type="guid")
-         * @ORM\Id
-         * @ORM\GeneratedValue(strategy="UUID")
-         */
-        private $id;
-    
-        /**
-         * @var string
-         *
-         * @ORM\Column(name="api_id", type="string", nullable=false)
-         * @Vivait\StringGenerator()
-         */
-        private $api_key;
+    private $id;
 
+    /**
+     * @var string
+     *
+     * @ORM\Column(name="api_id", type="string", nullable=false)
+     * @Generate(generator="string")
+     */
+    private $api_key;
+```
 ## Options
 
 ### Length
 
-To change the length of the generated string, add `length` to the annotation. The default is 8. Length specifies the length
-of the resulting generated string, and does not include the prefix or separator
+To change the length of the generated string, add `length` to the annotation.
+```php
+@Generate(length=4)
+```  
 
-    @Vivait\StringGenerator(length=4)
+### Callbacks
 
-### Prefix the key
+It's possible to define callbacks on the `Generator` class that you are using. 
+For example, with the bundled StringGenerator, you may wish to set the character pool. 
 
-To prefix the string, add the `prefix` option to the annotation. The default seperator between the prefix and generated
-string is a `-`, but this can be changed using `separator`:
+This can be achieved by setting the `callbacks` option. For example:
 
-    @Vivait\StringGenerator(prefix="user", separator="_")
+```php
+@Generate(generator="string", callbacks={"setChars"="ABCDEFG"})
+```
 
-A prefix can be obtained via a callback to a method in the entity using `prefix_callback`, which overrides `prefix`.
+Here, `setChars()` is called in the `StringGenerator` class, passing `ABCDEFG` as a parameter.
 
-    /**
-     * @var string
-     *
-     * @ORM\Column(name="friendly_id", type="string", nullable=false)
-     * @Vivait\StringGenerator(prefix_callback="createPrefix", length=8)
-     */
-    private $friendly_id;
-    
-    public function createPrefix()
-    {
-        return $this->category->getCode();
-    }
-    
-### Alphabet
+It's even possible to set a callback value dynamically:
 
-Setting `alphabet` limits the characters the generator can choose from. Defaults to alphanumeric.
+```php
+/**
+ * @var string
+ *
+ * @ORM\Column(name="short_id", type="string", length=255, nullable=false)
+ * @Generate(generator="string", length=5, callbacks={"setPrefix"="getPrefix"})
+ */
+private $short_id;
 
-    @Vivait\StringGenerator(alphabet="abcdefghkmnpqrstuwxyz")
-    
-### Unique
+public function getPrefix()
+{
+    return $this->getType(); //"default"
+}
+```
 
-Setting `unique` is boolean and tell if the string must be unique or not, by default `true`
+In this case `StringGenerator::setPrefix("default")` will be called
 
-    @Vivait\StringGenerator(unique="false")
 
-## Custom generator
+### Unique
 
-If you want to use a different generator to create your string, create a class that implements namespace 
-`Vivait\StringGeneratorBundle\Model\GeneratorInterface`. Add the fully qualified classname to your config.yml:
+Setting `unique` is boolean and tell if the string must be unique or not, by default `true`
 
-    vivait_string_generator:
-      generator_class: Acme\BlogBundle\Generator\UsernameGenerator
+```php
+@Generate(generator="secure_bytes", unique=false)
+```

composer.json

@@ -7,9 +7,12 @@
          "email":"robin@vivait.co.uk"
       }
     ],
+    "minimum-stability": "dev",
+    "prefer-stable": true,
     "require": {
         "php": ">=5.3.3",
-        "doctrine/common": "~2.2"
+        "doctrine/common": "~2.2",
+        "symfony/security": "~2.1"
     },
     "require-dev": {
         "phpspec/phpspec": "~2.0"
@@ -19,8 +22,7 @@
     },
     "autoload":{
       "psr-0":{
-         "Vivait\\StringGeneratorBundle":""
+         "Vivait\\StringGeneratorBundle\\": "src/"
       }
-    },
-    "target-dir":"Vivait/StringGeneratorBundle"
+    }
 }

spec/Vivait/StringGeneratorBundle/EventListener/GeneratorListenerSpec.php

@@ -0,0 +1,52 @@
+<?php
+
+namespace spec\Vivait\StringGeneratorBundle\EventListener;
+
+use Doctrine\Common\Annotations\Reader;
+use PhpSpec\ObjectBehavior;
+use Prophecy\Argument;
+use Vivait\StringGeneratorBundle\Annotation\GeneratorAnnotation;
+use Vivait\StringGeneratorBundle\Generator\StringGenerator;
+use Vivait\StringGeneratorBundle\Registry\Registry;
+
+class GeneratorListenerSpec extends ObjectBehavior
+{
+    function it_is_initializable()
+    {
+        $this->shouldHaveType('Vivait\StringGeneratorBundle\EventListener\GeneratorListener');
+    }
+
+    function let(Reader $reader, Registry $registry)
+    {
+        $this->beConstructedWith($reader, $registry);
+    }
+
+    function it_performs_callbacks_on_the_generator(StringGenerator $generator, Entity $mockEntity)
+    {
+        $annotation = new GeneratorAnnotation([]);
+        $annotation->callbacks = ['setChars' => 'abcdef'];
+        $this->shouldNotThrow('\InvalidArgumentException')->duringPerformCallbacks($generator, $annotation, $mockEntity);
+
+        $annotation->callbacks = ['noMethod' => 'something'];
+        $this->shouldThrow('\InvalidArgumentException')->duringPerformCallbacks($generator, $annotation, $mockEntity);
+    }
+
+    function it_can_get_callback_values_from_annotated_object(StringGenerator $generator, Entity $mockEntity)
+    {
+        $annotation = new GeneratorAnnotation([]);
+        $annotation->callbacks = ['setPrefix' => 'getPrefix'];
+
+        $mockEntity->getPrefix()->willReturn('VIVA_');
+        $generator->setPrefix('VIVA_')->shouldBeCalled();
+        $this->performCallbacks($generator, $annotation, $mockEntity);
+    }
+}
+
+class Entity
+{
+    public function getPrefix()
+    {
+
+    }
+}
+

spec/Vivait/StringGeneratorBundle/Generator/SecureBytesGeneratorSpec.php

@@ -0,0 +1,36 @@
+<?php
+
+namespace spec\Vivait\StringGeneratorBundle\Generator;
+
+use PhpSpec\ObjectBehavior;
+use Prophecy\Argument;
+use Symfony\Component\Security\Core\Util\SecureRandom;
+
+class SecureBytesGeneratorSpec extends ObjectBehavior
+{
+    function it_is_initializable()
+    {
+        $this->shouldHaveType('Vivait\StringGeneratorBundle\Generator\SecureBytesGenerator');
+    }
+
+    function let()
+    {
+        $secureRandom = new SecureRandom();
+        $this->beConstructedWith($secureRandom);
+    }
+
+    function it_generates_random_string()
+    {
+        $this->setLength(10);
+        $this->generate()->shouldHaveStrlen(10);
+    }
+
+    function getMatchers()
+    {
+        return [
+            'haveStrlen' => function($string, $length){
+                return strlen($string) == $length;
+            }
+        ];
+    }
+}

spec/Vivait/StringGeneratorBundle/Generator/StringGeneratorSpec.php

@@ -0,0 +1,43 @@
+<?php
+
+namespace spec\Vivait\StringGeneratorBundle\Generator;
+
+use PhpSpec\ObjectBehavior;
+
+class StringGeneratorSpec extends ObjectBehavior
+{
+    function it_is_initializable()
+    {
+        $this->shouldHaveType('Vivait\StringGeneratorBundle\Generator\StringGenerator');
+    }
+
+    function it_generates_a_string_based_on_length()
+    {
+        $this->setLength(10);
+        $this->generate()->shouldBeString();
+        $this->generate()->shouldHaveStrlen(10);
+    }
+
+    function it_should_throw_an_exception_if_it_has_no_chars()
+    {
+        $this->shouldThrow('\OutOfBoundsException')->duringSetChars('');
+        $this->shouldThrow('\OutOfBoundsException')->duringSetChars(null);
+        $this->shouldThrow('\OutOfBoundsException')->duringSetChars(true);
+    }
+
+    function it_should_error_if_its_length_is_set_to_less_than_1()
+    {
+        $this->shouldThrow('\OutOfBoundsException')->duringSetLength(0);
+        $this->shouldThrow('\OutOfBoundsException')->duringSetLength(-1);
+        $this->shouldThrow('\OutOfBoundsException')->duringSetLength("ten");
+    }
+
+    function getMatchers()
+    {
+        return [
+            'haveStrlen' => function($string, $length){
+                return strlen($string) == $length;
+            }
+        ];
+    }
+}