Merge branch 'feature/member-or-null-by' into develop

eloquent · Mar 13, 2014 · 7c72610 · 7c72610
2 parents 188bb27 + 9e266d2
commit 7c72610
Show file tree

Hide file tree

Showing 7 changed files with 317 additions and 143 deletions.
diff --git a/.travis.install b/.travis.install
@@ -1,10 +1,14 @@
 #!/usr/bin/env php
 <?php
-/**
- * This script is executed before composer dependencies are installed,
- * and as such must be included in each project as part of the skeleton.
- */
 
+// Update git to the latest version ...
+passthru('sudo apt-get update');
+passthru('sudo apt-get install git');
+
+// Update composer to the latest version ...
+passthru('composer self-update --no-interaction');
+
+// Build a composer config that uses the GitHub OAuth token if it is available ...
 $config = array(
     'config' => array(
         'notify-on-install' => false
@@ -16,20 +20,23 @@ if ($token = getenv('ARCHER_TOKEN')) {
         'github.com' => $token
     );
     $composerFlags = '--prefer-dist';
-    passthru('curl -s -i -H "Authorization: token $ARCHER_TOKEN" https://api.github.com | grep "^X-RateLimit"');
 } else {
     $composerFlags = '--prefer-source';
 }
 
 $file = '~/.composer/config.json';
-$dir  = dirname($file);
+$dir = dirname($file);
 if (!is_dir($dir)) {
     mkdir($dir, 0755, true);
 }
 file_put_contents($file, json_encode($config));
 
-passthru('composer self-update --no-interaction');
+// Display some information about GitHub rate limiting ...
+if ($token) {
+    passthru('curl -s -i -H "Authorization: token $ARCHER_TOKEN" https://api.github.com | grep "^X-RateLimit"');
+}
 
+// Install composer dependencies ...
 $exitCode = 0;
 passthru('composer install --dev --no-progress --no-interaction --ansi ' . $composerFlags, $exitCode);
 exit($exitCode);
diff --git a/.travis.yml b/.travis.yml
@@ -1,11 +1,3 @@
-#
-# This is the default Travis CI configuration.
-#
-# It uses a GitHub OAuth token when fetching composer dependencies
-# to avoid IP-based API throttling.
-#
-# It also allows publication of artifacts via an additional build.
-#
 language: php
 
 php: ["5.3", "5.4", "5.5", "hhvm"]
@@ -16,10 +8,11 @@ matrix:
 
 env:
   global:
-    - ARCHER_PUBLISH_VERSION=5.4
+    - ARCHER_PUBLISH_VERSION=5.5
     - secure: "RshLtPfJvPQyIxEsUXlBc/DEfv2uEBvr2gf4Ml6qIbnCjeGUknyhGpjm/oLn4gL0lonTC3gLhT3PVkZG8yTCjFrThnLPucty9LFT4hLfqH2JTSrqYWc57sS3EuaAbjYUo/UtKV9QQTBm3TQYuWGKamzTnNtNM6lITrL19zfcAbM="
 
 install:
   - ./.travis.install
+
 script:
   - ./vendor/bin/archer travis:build
diff --git a/src/AbstractMultiton.php b/src/AbstractMultiton.php
@@ -19,22 +19,6 @@
  */
 abstract class AbstractMultiton implements MultitonInterface
 {
-    /**
-     * Returns an array of all members in this multiton.
-     *
-     * @return array<string,MultitonInterface> All members.
-     */
-    final public static function members()
-    {
-        $class = get_called_class();
-        if (!array_key_exists($class, self::$members)) {
-            self::$members[$class] = array();
-            static::initializeMembers();
-        }
-
-        return self::$members[$class];
-    }
-
     /**
      * Returns a single member by string key.
      *
@@ -72,6 +56,23 @@ final public static function memberByKeyWithDefault(
         );
     }
 
+    /**
+     * Returns a single member by string key. Additionally returns null if the
+     * supplied key is null.
+     *
+     * @param string|null  $key             The string key associated with the member, or null.
+     * @param boolean|null $isCaseSensitive True if the search should be case sensitive.
+     *
+     * @return MultitonInterface|null                      The member associated with the given string key, or null if the supplied key is null.
+     * @throws Exception\UndefinedMemberExceptionInterface If no associated member is found.
+     */
+    final public static function memberOrNullByKey(
+        $key,
+        $isCaseSensitive = null
+    ) {
+        return static::memberOrNullBy('key', $key, $isCaseSensitive);
+    }
+
     /**
      * Returns a single member by comparison with the result of an accessor
      * method.
@@ -147,41 +148,40 @@ function (MultitonInterface $member) use (
     }
 
     /**
-     * Returns a set of members by comparison with the result of an accessor
-     * method.
+     * Returns a single member by comparison with the result of an accessor
+     * method. Additionally returns null if the supplied value is null.
      *
      * @param string       $property        The name of the property (accessor method) to match.
-     * @param mixed        $value           The value to match.
+     * @param mixed        $value           The value to match, or null.
      * @param boolean|null $isCaseSensitive True if the search should be case sensitive.
      *
-     * @return array<string,MultitonInterface> All members for which $member->{$property}() === $value.
+     * @return MultitonInterface|null                      The first member for which $member->{$property}() === $value, or null if the supplied value is null.
+     * @throws Exception\UndefinedMemberExceptionInterface If no associated member is found.
      */
-    final public static function membersBy(
+    final public static function memberOrNullBy(
         $property,
         $value,
         $isCaseSensitive = null
     ) {
-        if (null === $isCaseSensitive) {
-            $isCaseSensitive = true;
-        }
-        if (!$isCaseSensitive && is_scalar($value)) {
-            $value = strtoupper(strval($value));
-        }
+        $member = static::memberByWithDefault(
+            $property,
+            $value,
+            null,
+            $isCaseSensitive
+        );
+        if (null === $member) {
+            if (null === $value) {
+                return null;
+            }
 
-        return static::membersByPredicate(
-            function (MultitonInterface $member) use (
+            throw static::createUndefinedMemberException(
+                get_called_class(),
                 $property,
-                $value,
-                $isCaseSensitive
-            ) {
-                $memberValue = $member->{$property}();
-                if (!$isCaseSensitive && is_scalar($memberValue)) {
-                    $memberValue = strtoupper(strval($memberValue));
-                }
+                $value
+            );
+        }
 
-                return $memberValue === $value;
-            }
-        );
+        return $member;
     }
 
     /**
@@ -228,6 +228,60 @@ final public static function memberByPredicateWithDefault(
         return $default;
     }
 
+    /**
+     * Returns an array of all members in this multiton.
+     *
+     * @return array<string,MultitonInterface> All members.
+     */
+    final public static function members()
+    {
+        $class = get_called_class();
+        if (!array_key_exists($class, self::$members)) {
+            self::$members[$class] = array();
+            static::initializeMembers();
+        }
+
+        return self::$members[$class];
+    }
+
+    /**
+     * Returns a set of members by comparison with the result of an accessor
+     * method.
+     *
+     * @param string       $property        The name of the property (accessor method) to match.
+     * @param mixed        $value           The value to match.
+     * @param boolean|null $isCaseSensitive True if the search should be case sensitive.
+     *
+     * @return array<string,MultitonInterface> All members for which $member->{$property}() === $value.
+     */
+    final public static function membersBy(
+        $property,
+        $value,
+        $isCaseSensitive = null
+    ) {
+        if (null === $isCaseSensitive) {
+            $isCaseSensitive = true;
+        }
+        if (!$isCaseSensitive && is_scalar($value)) {
+            $value = strtoupper(strval($value));
+        }
+
+        return static::membersByPredicate(
+            function (MultitonInterface $member) use (
+                $property,
+                $value,
+                $isCaseSensitive
+            ) {
+                $memberValue = $member->{$property}();
+                if (!$isCaseSensitive && is_scalar($memberValue)) {
+                    $memberValue = strtoupper(strval($memberValue));
+                }
+
+                return $memberValue === $value;
+            }
+        );
+    }
+
     /**
      * Returns a set of members by predicate callback.
      *

diff --git a/src/AbstractValueMultiton.php b/src/AbstractValueMultiton.php
@@ -31,19 +31,6 @@ final public static function memberByValue($value, $isCaseSensitive = null)
         return static::memberBy('value', $value, $isCaseSensitive);
     }
 
-    /**
-     * Returns a set of members matching the supplied value.
-     *
-     * @param scalar       $value           The value associated with the members.
-     * @param boolean|null $isCaseSensitive True if the search should be case sensitive.
-     *
-     * @return array<string,ValueMultitonInterface> All members with the supplied value.
-     */
-    final public static function membersByValue($value, $isCaseSensitive = null)
-    {
-        return static::membersBy('value', $value, $isCaseSensitive);
-    }
-
     /**
      * Returns a single member by value. Additionally returns a default if no
      * associated member is found.
@@ -67,6 +54,36 @@ final public static function memberByValueWithDefault(
         );
     }
 
+    /**
+     * Returns a single member by value. Additionally returns null if the
+     * supplied value is null.
+     *
+     * @param scalar|null  $value           The value associated with the member, or null.
+     * @param boolean|null $isCaseSensitive True if the search should be case sensitive.
+     *
+     * @return ValueMultitonInterface|null        The first member with the supplied value, or null if the supplied value is null.
+     * @throws Exception\UndefinedMemberException If no associated member is found.
+     */
+    final public static function memberOrNullByValue(
+        $value,
+        $isCaseSensitive = null
+    ) {
+        return static::memberOrNullBy('value', $value, $isCaseSensitive);
+    }
+
+    /**
+     * Returns a set of members matching the supplied value.
+     *
+     * @param scalar       $value           The value associated with the members.
+     * @param boolean|null $isCaseSensitive True if the search should be case sensitive.
+     *
+     * @return array<string,ValueMultitonInterface> All members with the supplied value.
+     */
+    final public static function membersByValue($value, $isCaseSensitive = null)
+    {
+        return static::membersBy('value', $value, $isCaseSensitive);
+    }
+
     /**
      * Returns the value of this member.
      *