Sylius/docs/components/Variation/basic_usage.rst

Basic Usage
===========

VariableInterface
-----------------

Let's see how an exemplary class implementing the **VariableInterface** should look like.

.. code-block:: php

    <?php

    use Doctrine\Common\Collections\ArrayCollection;
    use Doctrine\Common\Collections\Collection;
    use Sylius\Component\Variation\Model\OptionInterface;
    use Sylius\Component\Variation\Model\VariableInterface;
    use Sylius\Component\Variation\Model\VariantInterface;

    class Clothing implements VariableInterface
    {
        /**
         * @var string
         */
        private $name;

        /**
         * @var Collection
         */
        private $variants;

        /**
         * @var Collection
         */
        private $options;

        /**
         * @param string $name
         */
        public function __construct($name)
        {
            $this->name = $name;
            $this->variants = new ArrayCollection();
            $this->options = new ArrayCollection();
        }

        /**
         * {@inheritdoc}
         */
        public function hasVariants()
        {
            return !$this->variants->isEmpty();
        }

        /**
         * {@inheritdoc}
         */
        public function getVariants()
        {
            return $this->variants;
        }

        /**
         * {@inheritdoc}
         */
        public function setVariants(Collection $variants)
        {
            $this->variants = $variants;
        }

        /**
         * {@inheritdoc}
         */
        public function addVariant(VariantInterface $variant)
        {
            $this->variants->add($variant);
        }

        /**
         * {@inheritdoc}
         */
        public function removeVariant(VariantInterface $variant)
        {
            $this->variants->removeElement($variant);
        }

        /**
         * {@inheritdoc}
         */
        public function hasVariant(VariantInterface $variant)
        {
            return $this->variants->contains($variant);
        }

        /**
         * {@inheritdoc}
         */
        public function hasOptions()
        {
            return !$this->options->isEmpty();
        }

        /**
         * {@inheritdoc}
         */
        public function getOptions()
        {
            return $this->options;
        }

        /**
         * {@inheritdoc}
         */
        public function setOptions(Collection $options)
        {
            $this->options = $options;
        }

        /**
         * {@inheritdoc}
         */
        public function addOption(OptionInterface $option)
        {
            $this->options->add($option);
        }

        /**
         * {@inheritdoc}
         */
        public function removeOption(OptionInterface $option)
        {
            $this->options->removeElement($option);
        }

        /**
         * {@inheritdoc}
         */
        public function hasOption(OptionInterface $option)
        {
            return $this->options->contains($option);
        }
    }

.. _component_variation_generator_variant-generator:

VariantGenerator
----------------

A **VariantGenerator** is used to create all possible combinations of an object's options and to create ``Variant`` models from them.

**Example:**

If an object such as a T-shirt has 2 options - *Color* and *Size* - with 3 possible values per option,
then the generator will create 9 variants and assign them to the object.

The generator will ignore invalid variants or variants that already exist.

**T-Shirt Options**

+------------+----------+
| **Colors** | **Size** |
+------------+----------+
| Black      | Small    |
+------------+----------+
| White      | Medium   |
+------------+----------+
| Red        | Large    |
+------------+----------+

**Possible T-Shirt Variants**

These variants should be generated by the ``VariantGenerator`` from the options above:

1. Black, Small
2. Black, Medium
3. Black, Large
4. White, Small
5. White, Medium
6. White, Large
7. Red, Small
8. Red, Medium
9. Red, Large

.. code-block:: php

    <?php

    use Sylius\Component\Variation\Generator\VariantGenerator;
    use Sylius\Component\Variation\Model\VariableInterface;
    use Sylius\Component\Variation\SetBuilder\CartesianSetBuilder;
    use Sylius\Component\Resource\Repository\InMemoryRepository;

    $variantRepository = new InMemoryRepository();

    $setBuilder = new CartesianSetBuilder();

    $subject = new Clothing('T-Shirt');

    $colors = new Option();
    $colors->setValues(new ArrayCollection(array('White', 'Black', 'Red')));
    $colors->setName('Color');

    $sizes = new Option();
    $sizes->setValues(new ArrayCollection(array('Small', 'Medium', 'Large')));
    $sizes->setName('Size');

    $variable->addOption($colors);
    $variable->addOption($sizes);

    $generator = new VariantGenerator($variantRepository, $setBuilder);

    // Generate all possible variants if they don't exist yet.
    $generator->generate($variable)

.. note::

    The variant generator implements the :ref:`component_variation_generator_variant-generator-interface`.


.. note::

    The variant generator's set builder should implement the :ref:`component_variation_set-builder_set-builder-interface`.