Merge branch 'release/0.1.0'

.gitattributes

@@ -0,0 +1,7 @@
+# archer start
+.gitattributes export-ignore
+.gitignore export-ignore
+.travis.* export-ignore
+.archer.* export-ignore
+test export-ignore
+# archer end

.gitignore

@@ -0,0 +1,4 @@
+# archer start
+/artifacts/
+/vendor/
+# archer end

.travis.env

@@ -0,0 +1 @@
+VDXTEt7oKcHudzoec6cJN0f8unJYNYlkOphGq2BE9waA0RjfmjhyxYwomw21hep1ZK8PPpoMRzGAyDSjc6l5lMeR7gnHcygQoPbBDtBVgv+oWg12cUaSXP6jvcMArGmnyIYPxYduzKmXA2/b0Jtsc4B5eEwGjM1AJIMqFQ/GBa8=

.travis.install

@@ -0,0 +1,35 @@
+#!/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.
+ */
+
+$config = array(
+    'config' => array(
+        'notify-on-install' => false
+    )
+);
+
+if ($token = getenv('ARCHER_TOKEN')) {
+    $config['config']['github-oauth'] = array(
+        '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);
+if (!is_dir($dir)) {
+    mkdir($dir, 0755, true);
+}
+file_put_contents($file, json_encode($config));
+
+passthru('composer self-update --no-interaction');
+
+$exitCode = 0;
+passthru('composer install --dev --no-progress --no-interaction --ansi ' . $composerFlags, $exitCode);
+exit($exitCode);

.travis.key

@@ -0,0 +1,6 @@
+-----BEGIN RSA PUBLIC KEY-----
+MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCd9XqLxYxIogG4BcMCFi8+Ggoh
+4XkykyvQB9NfvdtYGQN6mSHYTHePCouigrwUMsShJP08YBJbatHvE07gOUTeNtAn
+415ho+3NN5IpcvlCu9eKN7nQwdpBQVmCzyAIubdtdeZt3dEE3u7Q7LD8dHX83ejK
+vcbVUzn0Ni93pYbD+QIDAQAB
+-----END RSA PUBLIC KEY-----

.travis.yml

@@ -0,0 +1,21 @@
+#
+# 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"]
+
+env:
+  global:
+    - ARCHER_PUBLISH_VERSION=5.5
+    - secure: "VDXTEt7oKcHudzoec6cJN0f8unJYNYlkOphGq2BE9waA0RjfmjhyxYwomw21hep1ZK8PPpoMRzGAyDSjc6l5lMeR7gnHcygQoPbBDtBVgv+oWg12cUaSXP6jvcMArGmnyIYPxYduzKmXA2/b0Jtsc4B5eEwGjM1AJIMqFQ/GBa8="
+
+install:
+  - ./.travis.install
+script:
+  - ./vendor/bin/archer travis:build

CHANGELOG.md

@@ -0,0 +1,5 @@
+# Constance changelog
+
+## 0.1.0 (2013-11-11)
+
+- **[NEW]** Initial implementation.

CONTRIBUTING.md

@@ -0,0 +1,29 @@
+# Contributing
+
+**Constance** is open source software; contributions from the community are
+encouraged. Please take a moment to read these guidelines before submitting
+changes.
+
+### Code style
+
+All PHP code must adhere to the
+[PSR-2](https://github.com/php-fig/fig-standards/blob/master/accepted/PSR-2-coding-style-guide.md)
+standards.
+
+### Branching and pull requests
+
+As a guideline, please follow this process:
+
+ 1. [Fork the repository](https://help.github.com/articles/fork-a-repo).
+ 2. Create a topic branch for the change:
+    * New features should branch from **develop**.
+    * Bug fixes to existing versions should branch from **master**.
+    * Please ensure the branch is clearly labelled as a feature or fix.
+ 3. Make the relevant changes.
+ 4. [Squash](http://git-scm.com/book/en/Git-Tools-Rewriting-History#Changing-Multiple-Commit-Messages)
+    commits if necessary.
+ 4. Submit a pull request to the **develop** branch.
+
+Please note this is a general guideline only. For more information on the
+branching structure please see the
+[git-flow cheatsheet](http://danielkummer.github.com/git-flow-cheatsheet/).

LICENSE

@@ -0,0 +1,19 @@
+Copyright © 2013 Erin Millard
+
+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.

README.md

@@ -0,0 +1,187 @@
+# Constance
+
+*PHP constants as enumerations.*
+
+[![Build status]][Latest build]
+[![Test coverage]][Test coverage report]
+[![Uses semantic versioning]][SemVer]
+
+## Installation and documentation
+
+* Available as [Composer] package [eloquent/constance].
+* [API documentation] available.
+
+## What is Constance?
+
+*Constance* is a library for representing PHP constants as an [enumerated type].
+*Constance* supports both class-level and global constants, and is built upon
+a powerful [enumeration library] to provide a rich feature set.
+
+Amongst other uses, *Constance* allows a developer to:
+
+- Type hint for a valid value as defined in a pre-existing set of constants.
+  Examples include the PHP error levels, and PDO attributes.
+- Retrieve information about a constant from its value, such as its name (useful
+  for logging and debugging).
+- Perform simple operations on sets of constants with [bitwise] values,
+  including retrieving members by bit-mask, or composing a bit-mask from an
+  array of members.
+
+*Constance* is most useful for dealing with pre-defined constants that the
+developer has no control over. If it is within the developer's control to
+implement a first-class enumeration, then the recommended approach is to use
+an [enumeration library] directly.
+
+## Implementing an enumeration of constants
+
+*Constance* does not provide any concrete classes, but instead provides abstract
+base classes to make implementation of constant enumerations extremely
+simple. There are two abstract base classes - `AbstractClassConstant` for
+class-level constants, and `AbstractGlobalConstant` for global constants.
+
+### Class-level constants
+
+This example demonstrates how to define an enumeration of [PDO attributes]:
+
+```php
+use Eloquent\Constance\AbstractClassConstant;
+
+final class PdoAttribute extends AbstractClassConstant
+{
+    /**
+     * The class to inspect for constants.
+     */
+    const CONSTANCE_CLASS = 'PDO';
+
+    /**
+     * The expression used to match constant names that should be included in
+     * this enumeration.
+     */
+    const CONSTANCE_PATTERN = '{^ATTR_}';
+}
+```
+
+As the example demonstrates, *Constance* enumerations are extremely simple to
+implement. The constant `CONSTANCE_CLASS` tells *Constance* which class to
+inspect for constants, and the optional constant `CONSTANCE_PATTERN` is a
+regular expression used to limit which of the constants defined in
+`CONSTANCE_CLASS` are defined as members of this enumeration. In this particular
+case, the expression limits the members to constants starting with `ATTR_`.
+
+This enumeration can now be used to retrieve information about a PDO attribute
+constant when only its value is known at run-time:
+
+```php
+$attribute = PdoAttribute::memberByValue(PDO::ATTR_ERRMODE);
+
+echo $attribute->name();          // outputs 'ATTR_ERRMODE'
+echo $attribute->qualifiedName(); // outputs 'PDO::ATTR_ERRMODE'
+```
+
+`PdoAttribute` can also be used as a type hint that will only accept valid PDO
+attributes. Note the special static call syntax for accessing members of an
+enumeration:
+
+```php
+class MyConnection
+{
+    public function setAttribute(PdoAttribute $attribute, $value)
+    {
+        // ...
+    }
+}
+
+$connection = new MyConnection;
+$connection->setAttribute(PdoAttribute::ATTR_AUTOCOMMIT(), true);
+$connection->setAttribute(PdoAttribute::ATTR_PERSISTENT(), false);
+```
+
+### Global constants
+
+This example demonstrates how to define an enumeration of [PHP error levels]:
+
+```php
+use Eloquent\Constance\AbstractGlobalConstant;
+
+final class ErrorLevel extends AbstractGlobalConstant
+{
+    /**
+     * The expression used to match constant names that should be included in
+     * this enumeration.
+     */
+    const CONSTANCE_PATTERN = '{^E_}';
+}
+```
+
+Global constants are even simpler to implement than class-level constants.
+The optional constant `CONSTANCE_PATTERN` is a regular expression used to limit
+which globally defined constants are defined as members of this enumeration. In
+this particular case, the expression limits the members to constants starting
+with `E_`.
+
+The above enumeration will contain members for all the defined PHP error level
+constants, such as `E_NOTICE`, `E_WARNING`, `E_ERROR`, `E_ALL`, and `E_STRICT`.
+Note that *Constance* provides some limited [bitwise] helper methods for dealing
+with such sets of constants with bitwise values, which will be discussed in a
+separate section.
+
+## Bitwise logic
+
+*Constance* provides some methods for dealing with sets of constants that have
+[bitwise] values. The [PHP error levels] enumeration above serves as a good
+example of such a set.
+
+Assuming the `ErrorLevel` enumeration described above, the set of members
+included in `E_ALL` can be determined like so:
+
+```php
+$members = ErrorLevel::membersByBitmask(E_ALL);
+```
+
+`$members` now contains an array of enumeration members representing all the
+error levels included in `E_ALL` for the current run-time environment.
+Conversely, the members that are *not* included can be determined just as
+easily:
+
+```php
+$members = ErrorLevel::membersExcludedByBitmask(E_ALL);
+```
+
+A bit-mask can also be generated for an arbitrary set of enumeration members,
+like so:
+
+```php
+$members = array(ErrorLevel::E_NOTICE(), ErrorLevel::E_DEPRECATED());
+$bitmask = ErrorLevel::membersToBitmask($members);
+```
+
+`$bitmask` now contains a bit-mask that matches only `E_NOTICE` or
+`E_DEPRECATED`.
+
+Lastly, checking whether a given enumeration member matches a bit-mask is also
+extremely simple:
+
+```php
+$isStrictByDefault = ErrorLevel::E_STRICT()->valueMatchesBitmask(E_ALL);
+```
+
+`$isStrictByDefault` will now contain a boolean value indicating whether `E_ALL`
+includes strict standards warnings for the current run-time environment.
+
+<!-- References -->
+
+[bitwise]: http://en.wikipedia.org/wiki/Bitwise_operation
+[enumerated type]: http://en.wikipedia.org/wiki/Enumerated_type
+[enumeration library]: https://github.com/eloquent/enumeration
+[PDO attributes]: http://www.php.net/manual/en/pdo.constants.php
+[PHP error levels]: http://www.php.net/manual/en/errorfunc.constants.php
+
+[API documentation]: http://lqnt.co/constance/artifacts/documentation/api/
+[Build status]: https://api.travis-ci.org/eloquent/constance.png?branch=master
+[Composer]: http://getcomposer.org/
+[eloquent/constance]: https://packagist.org/packages/eloquent/constance
+[Latest build]: https://travis-ci.org/eloquent/constance
+[SemVer]: http://semver.org/
+[Test coverage report]: https://coveralls.io/r/eloquent/constance
+[Test coverage]: https://coveralls.io/repos/eloquent/constance/badge.png?branch=master
+[Uses semantic versioning]: http://b.repl.ca/v1/semver-yes-brightgreen.png

composer.json

@@ -0,0 +1,27 @@
+{
+    "name": "eloquent/constance",
+    "description": "PHP constants as enumerations.",
+    "keywords": ["constant", "enumeration", "enum", "name", "value"],
+    "homepage": "https://github.com/eloquent/constance",
+    "license": "MIT",
+    "authors": [
+        {
+            "name": "Erin Millard",
+            "email": "ezzatron@gmail.com",
+            "homepage": "http://ezzatron.com/"
+        }
+    ],
+    "require": {
+        "php": ">=5.3",
+        "eloquent/enumeration": "~5",
+        "icecave/isolator": "~2"
+    },
+    "require-dev": {
+        "icecave/archer": "~1"
+    },
+    "autoload": {
+        "psr-0": {
+            "Eloquent\\Constance": "src"
+        }
+    }
+}