Merge pull request #215 from GrahamCampbell/chaining

Chaining

README.md

@@ -40,7 +40,7 @@ This is the usage guide for Factory Muffin 2.0. Within this guide, you will see
 
 ### The Facade
 
-The facade class (`League\FactoryMuffin\Facade`) should always be your main point of entry for communicating with Factory Muffin. It will dynamically proxy static method calls to the underlying factory instance. The other classes, including the factory class (`League\FactoryMuffin\Factory`), are not intended for direct public use.
+The facade class (`League\FactoryMuffin\Facade`) should always be your main point of entry for communicating with Factory Muffin. It will dynamically proxy static method calls to the underlying factory instance. The other classes, including the factory class (`League\FactoryMuffin\Factory`), are not intended for direct public use. Also, note that all public methods that would have returned void, return the factory instance in order to support method chaining.
 
 ### Factory Definitions
 
@@ -126,8 +126,8 @@ class TestUserModel extends PHPUnit_Framework_TestCase
 {
     public static function setupBeforeClass()
     {
-        FactoryMuffin::setSaveMethod('save'); // optional step
-        FactoryMuffin::setFakerLocale('en_EN'); // optional step
+        // note that method chaining is supported
+        FactoryMuffin::setFakerLocale('en_EN')->setSaveMethod('save'); // optional step
         FactoryMuffin::loadFactories(__DIR__ . '/factories');
     }
 

UPGRADING.md

@@ -45,7 +45,7 @@ It also should be noted that we've moved from PSR-0 to PSR-4 for autoloading.
 
 ### Facade Changes
 
-Under it's new name, the facade class now uses `__callStatic` to dynamically call the underlying factory instance.
+Under it's new name, the facade class now uses `__callStatic` to dynamically call the underlying factory instance. Also, note that all public methods that would have returned void, return the factory instance in order to support method chaining.
 
 ### Factory Definitions
 

src/Facade.php

@@ -6,22 +6,23 @@
  * Class Facade.
  *
  * This is the main point of entry for using Factory Muffin.
- * This class dynamically proxies static method calls to the underlying factory instance.
+ * This class dynamically proxies static method calls to
+ * the underlying factory instance.
  *
  * @see League\FactoryMuffin\Factory
  *
- * @method static void setSaveMethod(string $method) Set the method we use when saving objects.
- * @method static void setDeleteMethod(string $method) Set the method we use when deleting objects.
+ * @method static Factory setSaveMethod(string $method) Set the method we use when saving objects.
+ * @method static Factory setDeleteMethod(string $method) Set the method we use when deleting objects.
  * @method static object[] seed(int $times, string $model, array $attr = array()) Returns multiple versions of an object.
  * @method static object create(string $model, array $attr = array()) Creates and saves in db an instance of the model.
  * @method static object[] saved() Return an array of saved objects.
  * @method static bool isSaved(object $object) Is the object saved?
- * @method static void deleteSaved() Call the delete method on any saved objects.
+ * @method static Factory deleteSaved() Call the delete method on any saved objects.
  * @method static object instance(string $model, array $attr = array()) Return an instance of the model.
  * @method static array attributesFor(object $object, array $attr = array()) Returns the mock attributes for the model.
- * @method static void define(string $model, array $definition = array()) Define a new model factory.
+ * @method static Factory define(string $model, array $definition = array()) Define a new model factory.
  * @method static string|object generateAttr(string $kind, object $object = null) Generate the attributes.
- * @method static void loadFactories(string|string[] $paths) Load the specified factories.
+ * @method static Factory loadFactories(string|string[] $paths) Load the specified factories.
  *
  * @package League\FactoryMuffin
  * @author  Zizaco <[email protected]>

src/Factory.php

@@ -19,8 +19,9 @@
 /**
  * Class Factory.
  *
- * This class is not intended to be used directly.
- * Please use the provided facade.
+ * This class is not intended to be used directly. Please
+ * use the provided facade. This class may be used a result
+ * of method chaining after initially using the facade.
  *
  * @package League\FactoryMuffin
  * @author  Zizaco <[email protected]>
@@ -77,38 +78,44 @@ class Factory
      *
      * @param string $local
      *
-     * @return void
+     * @return $this
      */
     public function setFakerLocale($local)
     {
         $this->fakerLocale = $local;
 
         // The faker class must be instantiated again with a new the new locale
         $this->faker = null;
+
+        return $this;
     }
 
     /**
      * Set the method we use when saving objects.
      *
      * @param string $method
      *
-     * @return void
+     * @return $this
      */
     public function setSaveMethod($method)
     {
         $this->saveMethod = $method;
+
+        return $this;
     }
 
     /**
      * Set the method we use when deleting objects.
      *
      * @param string $method
      *
-     * @return void
+     * @return $this
      */
     public function setDeleteMethod($method)
     {
         $this->deleteMethod = $method;
+
+        return $this;
     }
 
     /**
@@ -233,7 +240,7 @@ public function isSaved($object)
      *
      * @throws \League\FactoryMuffin\Exceptions\DeletingFailedException
      *
-     * @return void
+     * return $this
      */
     public function deleteSaved()
     {
@@ -255,6 +262,8 @@ public function deleteSaved()
         if ($exceptions) {
             throw new DeletingFailedException($exceptions);
         }
+
+        return $this;
     }
 
     /**
@@ -336,11 +345,13 @@ private function getFactoryAttrs($model)
      * @param string $model      Model class name.
      * @param array  $definition Array with definition of attributes.
      *
-     * @return void
+     * @return $this
      */
     public function define($model, array $definition = array())
     {
         $this->factories[$model] = $definition;
+
+        return $this;
     }
 
     /**
@@ -385,7 +396,7 @@ private function getFaker()
      *
      * @throws \League\FactoryMuffin\Exceptions\DirectoryNotFoundException
      *
-     * @return void
+     * @return $this
      */
     public function loadFactories($paths)
     {
@@ -396,6 +407,8 @@ public function loadFactories($paths)
 
             $this->loadDirectory($path);
         }
+
+        return $this;
     }
 
     /**

tests/AbstractTestCase.php

@@ -6,14 +6,11 @@ abstract class AbstractTestCase extends PHPUnit_Framework_TestCase
 {
     public static function setupBeforeClass()
     {
-        FactoryMuffin::setSaveMethod('save'); // optional step
-        FactoryMuffin::setFakerLocale('en_EN'); // optional step
         FactoryMuffin::loadFactories(__DIR__ . '/factories');
     }
 
     public static function tearDownAfterClass()
     {
-        FactoryMuffin::setDeleteMethod('delete'); // optional step
         FactoryMuffin::deleteSaved();
     }
 }

tests/DefinitionTest.php

@@ -13,6 +13,7 @@ public function testDefine()
     {
         $user = FactoryMuffin::create('UserModelStub');
 
+        $this->assertInstanceOf('UserModelStub', $user);
         $this->assertInternalType('string', $user->name);
         $this->assertInternalType('boolean', $user->active);
         $this->assertContains('@', $user->email);
@@ -22,6 +23,7 @@ public function testDefineMultiple()
     {
         $user = FactoryMuffin::create('UserModelStub');
 
+        $this->assertInstanceOf('UserModelStub', $user);
         $this->assertInternalType('string', $user->name);
         $this->assertInternalType('boolean', $user->active);
         $this->assertContains('@', $user->email);
@@ -30,18 +32,18 @@ public function testDefineMultiple()
     public function testSeed()
     {
         $users = FactoryMuffin::seed(2, 'UserModelStub');
+
         $this->assertCount(2, $users);
         $this->assertInstanceOf('UserModelStub', $users[0]);
         $this->assertInstanceOf('UserModelStub', $users[1]);
-
-        // Make sure these are not the same object returned twice for some reason
         $this->assertNotEquals($users[0], $users[1]);
     }
 
     public function testInstance()
     {
         $user = FactoryMuffin::instance('UserModelStub');
 
+        $this->assertInstanceOf('UserModelStub', $user);
         $this->assertInternalType('string', $user->name);
         $this->assertInternalType('boolean', $user->active);
         $this->assertContains('@', $user->email);
@@ -65,9 +67,10 @@ public function testFactoryLoading()
     {
         $count = count(get_included_files());
 
-        FactoryMuffin::loadFactories(__DIR__ . '/stubs');
+        $return = FactoryMuffin::loadFactories(__DIR__ . '/stubs');
 
         $this->assertSame(1, count(get_included_files()) - $count);
+        $this->assertInstanceOf('League\FactoryMuffin\Factory', $return);
     }
 
     public function testShouldThrowExceptionWhenLoadingANonexistentDirectory()

tests/SaveAndDeleteTest.php

@@ -35,7 +35,8 @@ public function testShouldNotSave()
      */
     public function testShouldThrowExceptionAfterSaveMethodRename()
     {
-        FactoryMuffin::setSaveMethod('foo');
+        $return = FactoryMuffin::setSaveMethod('foo');
+        $this->assertInstanceOf('League\FactoryMuffin\Factory', $return);
         try {
             FactoryMuffin::create($model = 'ModelThatWillSaveStub');
         } catch (SaveMethodNotFoundException $e) {
@@ -52,7 +53,8 @@ public function testShouldThrowExceptionAfterSaveMethodRename()
      */
     public function testShouldThrowExceptionAfterDeleteMethodRename()
     {
-        FactoryMuffin::setDeleteMethod('bar');
+        $return = FactoryMuffin::setDeleteMethod('bar');
+        $this->assertInstanceOf('League\FactoryMuffin\Factory', $return);
         FactoryMuffin::create($model = 'ModelThatWillSaveStub');
         try {
             FactoryMuffin::deleteSaved();