Merge branch 'develop'

jeremykendall · Mar 25, 2015 · 41c0a34 · 41c0a34
2 parents 69d610f + 3389164
commit 41c0a34
Show file tree

Hide file tree

Showing 16 changed files with 312 additions and 178 deletions.
diff --git a/.php_cs b/.php_cs
@@ -0,0 +1,15 @@
+<?php
+
+require_once './vendor/autoload.php';
+
+$finder = \Symfony\CS\Finder\DefaultFinder::create()
+    ->in('src/');
+
+return \Symfony\CS\Config\Config::create()
+    ->setUsingCache(true)
+    ->fixers([
+        '-concat_without_spaces', 
+        'concat_with_spaces', 
+        'ordered_use',
+    ])
+    ->finder($finder);
diff --git a/.travis.yml b/.travis.yml
@@ -4,6 +4,7 @@ php:
   - 5.3
   - 5.4
   - 5.5
+  - 5.6
 
 before_script:
   - composer self-update

diff --git a/README.md b/README.md
@@ -1,59 +1,70 @@
 # Slim Auth [![Build Status](https://travis-ci.org/jeremykendall/slim-auth.png?branch=master)](https://travis-ci.org/jeremykendall/slim-auth) [![Coverage Status](https://coveralls.io/repos/jeremykendall/slim-auth/badge.png?branch=master)](https://coveralls.io/r/jeremykendall/slim-auth?branch=master) [![Dependencies Status](https://depending.in/jeremykendall/slim-auth.png)](http://depending.in/jeremykendall/slim-auth)
 
 Slim Auth is an authorization and authentication library for the [Slim Framework][1].
-Authentication is accomplished by using the Zend Framework [Authentication][2] 
-component, and authorization by using the Zend Framework [Acl][3] component.
+Authentication is provided by the Zend Framework [Zend\Authentication][2] 
+component, and authorization by the Zend Framework [Zend\Permissions\Acl][3] component.
 
-## DOCUMENTATION INCOMPLETE
+## Fair Warning: Documentation Mostly Complete 
 
-This lib is usable, but is beta software, and this documentation is incomplete.
-If you're *extremely* familiar with Zend Auth and Zend ACL, you can probably work 
-it out just fine.  Otherwise, you might want to wait for the docs to be completed.
+Slim Auth is fully functional and production ready (I've used it in production
+in multiple projects), but this documentation is incomplete. (Current status of
+the documentation is ~90% complete.)
+
+If you're familiar with [Zend\Authentication][2] and [Zend\Permissions\Acl][3], you'll be able to implement the library without any trouble. Otherwise, you might want to wait for the docs to be completed (no ETA) or open a GitHub issue with any questions or problems you encounter.
 
 Caveat emptor and all that. 
 
-## Installation
+## Slim SessionCookie No Longer Recomended
 
-Install composer in your project:
+**TL;DR**: You *will* experience unexpected behavior if you use 
+`Zend\Authentication\Storage\Session` as your auth storage and 
+`Slim\Middleware\SessionCookie` to provide encrypted cookies when your Slim
+version is >= 2.6.  
 
-```
-curl -s https://getcomposer.org/installer | php
-```
+Earlier versions of this documentation (and the [sample implementation][10])
+demonstrated the use of Slim's [SessionCookie Middleware](http://docs.slimframework.com/#Cookie-Session-Store) as a way to handle session storage in concert with Zend Session. As of [Slim 2.6.0](https://github.com/slimphp/Slim/releases/tag/2.6.0), 
+Zend Session and Slim's SessionCookie middleware no longer play well together,
+and I've opted for a Zend Session only approach.
+
+## Requirements
+
+Slim Auth works with all versions of Slim 2 >= 2.4.2. Slim Auth has not been
+tested against the upcoming Slim 3 release.
+
+## Example Implementation
 
-Create a composer.json file in your project root:
+I've put together an example implementation to demonstrate the library in
+action.  The example implementation can be found [here][10].
+
+## Installation
+
+Installation is provided via [Composer][11].
+
+First, install Composer.
 
 ```
-{
-    "require": {
-        "jeremykendall/slim-auth": "*"
-    }
-}
+curl -s https://getcomposer.org/installer | php
 ```
 
-(*Please check Packagist for the [most recent version of Slim Auth][6]*)
-
-Install via composer:
+Then install Slim Auth with the following Composer command.
 
 ```
-php composer.phar install
+composer require jeremykendall/slim-auth
 ```
 
-Add this line to your application’s index.php file:
+Finally, add this line at the top of your application’s index.php file:
 
 ```
-<?php
 require 'vendor/autoload.php';
 ```
 
 ## Preparing Your App For Slim Auth
 
-# Configuring Password Validator
-
 ### Database
 
 Your database should have a user table, and that table must have a `role`
 column.  The contents of the `role` column should be a string and correspond to
-the roles in your ACL. The user table name and all other column names are up to you.
+the roles in your ACL. The table name and all other column names are up to you.
 
 Here's an example schema for a user table. If you don't already have a user
 table, feel free to use this one:
