Developed with love by KnpLabs Hire us for your project!
29

StringGeneratorBundle

by vivait

Generate random strings for IDs or keys using property annotations

StringGeneratorBundle

Build Status

This bundle allows you to automatically generate a unique random string on an entity property, useful for
creating keys. Using Doctrine's prePersist callback, StringGenerator adds the generated string to a property
before the entity is persisted. It also checks whether the string is unique to that property (just in case) and if not, quietly
generates a new string.

Install

Run: composer require vivait/string-generator-bundle:^2.0 to install the bundle.

If you are using PHP 5.3 or 5.4 you can use the legacy versionvivait/string-generator-bundle:^1.1

Check latest releases

Update your AppKernel:
php
public function registerBundles()
{
$bundles = array(
...
new Vivait\StringGeneratorBundle\VivaitStringGeneratorBundle(),
}

Bundled generators

StringGenerator

Generates a random string based on a pool or characters. Defaults:

@Generate(generator="string", options={"length"=8, "chars"="0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ", "prefix"=""})

SecureStringGenerator

Generates a secure random string using ircmaxell's RandomLib. The library provides three different strengths of
strings(currently high is unavailable), low and medium. Defaults:

@Generate(generator="secure_string", options={"length"=32, "chars"="0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ", "strength"="medium"})

SecureBytesGenerator

Generates a secure random byte string using the Symfony\Component\Security\Core\Util\SecureRandom class. Defaults:

@Generate(generator="secure_bytes", options={"length"=8})

UuidStringGenerator

For use this generator you should require the package ramsey/uuid in your application.

For generating a UUID:

@Generate(generator="uuid_string", options={"version"=4})

You can use also namespaced versions (v3 and v5). For example with the v5:
php
@Generate(generator="uuid_string", options={"version"=5}, namespace="my_namespace")

Usage

Add the @Generate(generator="generator_name") annotation to an entity property
(where generator_name is the name of a generator defined in the configuration).

generator is a required property of the annotation.

use Vivait\StringGeneratorBundle\Annotation\GeneratorAnnotation as Generate;

/**
 * Api
 *
 * @ORM\Table()
 * @ORM\Entity()
 */
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)
     * @Generate(generator="string")
     */
    private $api_key;

Options

Generators that implement ConfigurableGeneratorInterface, such as the bundled generators have options which can be configured.

To do this, set the options parameter on the annotation:

@Generate(generator="string", options={"length"=32, "chars"="ABCDEFG"})

Callbacks

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 a prefix on the generated string

This can be achieved by setting the callbacks option. For example:

@Generate(generator="my_generator", callbacks={"setPrefix"="VIVA_"})

Here, setChars() is called in the StringGenerator class, passing ABCDEFG as a parameter.

It's even possible to set a callback value dynamically:

/**
 * @var string
 *
 * @ORM\Column(name="short_id", type="string", length=255, nullable=false)
 * @Generate(generator="string", options={"length"=32}, callbacks={"setPrefix"="getPrefix"})
 */
private $short_id;

public function getPrefix()
{
    return $this->getType(); //"default"
}

In this case StringGenerator::setPrefix("default") will be called

Unique

Setting unique is boolean and tell if the string must be unique or not, by default true

@Generate(generator="secure_bytes", unique=false)

Override

By default, override is set to true, so a string is always generated for a property.
However, by setting override to false, only null properties will have a string generated for them.

@Generate(generator="string", override=false)

Custom generators

You can use your own generators by implementing GeneratorInterface and defining the generator in your services.yml file with the tag vivait_generator.generator and an alias, which will be used to identify the Generator in annotations.

vivait_generator.generator.secure_bytes:
    class: Vivait\StringGeneratorBundle\Generator\SecureBytesGenerator
    tags:
        - { name: vivait_generator.generator, alias: 'secure_bytes' }

To create configurable generators, implement ConfigurableGeneratorInterface. This interface uses
Symfony\Component\OptionsResolver\OptionsResolver to set the generator configuration.

Set default options:

/**
 * @param OptionsResolver $resolver
 */
public function getDefaultOptions(OptionsResolver $resolver)
{
  $resolver->setDefaults(
      [
        'chars'  => $this->chars,
        'length' => $this->length,
        'prefix' => $this->prefix,
      ]
  );
}

Do something with options:

/**
 * @param array $options
 */
public function setOptions(array $options)
{
    $this->chars  = $options['chars'];
    $this->length = $options['length'];
    $this->prefix = $options['prefix'];
}
MIT License

Copyright (c) 2017 Viva IT Limited

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
  • Merge pull request #34 from terox/fix-appbundle-namespace
    By web-flow, 1 year ago
  • Fix AppBundle namespace issue
    By terox, 1 year ago
  • Merge pull request #30 from terox/uuid-generator
    By web-flow, 1 year ago
  • Remove empty constructor
    By web-flow, 1 year ago
  • Remove unused function
    By web-flow, 1 year ago
  • Change readme
    By web-flow, 1 year ago
  • Add compose require ramsey/uuid into travis.yml
    By terox, 1 year ago
  • Fix new services declaration
    By terox, 1 year ago
  • Merge branch 'master' into uuid-generator
    By web-flow, 1 year ago
  • Add documentation for UUID generator
    By terox, 1 year ago
  • Made uuid generator optional (suggest via composer)
    By terox, 1 year ago
  • Merge pull request #33 from leightonthomas/feature/compiler-pass
    By web-flow, 2 years ago
  • Updates composer json
    By , 2 years ago
  • Docblock
    By leightonthomas, 2 years ago
  • Removes unnecessary thing
    By leightonthomas, 2 years ago
  • Re-adds legacy support for bc
    By leightonthomas, 2 years ago
  • Adds configuration back
    By leightonthomas, 2 years ago
  • Adds a compiler pass for generators rather than config (removes need for default configuration)
    By leightonthomas, 2 years ago
  • Merge pull request #32 from leightonthomas/fix/31-reflection-object
    By web-flow, 2 years ago
  • Fixes the issue
    By leightonthomas, 2 years ago
  • Formatting
    By leightonthomas, 2 years ago
  • UUID Generator
    By terox, 2 years ago
  • Merge branch 'master-up' into uuid-generator
    By terox, 2 years ago
  • Add UuidGenerator
    By terox, 2 years ago
  • Merge pull request #29 from Brunty/patch-1
    By web-flow, 2 years ago
  • Update README with travis badge
    By web-flow, 2 years ago
  • Added MIT license
    By web-flow, 2 years ago
  • Update README.md
    By web-flow, 2 years ago
  • Set theme jekyll-theme-slate
    By , 2 years ago
  • Merge pull request #28 from terox/master
    By web-flow, 2 years ago