--- /dev/null
+<?php
+
+namespace RedBeanPHP;
+
+use RedBeanPHP\ToolBox as ToolBox;
+use RedBeanPHP\OODBBean as OODBBean;
+
+/**
+ * Label Maker.
+ * Makes so-called label beans.
+ * A label is a bean with only an id, type and name property.
+ * Labels can be used to create simple entities like categories, tags or enums.
+ * This service class provides convenience methods to deal with this kind of
+ * beans.
+ *
+ * @file RedBeanPHP/LabelMaker.php
+ * @author Gabor de Mooij and the RedBeanPHP Community
+ * @license BSD/GPLv2
+ *
+ * @copyright
+ * copyright (c) G.J.G.T. (Gabor) de Mooij and the RedBeanPHP Community
+ * This source file is subject to the BSD/GPLv2 License that is bundled
+ * with this source code in the file license.txt.
+ */
+class LabelMaker
+{
+ /**
+ * @var ToolBox
+ */
+ protected $toolbox;
+
+ /**
+ * Constructor.
+ *
+ * @param ToolBox $toolbox
+ */
+ public function __construct( ToolBox $toolbox )
+ {
+ $this->toolbox = $toolbox;
+ }
+
+ /**
+ * A label is a bean with only an id, type and name property.
+ * This function will dispense beans for all entries in the array. The
+ * values of the array will be assigned to the name property of each
+ * individual bean.
+ *
+ * <code>
+ * $people = R::dispenseLabels( 'person', [ 'Santa', 'Claus' ] );
+ * </code>
+ *
+ * @param string $type type of beans you would like to have
+ * @param array $labels list of labels, names for each bean
+ *
+ * @return array
+ */
+ public function dispenseLabels( $type, $labels )
+ {
+ $labelBeans = array();
+ foreach ( $labels as $label ) {
+ $labelBean = $this->toolbox->getRedBean()->dispense( $type );
+ $labelBean->name = $label;
+ $labelBeans[] = $labelBean;
+ }
+
+ return $labelBeans;
+ }
+
+ /**
+ * Gathers labels from beans. This function loops through the beans,
+ * collects the value of the name property for each individual bean
+ * and stores the names in a new array. The array then gets sorted using the
+ * default sort function of PHP (sort).
+ *
+ * Usage:
+ *
+ * <code>
+ * $o1->name = 'hamburger';
+ * $o2->name = 'pizza';
+ * implode( ',', R::gatherLabels( [ $o1, $o2 ] ) ); //hamburger,pizza
+ * </code>
+ *
+ * Note that the return value is an array of strings, not beans.
+ *
+ * @param array $beans list of beans to loop through
+ *
+ * @return array
+ */
+ public function gatherLabels( $beans )
+ {
+ $labels = array();
+
+ foreach ( $beans as $bean ) {
+ $labels[] = $bean->name;
+ }
+
+ sort( $labels );
+
+ return $labels;
+ }
+
+ /**
+ * Fetches an ENUM from the database and creates it if necessary.
+ * An ENUM has the following format:
+ *
+ * <code>
+ * ENUM:VALUE
+ * </code>
+ *
+ * If you pass 'ENUM' only, this method will return an array of its
+ * values:
+ *
+ * <code>
+ * implode( ',', R::gatherLabels( R::enum( 'flavour' ) ) ) //'BANANA,MOCCA'
+ * </code>
+ *
+ * If you pass 'ENUM:VALUE' this method will return the specified enum bean
+ * and create it in the database if it does not exist yet:
+ *
+ * <code>
+ * $bananaFlavour = R::enum( 'flavour:banana' );
+ * $bananaFlavour->name;
+ * </code>
+ *
+ * So you can use this method to set an ENUM value in a bean:
+ *
+ * <code>
+ * $shake->flavour = R::enum( 'flavour:banana' );
+ * </code>
+ *
+ * the property flavour now contains the enum bean, a parent bean.
+ * In the database, flavour_id will point to the flavour record with name 'banana'.
+ *
+ * @param string $enum ENUM specification for label
+ *
+ * @return array|OODBBean
+ */
+ public function enum( $enum )
+ {
+ $oodb = $this->toolbox->getRedBean();
+
+ if ( strpos( $enum, ':' ) === FALSE ) {
+ $type = $enum;
+ $value = FALSE;
+ } else {
+ list( $type, $value ) = explode( ':', $enum );
+ $value = preg_replace( '/\W+/', '_', strtoupper( trim( $value ) ) );
+ }
+
+ /**
+ * We use simply find here, we could use inspect() in fluid mode etc,
+ * but this would be useless. At first sight it looks clean, you could even
+ * bake this into find(), however, find not only has to deal with the primary
+ * search type, people can also include references in the SQL part, so avoiding
+ * find failures does not matter, this is still the quickest way making use
+ * of existing functionality.
+ *
+ * @note There seems to be a bug in XDebug v2.3.2 causing suppressed
+ * exceptions like these to surface anyway, to prevent this use:
+ *
+ * "xdebug.default_enable = 0"
+ *
+ * Also see Github Issue #464
+ */
+ $values = $oodb->find( $type );
+
+ if ( $value === FALSE ) {
+ return $values;
+ }
+
+ foreach( $values as $enumItem ) {
+ if ( $enumItem->name === $value ) return $enumItem;
+ }
+
+ $newEnumItems = $this->dispenseLabels( $type, array( $value ) );
+ $newEnumItem = reset( $newEnumItems );
+
+ $oodb->store( $newEnumItem );
+
+ return $newEnumItem;
+ }
+}