@@ -70,12 +81,9 @@ CREATE TABLE IF NOT EXISTS [users] (
 ### ACL
 
 An Access Control List, or ACL, defines the set of rules that determines which group
-of users have access to which routes within your Slim application. Below is an
-example ACL suitable for an extremely simple app.  Please pay special attention
-to the comments.
+of users have access to which routes within your Slim application. Below is a very simple example ACL. Please pay special attention to the comments.
 
-*Please refer to the [Zend ACL documentation][3] for complete details on using
-their ACL component.*
+*Please refer to the [Zend\Permissions\Acl documentation][3] for complete details on using the Zend Framework ACL component.*
 
 ```
 namespace Example;
@@ -103,7 +111,7 @@ class Acl extends ZendAcl
 
         // APPLICATION PERMISSIONS
         // Now we allow or deny a role's access to resources. The third argument
-        // is 'privilege'. We're using HTTP method for resources.
+        // is 'privilege'. We're using HTTP method as 'privilege'.
         $this->allow('guest', '/', 'GET');
         $this->allow('guest', '/login', array('GET', 'POST'));
         $this->allow('guest', '/logout', 'GET');
@@ -119,7 +127,7 @@ class Acl extends ZendAcl
 #### The Guest Role
 
 Please note the `guest` role. **You must use the name** `guest` **as the role
-assigned to an unauthenticated user**. The other role names are yours to choose.
+assigned to unauthenticated users**. The other role names are yours to choose.
 
 #### Acl "Privileges"
 
@@ -129,34 +137,26 @@ adding the third argument, you are restricting route access by HTTP method.  If
 you do not provide an HTTP verb or verbs, you are allowing access to the
 specified route via *all* HTTP methods. **Be extremely vigilant here.** You
 wouldn't want to accidentally allow a 'guest' role access to an admin `DELETE`
-route simply because it references a public resource.
+route simply because you forgot to explicitly deny the `DELETE` route.
 
 ## Configuring Slim Auth: Defaults
 
 Now that you have a user database table with a `role` column and an ACL, you're
 ready to configure Slim Auth and add it to your application.
 
-First, add `use` statements for the PDO adapter and the Slim Auth Bootstrap.
+First, add `use` statements for the PasswordValidator (from the 
+[Password Validator][9] library), the PDO adapter, and the Slim Auth Bootstrap.
 
 ```
+use JeremyKendall\Password\PasswordValidator;
 use JeremyKendall\Slim\Auth\Adapter\Db\PdoAdapter;
 use JeremyKendall\Slim\Auth\Bootstrap;
 ```
 
-Next, create your Slim application with `cookies.encrypt` and
-`cookies.secret_key` as a minimum configuration.
-
->*Default Slim Auth identity storage is session storage. You MUST set the
->following cookie encryption settings if you use the SessionCookie middleware,
->which this example does. Details on configuring different storage are available
->later in the documentation.*
+Next, create your Slim application.
 
 ```
-$app = new \Slim\Slim(array(
-    // Config requirements for default Slim Auth implementation
-    'cookies.encrypt' => true,
-    'cookies.secret_key' => 'CHANGE ME. SERIOUSLY, CHANGE ME RIGHT NOW.',
-));
+$app = new \Slim\Slim();
 ```
 
 ### Authentication Adapter
@@ -166,27 +166,30 @@ From the Zend Authentication documentation:
 > `Zend\Authentication` adapters are used to authenticate against a particular
 > type of authentication service, such as LDAP, RDBMS, or file-based storage.
 
-Slim Auth provides an RDBMS authentication adapter for PDO. The constructor
-accepts four required arguments:
+Slim Auth provides an RDBMS authentication adapter for [PDO][12]. The constructor
+accepts five required arguments:
 
 * A `\PDO` instance
 * The name of the user table
 * The name of the identity, or username, column
 * The name of the credential, or password, column
+* An instance of `JeremyKendall\Password\PasswordValidator`
 
 ```
 $db = new \PDO(<database connection info>);
-$adapter = new PdoAdapter($db, <user table name>, <identity column name>, <credential column name>);
+$adapter = new PdoAdapter(
+    $db, 
+    <user table name>, 
+    <identity column name>, 
+    <credential column name>, 
+    new PasswordValidator()
+);
 ```
 
-#### Credential Validation Callback
-
-There is an optional fifth parameter: `$credentialValidationCallback`. If you
-do not provide a callback (and it's recommended that you don't), Slim Auth uses
-PHP's new password hash functionality by default. If you're not able to use
-PHP 5.5's new password hashing functions *and* your version of PHP doesn't
-support the userland implementation [password_compat][8], then you'll need to
-provide your own credential validation functionality via a callback.
+> **NOTE**: Please refer to the [Password Validator documentation][9] for more
+> information on the proper use of the library. If you choose not to use the 
+> Password Validator library, you will need to create your own authentication 
+> adapter.
 
 ### Putting it all Together
 
@@ -198,19 +201,6 @@ $authBootstrap = new Bootstrap($app, $adapter, $acl);
 $authBootstrap->bootstrap();
 ```
 
-Finally, and this is *crucial*, you *must* add Slim's [SessionCookie][7]
-Middleware, and you must add it  *after* the Slim Auth `Boostrap::bootstrap()`
-method has been called. 
-
-> **NOTE**: This is only a requirement if you're using the default Session
-> Storage *and* you opt to use the `SessionCookie` middleware.  It is possible to
-> configure Slim Auth to use storage other than Slim's SessionCookie.
-
-```
-// Add the session cookie middleware *after* auth to ensure it's executed first
-$app->add(new \Slim\Middleware\SessionCookie());
-```
-
 ### Login Route
 
 You'll need a login route, of course, and it's important that you name your
@@ -262,11 +252,22 @@ $app->get('/logout', function () use ($app) {
 });
 ```
 
+## And Done
+
+That should get you most of the way. I'll complete documentation as soon as I'm
+able, but can't currently commit to an ETA. Again, please feel free to open and
+issue with any questions you might have regarding implementation. 
+
+Thanks for considering Slim Auth for your project.
+
 [1]: http://slimframework.com/
-[2]: http://framework.zend.com/manual/2.2/en/modules/zend.authentication.intro.html
-[3]: http://framework.zend.com/manual/2.2/en/modules/zend.permissions.acl.intro.html
+[2]: http://framework.zend.com/manual/current/en/modules/zend.authentication.intro.html
+[3]: http://framework.zend.com/manual/current/en/modules/zend.permissions.acl.intro.html
 [4]: http://docs.slimframework.com/#Route-Names
 [5]: http://docs.slimframework.com/#Route-Helpers
 [6]: https://packagist.org/packages/jeremykendall/slim-auth
-[7]: http://docs.slimframework.com/#Cookie-Session-Store
 [8]: https://github.com/ircmaxell/password_compat
+[9]: https://github.com/jeremykendall/password-validator
+[10]: https://github.com/jeremykendall/slim-auth-impl
+[11]: http://getcomposer.org
+[12]: http://php.net/manual/en/book.pdo.php
diff --git a/build.properties b/build.properties
@@ -0,0 +1,2 @@
+project.basedir = .
+passthru = true
diff --git a/build.xml b/build.xml
@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<project name="Slim Auth" default="build">
+
+    <property file="build.properties" />
+
+    <fileset id="src" dir="${project.basedir}/src">
+        <include name="**/*.php" />
+    </fileset>
+
+    <target name="clean" description="Clean build path">
+        <delete dir="${project.basedir}/build" />
+        <mkdir dir="${project.basedir}/build" />
+        <mkdir dir="${project.basedir}/build/docs" />
+        <mkdir dir="${project.basedir}/build/cache" />
+        <mkdir dir="${project.basedir}/build/coverage" />
+        <mkdir dir="${project.basedir}/build/logs" />
+    </target>
+
+    <target name="phplint" description="Running php lint check">
+        <phplint haltonfailure="true">
+            <fileset refid="src" />
+        </phplint>
+    </target>
+
+    <target name="phpunit" description="Running unit tests">
+        <exec
+            passthru="${passthru}"
+            dir="${project.basedir}"
+            command="phpunit
+                --log-junit=${project.basedir}/build/logs/junit.xml
+                --coverage-clover=${project.basedir}/build/logs/clover.xml
+                --coverage-html=${project.basedir}/build/coverage" />
+    </target>
+
+    <target name="php-cs-fixer" description="Fix CS violations">
+        <exec
+            passthru="${passthru}"
+            dir="${project.basedir}"
+            command="php-cs-fixer fix --verbose" />
+    </target>
+
+    <target name="phpdoc" description="Generate API documentation">
+        <exec passthru="${passthru}" command="phpdoc --force" />
+    </target>
+
+    <target name="phpunit-gen-report">
+        <phpunitreport
+            infile="${project.basedir}/build/logs/junit.xml"
+            format="frames"
+            todir="${project.basedir}/build/logs"
+            />
+    </target>
+
+    <target name="phpcpd" description="Copy/Paste detection">
+        <phpcpd>
+            <fileset refid="src" />
+            <formatter
+                type="pmd"
+                outfile="${project.basedir}/build/logs/pmd-cpd.xml" />
+        </phpcpd>
+    </target>
+
+    <target name="phploc" description="Generate phploc.csv">
+        <phploc reportType="csv" reportName="phploc" reportDirectory="${project.basedir}/build/logs">
+            <fileset refid="src" />
+        </phploc>
+    </target>
+
+    <target name="phpmd" description="Mess detection">
+        <exec
+            passthru="${passthru}"
+            dir="${project.basedir}/src"
+            command="phpmd ${project.basedir}/src xml cleancode,codesize,controversial,design,naming,unusedcode
+            --suffixes .php
+            --reportfile ${project.basedir}/build/logs/pmd.xml" />
+    </target>
+
+    <target name="build" description="Build app">
+        <phingCall target="clean" />
+        <phingCall target="phplint" />
+        <phingCall target="php-cs-fixer" />
+        <phingCall target="phpunit" />
+        <phingCall target="phpunit-gen-report" />
+        <phingCall target="phpcpd" />
+        <phingCall target="phpmd" />
+        <phingCall target="phploc" />
+        <phingCall target="phpdoc" />
+    </target>
+</project>